SPNEGO trust association interceptor (TAI) troubleshooting tips (deprecated)
Presented here is a list of troubleshooting tips useful in diagnosing Simple and Protected GSS-API Negotiation (SPNEGO) TAI problems and exceptions.
In WebSphere® Application Server Version 6.1, a trust association interceptor (TAI) that uses the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) to securely negotiate and authenticate HTTP requests for secured resources was introduced. In WebSphere Application Server 7.0, this function is now deprecated. SPNEGO web authentication has taken its place to provide dynamic reload of the SPNEGO filters and to enable fallback to the application login method.
Trace | Use |
---|---|
com.ibm.security.jgss.debug |
Set this JVM Custom Property to all to trace through JGSS
code. Messages appear in the trace.log file, and
SystemOut.log. |
com.ibm.security.krb5.Krb5Debug |
Set this JVM Custom Property to all to trace through the
Kerberos5-specific JGSS code. Messages appear in the trace.log file, and
SystemOut.log. |
com.ibm.ws.security.spnego.* |
Set this trace on using the trace.log file. | . Messages appear in the
Problem: WebSphere Application Server and the Active Directory (AD) Domain Controller's time are not synchronized within 5 minutes.
Symptom | User Action |
---|---|
|
The preferred way to resolve this issue is to synchronize the WebSphere Application Server system time to be within 5 minutes of the AD
server's time. A best practice is to use a time server to keep all systems synchronized. You can
also add or adjust the clockskew parameter in the Kerberos configuration file.
Note: The default for the
clockskew parameter is 300 seconds (or 5 minutes).
|
Problem: No factory available to create a name for mechanism 1.3.6.1.5.5.2.
Problem | Symptom | User Action |
---|---|---|
Getting an exception: No factory available to create a name for mechanism 1.3.6.1.5.5.2. There is no factory available to process the creation of a name for the specific mechanism. |
|
Check the java.security file to ensure that it contains the IBMSPNEGO
security provider and that the provider is defined correctly. The java.security
file should contain a line similar to:
|
Problem: Getting an exception as the JGSS library is trying to process the SPNEGO token.
Symptom | Description | User Action |
---|---|---|
The following error is displayed as the JGSS library is trying to process the SPNEGO
token.
|
This exception is the result of encoding the ticket using one key and attempting to decode
it using a different key. There are numbers of possible reasons for this condition:
|
If the problem is with the Kerberos keytab file, then regenerate the keytab file. If the
problem is with multiple SPN definitions, then remove the extra or conflicting SPN, confirm that the
SPN is no longer registered with the Active Directory, and then add the SPN. The Active Directory
may need to be searched for other entries with SPNs defined that clash with the SPN. To confirm
that the SPN is not registered, the command:
Should
return with the following response:
|
Problem: Single sign-on is not occurring.
Symptom | Description | User Action |
---|---|---|
When tracing is enabled, the following message
appears:
|
The client is returning an NT LAN manager (NTLM) response to the authorized challenge, not
a SPNEGO token. This condition can occur due to any of the following reasons:
|
If the SPN is defined incorrectly as If the problem is with the Kerberos keytab file, then regenerate the keytab file. If the problem is with either category of multiple SPN definitions, then remove the extra or
conflicting SPN, confirm that the SPN is no longer registered with the Active Directory, and then
add the SPN. You can search the Active Directory for other SPN entries that are causing multiple SPN
definitions. The following commands are useful to determine multiple SPN definitions:
|
Problem: Credential Delegation is not working.
Symptom | Description | User Action |
---|---|---|
An invalid option is detected. When tracing is enabled, the following message is
displayed:
|
The Kerberos configuration file is not properly configured. | Ensure that the renewable, or proxiable are set to true. |
Problem: Unable to get SSO working using RC4-HMAC encryption.
Symptom | Description | User Action |
---|---|---|
Examine the following message in the trace that you receive when trace is turned
on:
|
RC4-HMAC encryption is not supported by a Microsoft
Windows
version before the 2003 Kerberos key distribution center (KDC). To confirm this condition, examine
the trace and identify where the exception is thrown. The content of the incoming ticket should be
visible in the trace. Although the incoming ticket is encrypted, the SPN for the service is
readable. If a Microsoft
Windows
version before the 2003 KDC is used and the system is configured to use RC4-HMAC, the string
representing the ticket for userid@REALM (instead of the expected
HTTP/hostname.realm@REALM ) is displayed. For example, this is the beginning of a
ticket received from a Microsoft
Windows
version prior to 2003
KDC: The
realm is REALM.COM. The service name is userid. A correctly formed ticket for the same SPN is:
|
To correct the problem, either use the Single data encryption standard (DES) or use a Microsoft Windows 2003 Server for a KDC. Remember to regenerate the SPN, and the Kerberos keytab file. |
Problem: User receives the following message when accessing a protected URL through the SPNEGO SSO.
Symptom | Description | User Action |
---|---|---|
Examine the following
message:
|
This message is generated by the Apache/IBM HTTP Server. This server is indicating that the authorization header returned by the user's browser is too large. The long string that follows the word Negotiate (in the previous error message) is the SPNEGO token. This SPNEGO token is a wrapper of the Microsoft Windows Kerberos token. Microsoft Windows includes the user's PAC information in the Kerberos token. The more security groups that the user belongs to, the more PAC information is inserted in the Kerberos token, and the larger the SPNEGO becomes. IBM HTTP Server 2.0 (also Apache 2.0 and IBM HTTP Server 6.0) limit the size of any acceptable HTTP header to be 8K. In Microsoft Windows domains having many groups, and with user membership in many groups, the size of the user's SPNEGO token may exceed the 8K limit. | If possible, reduce the number of security groups the user is a member of. IBM HTTP Server 2.0.47 fix pack PK01070 allows for HTTP header sizes up to and
beyond the Microsoft limit of 12K. WebSphere Application
Server Version 6.0 users can obtain this fix in fix pack 6.0.0.2. Note: Non-Apache-based web servers
may require differing solutions.
|
Problem: Even with JGSS tracing disabled, some KRB_DBG_KDC messages appear in the SystemOut.log.
Symptom | Description | User Action |
---|---|---|
Examine theSystemOut.log and note that some KRB_DBG_KDC messages appear there even with JGSS tracing disabled. | While most of the JGSS tracing is controlled by the com.ibm.security.jgss.debug property, a small set of messages are controlled by the com.ibm.security.krb5.Krb5Debug property. The com.ibm.security.krb5.Krb5Debug property has a default value to put some messages to the SystemOut.log. | .To remove all KRB_DBG_KDC messages from the SystemOut.log, set the
JVM property as follows:
|
Problem: An application contains a custom HTTP 401 error page, the SPNEGO TAI-generated HTTP response page is not displayed in a browser.
Symptom | Description | User Action |
---|---|---|
When an application contains a custom HTTP 401 error page, the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) trust association interceptor (TAI)-generated HTTP response page is not displayed in a browser. | When an application contains a custom HTTP 401 error page, the SPNEGO TAI-generated HTTP response page is not displayed in a browser. The custom HTTP 401 error page is displayed instead. | You can customize your HTTP 401 page to include information concerning how to configure your browser to use SPNEGO. For more information, see Configuring the client browser to use SPNEGO TAI (deprecated) and SPNEGO TAI custom properties configuration (deprecated). |
Problem: HTTP Post parameters are lost during interaction with the SPNEGO TAI, when stepping down to userid/password login.
Symptom | Description | User Action |
---|---|---|
HTTP Post parameters are lost during interaction with the SPNEGO TAI, when stepping down to
userid/password login.
|
The Microsoft Internet Explorer maintains state during a user's request. If a request was given
the response of an HTTP 401 Authenticate Negotiate, and the browser responds with a NTLM token obtained through a userid/password challenge, the browser resubmits the request. If this second request is given a response of an HTML page containing a redirection to the same URL but with new arguments (via Javascript), then the browser does not resubmit the POST parameters. Note: To
avoid this problem, it is critical to NOT perform the automatic redirection. If the user clicks a
link, the problem does not occur.
|
The browser responds to the Authenticate/Negotiate challenge with an NTLM token, not an SPNEGO
token. The SPNEGO TAI sees the NTLM, and returns a HTTP 403 response, along with
theHTML page. When the browser runs the JavaScript
By using the SPN<id>.NTLMTokenReceivedPage property, an appropriate message page can be
returned to the user. The default message that is returned (in the absence of a user-defined
property) is:
Using the SPN<id>.NTLMTokenReceivedPage property, you can customize the exact response. It is critical that the returned HTML not perform a redirection. When the SPNEGO TAI has been configured to use the shipped default HTTPHeaderFilter class as the SPN<id>.filterClass, then the SPN <id>.filter can be used to allow the second request to flow directly to the normal WebSphere Application Server security mechanism. In this way, the user experiences the normal authentication mechanism. An example of such a configuration follows showing the required SPNEGO TAI properties necessary
and the HTML file
content.
Note: Observe
that the filter property instructs the SPNEGO TAI to NOT intercept any HTTP request that contains
the string
noSPNEGO. Here is an example of a generating a helpful
response.
|
Problem: The trust association interceptor (TAI) does not call the initialize(Properties) method
Tracing might show that TAI is loaded, but that the initialize(Properties) method is not called. Only the getVersion() method appears to be called during startup.
WebSphere's TAI processing only calls initialize(Properties) when there are custom properties that are defined for the TAI.
To fix this issue, define an unused TAI custom property, such as com.ibm.issw.spnegoTAI.NumberOfServers=0.
Problem: The trust association interceptor (TAI) is not loading properly
SPNEGO014: Kerberos initialization Failure: org.ietf.jgss.GSSException, major code: 13, minor code: 0
major string: Invalid credentials
minor string: SubjectKeyFinder: no JAAS Subject
at com.ibm.security.jgss.i18n.I18NException.throwGSSException(I18NException.java:12)
…
A possible cause for this is that the JVM custom property javax.security.auth.useSubjectCredsOnly is not set to a value of false.
To fix this issue, define a JVM custom property on each JVM that is enabled for the TAI, javax.security.auth.useSubjectCredsOnly=false.
Problem: JACL scripts default characters for adding trust association interceptor (TAI) parameters can cause issues
JACL scripts for adding TAI parameters accept positional parameters. To accept the defaults, a
.
is specified. On some WebSphere platforms, if
you specify a .
it can cause the property to be added with a value of .
.
Always (regardless of platform), confirm that the properties added are as expected using the administrative console. If they are not, manually correct them.