Steve.cleasby@uk.ibm.com EMEA L2 Support

WebSphere SPNEGO SSO Single sign on from a support perspective

Basic requirements

The mechanics and process

Using alias hostnames

Flow diagram

Troubleshooting

‘SPNEGO SSO from a support perspective’

This document is not intended to be another installation and configuration guide for Spnego SSO there are already a number of good articles and guides out there covering the topic. What I did find when researching this topic was that I needed to bring together a number of different pieces of information from many of these articles and guides in order to get a comprehensive insight into the mechanics, and variations in WebSphere versions, Browser options and the actual process involved in the interaction between Spnego, Kerberos configuration files, Active Directory and the Browser.

I have included a summary of the install and config requirements and you can get more detail on this from the articles and documents listed in the links at the end of this document.

Spnego SSO is primarily designed around Microsoft Active Directory and MS Internet Explorer using Windows Integrated Logon. It can be used with other Browsers that provide a suitable response to HTTP401 (Authenticate:Negotiate). For example Mozilla Firefox config option; network.negotiate-auth.trusted-uris which allows a list of hosts that will be trusted for a Negotiated Authentication response. It is also possible to configure Chrome to use Windows Integrated Logon. Chrome.exe --auth-server-whitelist="ibmaewas.filnet.com" --auth-negotiate-delegatewhitelist="ibmaewas.filenet.com" --auth-schemes="digest,ntlm,negotiate"

In order for Spnego SSO to work there are some minimum requirements:-

The target application must be deployed with a deployment descriptor (web.xml) that defines the login method for SSO. Typically <auth-method>CLIENT-CERT</auth-method>

The user must authenticate via their windows desktop login to a Directory Service that provides Kerberos Tokens in response to Browser requests responding to HTTP401 (Authenticate:Negotiate). Typically this will be MS Active Directory.

The Directory Service for the user’s logged on domain must include a unique service account for use during the authentication/negotiation process. This is used by the Browser to build and encrypt the authentication token passed to the WebSphere Application server, and is also used by the WebSphere Application server to decrypt the authentication token returned by the Browser. This Directory Service account is a normal AD account that is modified during or after creation to include an attribute called the ‘Service Principal Name’ (SPN). The actual account name (samAccountName) can be any name that conforms to the Directory Service naming conventions. The SPN attribute must conform to a defined format. In the case of Spnego SSO the SPN must be in the format ‘HTTP/<<hostname>>’ where the <<hostname>> is the DNS primary ‘A’ record for the target host where the target application is deployed. An SPN must be unique within a given Domain. It is important to NOTE that there are no automatic mechanisms in place to maintain uniqueness. It is possible to inadvertently create duplicate SPN names against different accounts. If this happens it may cause unexpected behaviour or failure. When adding the SPN, add two entries, both the short host name and the fully qualified host name. This is standard AD practice for object SPNs. You can see this by using the setspn –L <<computername>> command.

The WebSphere Application server must be able to access and read a Kerberos configuration file. The path to this file and the filename form part of the Spnego configuration in WebSphere. This configuration file is typically named krb5.ini (Windows) or krb5.conf (Unix/Linux/AIX).

The WebSphere server must be able to find and read a Kerberos data file containing a list of Directory Service SPN’s. This file also contains encrypted password information for the service account that allows the WebSphere server to decrypt the authentication token. This is called the ‘keytab’ file. WebSphere can find the keytab file either through path and filename information in the WebSphere Spnego configuration settings or from a property (default_keytab) in the krb5.ini (.conf) Kerberos configuration file. The encryption type used is also specified in the krb5 configuration file. This information is used by WebSphere to decrypt the Authentication Token received from the Browser. NOTE: if the service account password is changed, the ‘keytab’ file must be updated to reflect the new password or Spnego will fail. The keytab file should contain two entries for a particular SPN. One with the short host name and one with the fully qualified DNS host name.

The WebSphere Application server includes the ability to configure Spnego SSO authentication for applications deployed on the WebSphere server. This is a server wide configuration, so care needs to be taken to ensure that any applications deployed on the server that include HTTP web service components are capable of operating in a Spnego SSO authentication configuration. For example FileNet P8 Content Engine includes HTTP web services that are not designed to work with Spnego SSO. So P8 CE cannot be deployed on a Spnego enabled application server. P8 Workplace, WorkplaceXT and ICN, are designed to be capable of being deployed in a Spnego SSO environment, with appropriate changes to the web.xml deployment descriptor to remove the requirement for FORMS based logon.

Example Processing and Mechanics of Spnego SSO:-

