WebSphere SPNEGO SSO

Single sign on from a support perspective

Basic
requirements

The mechanics
and process

Using alias
hostnames

Flow diagram

Troubleshooting

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

‘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_SPNE
GO_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

8: Decrypt token with data

from keytab and krb5.conf

7: Find SPN in
keytab file

6: Return SPNEGO authentication token

2: Receive HTTP 401 Authenticate:Negotiate

Krb5.conf
1: Browse to http://alias.filenet.com:9080/navigator keytab
Domain User Desktop using
WebSphere Application Server
Windows Integrated Logon
Configured for SPNEGO