ESOE to Active Directory Authentication Handler Installation Guide

Authors
Andre Zitelli
Bradley Beddoes

Applicable versions
Beta 1

Configuring the SPNEGO handler for integrated Active Directory SSO

This section assumes the reader has a reasonably detailed understanding of the Kerberos V5 authentication protocol. Additionally, an understanding of the Microsoft GSS extension of Kerberos may be helpful. The SPNEGO handler is dependent on the existence of a Kerberos KDC and AS. At the time of writing, only an Active Directory KDC has been tested with the handler. Below are some articles that may be of assistance.

http://msdn2.microsoft.com/en-us/library/ms995329.aspx
http://web.mit.edu/kerberos/www/
http://unix.lsa.umich.edu/docs/mit-kerberos/install_3.html
http://www.upenn.edu/computing/pennkey/sysadmin/e_install_win/win-config.html
http://www.microsoft.com/technet/prodtechnol/windows2000serv/howto/kerbstep.mspx

There must be a an existing Kerberos server before the SPNEGO handler can be configured to a working state. Once you have the Kerberos server up and running, you may continue with handler the configuration.

Enabling the SPNEGOHandler

By default, the SPNEGO authentication mechanism is disabled. We recommend you extract the ESOE ROOT.war file supplied to you to enable the Active Directory connector. Steps for enabling the connector are as follows:

  1. Create a directory called ROOT in your home directory
  2. Copy ROOT.war to ROOT
  3. Change to the ROOT directory and execute "jar -xf ROOT.war"
  4. Delete ROOT.war
  5. File: WEB-INF/esoeContext.xml
    Uncomment <import resource="resources/authentication/handlers/authenticators/kerberosV5Authenticator.xml" />
    Uncomment <import resource="resources/authentication/handlers/SPNEGOHandler.xml" />
  6. File: WEB-INF/resources/authentication.xml
    Uncomment <ref bean="spnegoHandler" />
  7. Extract and untar the file esoeauthn-ad.tar.gz which you have retrieved from our downloads area and copy the jar esoeauthn-ad.jar to WEB-INF/lib
  8. Recreate the war by running the command "jar -cf ../ROOT.war *". This will create ROOT.war in the parent directory

We release updates to ESOE as the default packaged ROOT.war file, please be aware you'll need to undertake this process when you deploy updates

Configuring the Kerberos realm.

The SPNEGO Handler must be configured to talk to a specified Kerberos realm KDC. The location of the realm configuration files are specific to the platform being used to host the ESOE (usually /etc/krb5.conf on \*NIX). This is configured as a standard Kerberos V5 configuration file and will be picked up by the SPNEGO handler (or more correctly, by native Kerberos libraries used by the JVM) on startup for processing. See the configuration file provided with the ESOE (krb5.conf) application deployment for an example configuration.

Setting up the ESOE authentication Principal on the AD KDC

An account must exist on the AD KDC for communication between the ESOE and the KDC. This account will have an associated Kerberos format keytab file and SPN generated in order to perform kerberos validation of the client credentials. The following steps must be performed on the AD domain controller in order to allow the ESOE to communicate with the KDC.

  1. Create the account that will be used by the ESOE. A normal user account will do fine. The placement of the account within the domain structure of Active Directory is up to you.
  2. Map the user account to the KDC by running the ktpass command. The ktpass command will map default SPN's to the specified user and create a kerberos keytab file that must be used by the ESOE to authenticate against the target Kerberos AS.
Example:
ktpass princ HTTP/esoe-dev.qut.edu.au@ADDEV.QUT.EDU.AU rndPass out HTTP.esoe-dev.qut.edu.au.keytab ptype KRB5_NT_PRINCIPAL mapuser esoe
...........
Targeting domain controller: qutadgp01-dev.addev.qut.edu.au
Using legacy password setting method
Successfully mapped HTTP/esoe-dev.qut.edu.au to esoe.
Key created.
Output keytab to HTTP.esoe-dev.qut.edu.au.keytab:
Keytab version: 0x502
keysize 76 HTTP/esoe-dev.qut.edu.au@ADDEV.QUT.EDU.AU ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x17
(RC4-HMAC) keylength 16 (0xc9e45125e632aa422a2ec781b0ea300c)
............

Where:

'princ' is the EXACT name of the service that will be providing the Kerberos SNPEGO authentication, prepended to the configured Kerberos realm. There must must also be a reverse mappable A record in DNS for this service DNS name. The SSO enabled client will use this name when presenting the Kerberos AS ticket via the SPNEGO protocol.

For example:

If the ESOE is hosted at http(s)://esoe.yourcompany.org, the principal specified must be HTTP/esoe.yourcompany.org@YOUR.REALM.ORG. Note the HTTP protocol identifier must match as well. When a client machine on the configured domain connects to [http://esoe.yourcompany.org], it will be challenged for a Kerberos ticket by the ESOE via the SPNEGO Negotiate protocol. The client will send a request to the KDC for a TGT for the service it was challenged by, which will then be mapped to the SPN by the Kerberos AS. If the mapping is successful then the GSS negotiation can continue.