An SSO enabled application is deployed on host ibmaewas with a DNS ‘CNAME’ alias ecmukfinance. A user logs on to their windows desktop as ‘ecmUser1’ in the Active Directory FILENET domain. They open a Browser to URL http://ecmukfinance:9080/WorkplaceXT. Browser receives HTTP401 Authenticate:Negotiate response from the application server. Browser resolves hostname in URL to ibmaewas because ecmukfinance is a DNS alias of ibmaewas. The hostname must be identified as a Local Intranet host / trusted URI depending on the Browser. Browser requests a Kerberos ticket and searches for SPN ‘HTTP/ibmaewas’ in the FILENET domain. The SPN must be found in the users’ logged on AD domain (or other trusted domain). When the SPN is found an authentication token is built encrypting the users logged on name ‘ecmUser1’. The Spnego authentication token is passed to the App server by the Browser.

The App server attempts to match the hostname in the request URL to a valid Spnego enabled authentication host defined in the WebSphere Spnego Web Authentication filter values. WebSphere Spnego uses DNS to resolve the hostname in the URL. The alias ecmukfinance resolves to ibmaewas because it is a CNAME alias of the ‘A’ record ibmaewas. The host ‘ibmaewas’ must be in

the Spnego filter list in WebSphere v7 and 8, or identified as a Spnego host by custom properties in WebSphere v6.

WebSphere must identify and find the appropriate SPN and determine how to decrypt the Token. WebSphere Spnego constructs the SPN search criteria based on the resolved hostname from the HTTP header and the configured Kerberos realm information, and looks for a matching SPN ‘HTTP/ibmaewas’ in the keytab file. The SPN in the keytab file must relate to a matching SPN in the AD domain identified with the Kerberos realm from the Kerberos configuration file, as specified in the WebSphere Spnego settings. In our example WebSphere will look for an SPN ‘HTTP/ibmaewas@FILENET.COM’ When a match is found, the Authentication token received from the Browser is decrypted using information from the krb5.ini (krb5.conf), and keytab file. The user name is decrypted from the Authentication Token in the format ‘ecmUser1@FILENET.COM’ The Kerberos realm is trimmed from the user name to give a user name of ecmUser1. The Kerberos realm is the same as the user’s Active Directory Domain name in upper case. WebSphere validates the user in the Authentication repository configured in WebSphere ‘Global Security’, using LDAP. When validation completes, the user is logged on to the target application.

Using an alias host name for SPNEGO TAI or SPENGO web authentication.

When you use the Simple and Protected GSS-API Negotiation Mechanism Web authentication or (SPNEGO) trust association interceptor (TAI) for authentication, and you would like to use a virtual or alias host name in the Browser URL for the target application server, you must configure WebSphere SPNEGO to resolve the alias host name correctly. Then, you can dynamically add or modify an alias name in DNS without changing the application server’s configuration. If you enable this functionality you will not need to include alias host names in the SPNEGO configuration.

Before you begin:

This configuration requires a working SPNEGO single sign-on environment using the default hostname. (The primary ‘A’ record in DNS)

About this task:

The application server will perform a DNS lookup for the target host in the URL when an HTTP request comes in, and if the alias host name is resolved to a host name that is already configured for SPNEGO single sign-on, the application server will continue to process it. It is not required to add alias hostnames to the settings for SPNEGO using this configuration.

Procedure WebSphere 6.x

1. Define the actual host name for the com.ibm.ws.security.spnego.SPNx.hostName custom property.

a. From administration console, click Global security > Web and SIP security > Trust association > Interceptors > com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl > Custom Properties

b. Add or modify the com.ibm.ws.security.spnego.SPNx.hostName property. For example:

Property Name

com.ibm.ws.security.spnego.SPN1.hostName

Value

ibmaewas

This custom property specifies the actual host name to which the application server can resolve the hostname in the target URL for use with SPNEGO single sign-on. You can then dynamically add or modify an alias name for this host in the DNS without changing the configuration for the application server, and use the alias in the Browser URL. (The Browser must identify the host as being allowed to use Windows Integrated Logon). You can add multiple SPN hostnames by incrementing the SPN number in the custom property. e.g. com.ibm.ws.security.spnego.SPN2.hostName

In WebSphere 7 and 8 this hostname is added to the SPNEGO filters section in Spnego Web Authentication config, and not as a custom property.

2. Turn on the Canonical support flag. WebSphere 6.x

a. From administration console, click Global security > Custom properties

b. Add or modify the com.ibm.websphere.security.krb.canonical_host property and set it to "true".

Name

com.ibm.websphere.security.krb.canonical_host

Value: true

