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.
depfeatTrace | 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
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 theclockskew parameter
is 300 seconds (or 5 minutes).
|
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:
|
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:
|
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 HTTP/server.realm.com@REALM.COM with the addition of @REALM.COM, then delete the user, redefine the user, and redefine the SPN. 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:
|
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. |
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. |
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.
|
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:
|
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). |
Symptom | Description | User Action |
---|---|---|
HTTP Post parameters are lost during interaction with the
SPNEGO TAI, when stepping down to userid/password login. "Stepping down to userid/password login" means that the Microsoft Internet Explorer tries to respond initially with a SPNEGO token. If this response is unsuccessful, then the Microsoft Internet Explorer tries to respond with a NTLM token that is obtained through a userid/password challenge. |
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 redirTimerfunction, any POST or GET parameters that were present from the original request are lost. 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.
|
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.
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.
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.