And where:

mapuser 'user' is the AD account created in step 1 above. Note if you choose to use a machine account or other you will need to change the value of ptype to a suitable option.

It is suggested that you use the 'rndPass' switch to avoid password policy issues on the domain controller.

Configuring SPNEGO parameters in esoe.config

Your esoe.config file located at esoe.data/config/esoe.config must be updated with the key data and other configuration to advise ESOE of your AD environment. This only needs to be undertaken once, not each time you upgrade unlike WAR rebuilding. Each of the configuration options below are disabled by default with a leading '#' character. Be sure to remove that.

Before challenging the client with an SPNEGO Negotiate header, the ESOE SPNEGO handler will look for a configured user-agent header supplied by the client. This is to ensure that the authenticating client is in fact a member of an AD (or Kerberos) domain, thus having the required credentials to complete a successful Kerberos authentication. Ie: The presence of the header is an assumption that the client browser has been configured for SSO.

The header string that the SPNEGO handler will look for is configured at the following parameter:
# Identifier name for browsers integrated into Active Directory
activeDirectoryBrowserId=someStringSSOEnabled

The configured string MUST be the same as the string used in the browser configuration guides below. Note: The user-agent header provided by the client browser does not need to exactly match this string, it must simply contain the exact string. Your also required to configure the server principal and keyTab details you created above in interacting with the domain controller.
# Identifier for server principal in Active Directory
serverPrincipal=HTTP/esoe-dev.qut.edu.au

The above parameter must be set to the SPN mapped to the Kerberos user in '2' above.
# Keytab for communication with Active Directory
keyTab=file://${esoe.data}/config//HTTP.esoe-dev.qut.edu.au.keytab

The above parameter must be set to the keytab file generated in '2' above, copied to the ESOE host.

To communicate with domain contollers ensure you've correctly copied the keytab file you've created to esoe.data/config/<keytabfilename> on each host running ESOE.

For the following lines in esoe.config please remove the leading '#' character to enable this configuration

spnegohandler.successURL=${successURL}
spnegohandler.spnegoUserAgentID=${activeDirectoryBrowserId}
spnegohandler.securityLevelIdentifier=${securityLevelIdentifer}
spnegohandler.securityLevel=${securityLevel1}

...

kerberosV5Authenticator.option.serverPrincipal=${serverPrincipal}
kerberosV5Authenticator.option.useKeyTab=true
kerberosV5Authenticator.option.storeKey=true
kerberosV5Authenticator.option.doNotPrompt=true
kerberosV5Authenticator.option.debug=true
kerberosV5Authenticator.file.keyTab=${keyTab}

Browser configuration settings

The most important part of browser configuration is ensuring the value of activeDirectoryBrowserId is presented by the browser when making requests of the ESOE.

The browser ID header can be configured manually in the browser for non IE browsers, or by group policy application by the domain controller for IE browsers on computers joined to an AD domain.

Firefox configuration:

Internet explorer Configuration;

Note: This method has only been tested on WinXp SP2. Configurations may vary on other versions.

AD policy configuration:

You can configure Active directory to globally apply the required settings to IE so that manual configuration is not required.

Useful tools:

Kerbtray

TroubleShooting

  1. SPNEGO auth fails with the browser displaying a 401 error stating 'SPNEGO Negotiate protocol required'.

This indicates that the browser has been configured to send the user-agent string that informs the ESOE that it is a member of the configured kerberos realm, yet it has not been configured to send SPNEGO data. Ensure that the activeDirectoryBrowserId parameter has been set in esoe.config. Recheck the browser configuration steps above to ensure the trusted domain has been setup correctly.

  1. SPNEGO auth keeps failing, with the esoe-core logs stating the browser did not send the correct token.
Ensure that your kerberos domain realm configuration is correct. The domain portion of the krb5.conf file must match the service that the user is attempting to access (Ie the ESOE), else the browser will attempt to provide NTLM authentication instead of an SPNEGO token. For example
[domain_realm]

        .your.esoe.com = YOUR.CONFIGURED.KERB.REALM
         your.esoe.com  = YOUR.CONFIGURED.KERB.REALM


If the esoe was actually hosted on my.esoe.com, or even esoe1.your.esoe.com, the SPNEGO auth will fail.

http://forum.java.sun.com/rss/rssmessages.jspa?RssUsername=Seema-1&numItems=60
http://java.sun.com/j2se/1.5.0/docs/guide/security/jgss/tutorials/Troubleshooting.html
http://docs.sun.com/app/docs/doc/816-5174/6mbb98ugh?a=view

Feedback

We aim to continually improve this documentation set to make it as easy as possible for new users and seasoned users alike to setup Active Directory integration for ESOE. We welcome any comments or additions you may have on the ESOE users mailing list at any time.