This custom property specifies whether the application server uses the canonical form of the URL/HTTP host name when authenticating a client. (i.e. resolve an alias or virtual hostname to the DNS primary ‘A’ record) When configuring hosts and addresses in DNS you can create multiple entries for a single actual host. These entries can be ‘A’ type records, ‘CNAME’ records or ‘PTR’ records.

‘A’ type records associate a fully qualified domain name with an IP Address. ‘CNAME’ records are an alias of an existing ‘A’ record. ‘PTR’ records are reverse lookup records that associate an IP Address with an ‘A’ type record.

This property when set to ‘true’ resolves a DNS ‘CNAME’ aliases to the related ‘A’ type record.

If you set this custom property to be false, and an authentication token contains a host name that is different from the HTTP host name in the HTTP header, the application server might issue the following message:

CWSPN0011E: An invalid SPNEGO token has been encountered while authenticating an HttpServletRequest

If you set this custom property to true, you can avoid this error message and allow the application server to authenticate using the canonical form of the URL/HTTP host name. This is already the default behaviour for WAS v7.0.0.5 and 8.x and the custom property is not required.

3. Configure the browser: On the browser for the client machine, the alias host name needs to be configured as a trusted host or Local Intranet address. Add two entries. The short hostname alias and the fully qualified hostname alias. Under normal circumstances the browser will interpret short non-qualified names as local intranet addresses. If the fully qualified name is used to access a local intranet resource that uses Spnego it must be added to the list of local trusted addresses. Test both formats and if required add both to the list.

o For Internet Explorer:

a. Select Tools > Internet options.

b. Select the Security tab.

c. Click Local intranet > Sites > Advanced

d. Add the alias host name entries in this panel.

o For Mozilla Firefox:

a. Type About:config in the address bar and press ENTER to access configuration options.

b. Locate the network.negotiate-auth.trusted-uris preference name, right-click on the preference, and select Modify.

c. Add alias host names in the text box, separating host names with a comma.

o For Chrome:

a. Chrome.exe --auth-server-whitelist="ibmaewas.filnet.com" --auth-negotiate-delegatewhitelist="ibmaewas.filenet.com" --auth-schemes="digest,ntlm,negotiate"

4. Ensure that the SPN for the resolved host name is in the keytab file.

o If com.ibm.websphere.security.krb.canonical_host is set to “true”, the application server expects the primary ‘A’ record resolved host name to be in the keytab file. The ‘CNAME’ alias does NOT need to be in the keytab file. The alias will be resolved to the ‘A’ record hostname. This is the default behaviour in WebSphere v 7.0.0.5 upwards and 8.x

o If com.ibm.websphere.security.krb.canonical_host is set to “false” and an alias is used, an SPN using the alias needs to be present in the keytab file. The alias hostname in the URL will be passed to Spnego unchanged.

o In Websphere 8.x Administrative console – Spnego Web Authentication there is an additional tick box option ‘Use the alias hostname for the application Server’ ticking this box is the same as setting the custom property com.ibm.websphere.security.krb.canonical_host equal to “false” so for this configuration this option should NOT be selected.

The Client browser will apply similar rules when resolving the hostname in the URL in order to obtain the Kerberos Ticket and build the SPNEGO Authentication Token.

Always ensure that the Directory Service SPN contains the correct hostname. This will typically be the primary ‘A’ record name in DNS. Also ensure that there is only one instance of the SPN in the users’ domain directory service. Duplicate SPNs against different accounts will cause authentication to fail.

Examples:-

App server Netbios hostname = ibmaewas App server hostname entries in DNS Forward lookup Zone = filenet.com:- ‘A’ type record = ibmaewas (FQDN ibmaewas.filenet.com) ‘CNAME’ record = ecmukfinance (FQDN ecmukfinance.filenet.com)

Active Directory service account = spnego_ibmaewas SPN = HTTP/ibmaewas SPN = HTTP/ibmaewas.filenet.com

Keytab file contains: - HTTP/ibmaewas@FILENET.COM HTTP/ibmaewas.filenet.com@FILENET.COM

Krb5.ini or Krb5.conf contains: - [libdefaults] default_realm = FILENET.COM default_keytab_name = FILE:C:\Windows\spnego.keytab default_tkt_enctypes = RC4-HMAC default_tgs_enctypes = RC4-HMAC forwardable = true renewable = true noaddresses = true clockskew = 300

NOTE: The Kerberos realm name is the same as the full active directory Domain name. The Kerberos realm name must always be in UPPER CASE. This Kerberos real name is appended to the SPN to match the SPN in the keytab file.

NOTE: RC4-HMAC is the typical encryption type used by MS AD 2003 and 2008. Other encryption types can be used. These would need to be managed by the MS AD administrator and included in the Kerberos configuration file.

The WebSphere Spnego Web Authentication config - Spnego filter list must include the DNS ‘A’ record hostname, for example: ibmaewas (Do not configure the alias name) WebSphere should be configured to use the krb5 canonical name = true (default in 7.0.0.5 and 8.x). In v8.x do not select the ‘Use the alias hostname for the application Server’.

The Browser must be configured for ‘Windows Integrated Authentication’ and the Browser must identify the target URL alias as being a local trusted intranet address. Add the hostnames to the list of trusted addresses in Local Intranet Zone or list of trusted URIs for Authenticate:Negotiate.

Example target URLs http://ecmukfinance:9080/WorkplaceXT http://ecmukfinance.filenet.com:9080/WorkplaceXT

NOTE: In WebSphere v7 and v8 the Spnego filter list can include filter criteria. This determines what web applications will use Spnego authentication. For example the criteria ‘request-url%=navigator’ will match only target URLs containing ‘navigator’. To match multiple URLs use the format: ‘request-url^=navigator|Workplace|WorkplaceXT|snoop’

These filter criteria can also be specified in Spnego TAI using the custom property com.ibm.ws.security.spnego.SPN<id>.filter

You cannot test Spnego SSO using the local browser on the WebSphere host that has been configured for Spnego SSO. The browser must be on a different host or client.

If the SPN information in the AD account is changed or modified it may be necessary to restart the client workstation as Kerberos Ticket information is cached locally.

Useful tools:-

Setspn (used to add, delete or list SPN objects in Active Directory) ktpass (windows tool to create, modify, merge keytab entries and files and SPNs) ktab (Java tool to create, modify, delete keytab entries) klist (Java tool to list keytab entries) In some Linux/UNIX versions of the Oracle/Sun JDK, ktab is no longer included. In this case use the ktab or kerberos utility supplied with the operating system like ktutil.

NOTE: setspn and klist can be used from a Windows 7 desktop or from a 2008 server. These can be very useful to check that the desktop can find and cache the SPN Kerberos ticket. Use setspn –Q HTTP/ibmp8aewas.filenet.com before launching the browser to make sure the SPN can be found. Use klist after attempting to connect to the application to check that the ticket has been returned

Diagnosing error conditions:

Invalid or non-spnego token:

If the Desktop Browser cannot find a matching SPN for the resolved hostname used in the target URL a valid Spnego authentication token cannot be created and returned. An HTTP 403 Forbidden response is sent back to the Browser. Some Browsers may not display a message in response to the failed Authentication token.

Where trace logging is enabled for Spnego, the Spnego enabled host may log the following:

Trace specification = *=info:com.ibm.ws.security.spnego.*=all

[12/02/15 13:55:21:515 GMT] 0000001f Context E com.ibm.ws.security.spnego.Context begin CWSPN0011E: A non-valid SPNEGO token has been encountered while authenticating a HttpServletRequest:

Or alternatively

[12/02/15 14:16:36:991 GMT] 0000001c SpnegoHandler 2 com.ibm.ws.security.spnego.SpnegoHandler isAuthHeaderNotSPNEGO Client sent back a non-SPNEGO authentication header:

This is because the Browser is unable to build the Authentication Token correctly.

The hostname in the URL must resolve to the hostname in the SPN and a matching SPN must be found in the user's log-on Domain.

Use command line tool nslookup to check resolving the URL host name: For example:

C:\Documents and Settings\Administrator>nslookup alias

Server: ibmp8450c.sjcvm.local --[This is the DNS server]--

Address: 192.168.1.12

Name: ibmp8501.SJCVM.local --[This is the Primary 'A' record name]

Address: 192.168.1.20

Aliases: alias.SJCVM.local --[This is the alias or virtual hostname]

The SPN must use the 'A' record name in both short and FQDN format. In this case SPN=HTTP/ibmp8501 and SPN=HTTP/ibmp8501.sjcvm.local

C:\>setspn -L spnegoweb

Registered ServicePrincipalNames for CN=spnegoweb,CN=Users,DC=SJCVM,DC=local:

HTTP/ibmp8501 HTTP/ibmp8501.sjcvm.local

Use setspn –Q or setspn –X on the desktop to check acces to the SPN Use klist to check if the SPN ticket is being returned

Problems decrypting the token:

If WebSphere Spnego cannot find suitable SPN information in the keytab file for the Spnego enabled host, the Authentication Token cannot be decrypted.

An HTTP 403 Forbidden response is sent back to the Browser

Some Browsers may not display a message in response to the failure.

The Spnego enabled host may log the following, where trace logging is enabled for Spnego:

Trace specification = *=info:com.ibm.ws.security.spnego.*=all

[12/02/15 16:48:25:032 GMT] 0000001a ServerCredent E com.ibm.ws.security.spnego.ServerCredential initialize CWSPN0014E: An exception occurred during Kerberos initialization. Failure: org.ietf.jgss.GSSException, major code: 13, minor code: 0

[12/02/15 16:48:25:032 GMT] 0000001a ServerCredent E com.ibm.ws.security.spnego.ServerCredentialsFactory initializeServer CWSPN0015E: Unable to create a GSSCredential for: HTTP/ibmp8501@SJCVM.LOCAL

[12/02/15 16:48:25:032 GMT] 0000001a ServerCredent E com.ibm.ws.security.spnego.ServerCredentialsFactory initializeServerCreds CWSPN0017E: Unable to create GSSCredentials for any of the hosts specified in the configuration properties.

Check the WebSphere Spnego configuration and ensure the path to the keytab file is correct

Check the contents of the keytab file using klist, ktab, or ktutil make sure the SPN logged is in the keytab file.

C:\Documents and Settings\Administrator>klist -e -k C:\winnt\spnegoweb.keytab

Key tab: C:\winnt\spnegoweb.keytab, 2 entries found.

[1] Service principal: HTTP/ibmp8501@SJCVM.LOCAL KVNO: 1 Key type: 23

[2] Service principal: HTTP/ibmp8501.sjcvm.local@SJCVM.LOCAL KVNO: 1 Key type: 23

Token not processed:

If the WebSphere Spnego filter configuration does not include the appserver hostname, WebSphere Spnego will not process the Authentication Token for the resolved host. WebSphere v6 SPNEGO configuration must set the custom property com.ibm.ws.security.spnego.SPN1.hostName value = <<hostname>> NOTE WebSphere v7 and v8 require at least one hostname in the Spnego Filter configuration and this host must exist in the configured keytab or you will receive a JAAS error ‘Invalid Credentials’.

Mismatching encryption type: The following may be logged:

Error authenticating request. Reporting to client Major code = 11, Minor code = 31 org.ietf.jgss.GSSException, major code: 11, minor code: 31 major string: General failure, unspecified at GSSAPI level minor string: Kerberos error while decoding and verifying token: com.ibm.security.krb5.internal.KrbException, status code: 31 message: Integrity check on decrypted field failed.

This happens if the keytab file entry was generated with an encryption type that does not match the encryption type for the Kerberos information returned by AD. For example: where the AD default is RC4-HMAC and the keytab was created with +DES only. This can also happen the other way round. Earlier versions of Active Directory prior to 2003 used DES by default, and if the keytab is encrypted with RC4-HMAC then token decryption will fail.

Solution: Re-generate the keytab file with the correct encryption type that matches the type used in Active Directory. Make sure the krb5.ini(.conf) contains the correct enc type default_tkt_enctypes = rc4-hmac default_tgs_enctypes = rc4-hmac

Pre windows 2003 use des-cbc-md5.

Token is decrypted but user is not authenticated:

A SECJ0222E: An unexpected exception occurred when trying to create a LoginContext.

The WebSphere LDAP repository configuration must include access to the user’s domain and be able to find the user ID in the configured Directory Service. For further debugging use a network trace tool like Wireshark and filter for dns || kerberos || ldap you can also add these JVM properties (examples for WebSphere): -Dcom.ibm.security.jgss.debug=all -Dcom.ibm.security.krb5.Krb5Debug=all

Other useful support links:

Troubleshooting:

http://www-01.ibm.com/support/knowledgecenter/SSEQTP_8.5.5/com.ibm.websphere.base.doc/ae/rsec_SPNEGO_troubles.html

Installation and configuration:

https://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101065

http://www.ibm.com/developerworks/websphere/library/techarticles/0809_lansche/0809_lansche.html

http://www.redbooks.ibm.com/redbooks/pdfs/sg247771.pdf

http://www.redbooks.ibm.com/abstracts/sg247675.html?Open

See next page for process flow diagram

Active Directory Domain Controller: KDC and DNS

Domain User Desktop using Windows Integrated Logon

WebSphere Application Server Configured for SPNEGO

Krb5.conf keytab 1: Browse to http://alias.filenet.com:9080/navigator

2: Receive HTTP 401 Authenticate:Negotiate

6: Return SPNEGO authentication token

7: Find SPN in keytab file

8: Decrypt token with data from keytab and krb5.conf