How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I troubleshoot Kerberos and WDSSO issues in AM (All versions)?

Last updated May 10, 2022

The purpose of this article is to provide information on troubleshooting Kerberos™ and Windows Desktop SSO (WDSSO) issues in AM. You can use the collected data to troubleshoot issues yourself or include it when you raise a ticket to enable us to help you more effectively.


4 readers recommend this article

Troubleshooting Kerberos and WDSSO issues

If you are experiencing issues with your Kerberos node or WDSSO module in AM, you can use the following troubleshooting steps to debug your issue:

  1. Generate a full set of message level debug logs and capture the HTTP trace while reproducing the issue. Required debug logs include the AM ones and the debug logs for the Krb5LoginModule.
  2. Verify a Kerberos token has been sent (rather than a NTLM token).
  3. Enable Kerberos event logging on the Microsoft® Windows® or Active Directory® server as detailed in: Microsoft - How to enable Kerberos event logging.
  4. Export the configuration for your WDSSO module - it is essential to check if a configuration issue is contributing to your issues.
  5. Check your keytab file details are correct.
  6. Check your browser settings are correct.
  7. Check other configuration details.
  8. Check connection to Kerberos Key Distribution Center (KDC).

Additionally, information is included about the expected access flows for Kerberos authentication (with an agent protected resource) and a federated environment. These flows can help you track down where the breakdown in Kerberos is occurring, which can help focus your troubleshooting efforts. 

Note

If none of these resolve the issue, another problem must exist with the Kerberos protocol between the browser and Active Directory; you can attempt to track this down using utilities such as the Microsoft Network Monitor or the Microsoft Message Analyzer.

Understanding access flows for Kerberos

Kerberos Authentication​

The expected access flow for Kerberos single sign-on (SSO) with an agent protected resource is as follows: 

  1. The user attempts to access the protected resource with a SPNEGO-enabled browser.
  2. The agent intercepts the request and redirects to the AM server.
  3. The AM server returns a HTTP 401 Authenticate/Negotiate response.
  4. The browser sends the following to the Active Directory server:
    • a request for the Ticket Granting Ticket (TGT) if a TGT does not already exist.
    • a request (accompanied by the TGT) for a Kerberos Service Ticket.
  5. The Kerberos Domain Controller sends a Service Ticket to the browser.
  6. The browser sends HTTP, POST, GET, Web-Service and SPNEGO tokens to the AM server.
  7. The Kerberos node or WDSSO module validates the SPNEGO token and retrieves the user profile from the user data store.
  8. The AM server creates an SSO Token.
  9. The AM server returns a HTTP 200 OK response and the SSO Token to the browser.
  10. The browser sends the SSO token to the agent and the agent grants access to the protected resource.

Federated environment

The expected access flow for Kerberos in a federated environment is as follows: 

  1. The user attempts to access the protected resource at the service provider (SP).
  2. The SP sends the authorization request to the AM identity provider (IdP).
  3. The AM IdP returns a HTTP 401 Authenticate/Negotiate response.
  4. The browser sends the following to the Active Directory server:
    • a request for the Ticket Granting Ticket (TGT) if a TGT does not already exist.
    • a request (accompanied by the TGT) for a Kerberos Service Ticket.
  5. The Kerberos Domain Controller sends a Service Ticket to the browser.
  6. The browser sends HTTP, POST, GET, Web-Service and SPNEGO tokens to the AM IdP.
  7. The Kerberos node or WDSSO module validates the SPNEGO token and retrieves the user profile from the user data store.
  8. The AM IdP creates an SSO Token.
  9. The AM IdP returns a HTTP 200 OK response and the SSO Token to the browser.
  10. The AM IdP sends the authorization response of Success to the SP and the SP grants access.

Generating debug logs and capturing the HTTP trace

It is important to ensure your debug logs and HTTP trace have corresponding date and timestamps. You should follow this process:

  1. Enable message level debugging as described in Debug Logging (AM 7 and later) or How do I enable Message level debugging in AM (All versions) debug files?
  2. Clear the AM debug logs as described in How do I clear debug logs in AM (All versions)?
  3. Enable debug logging for the Krb5LoginModule of the JVM; this adds additional logging to the container's standard logs, which allows you to trace the program's execution of the Kerberos V5 protocol. You can enable debug logging as detailed in How do I enable debug logging for troubleshooting Kerberos and WDSSO issues in AM (All versions)?
  4. Start a HTTP trace in your browser. You can do this by capturing a HAR file as described in How do I create a HAR file for troubleshooting AM (All versions)?
  5. Reproduce the issue using your browser.
  6. Stop the HTTP trace.

Verifying a Kerberos token has been sent

Microsoft Windows will first try Kerberos; unless all the requirements are met, it will fall back to NTLM authentication. 

You can use the output from the HTTP trace captured in the above section to check that a Kerberos token has been sent as follows:

  1. Examine the output from the HTTP trace tool. You are looking for the Authorization: Negotiate section:
    • If this begins YII, then Kerberos is being used, for example: Authorization: Negotiate YIIVDAYGKwYBE...
    • If this begins TlR, then Kerberos is not being used,  for example: Authorization: Negotiate TlRMTVNTUA...

You can also check the Authentication log for the WDSSO module to see if it has fallen back to NTLM authentication. If it has, you will see the following error:

ERROR: kerberos token is not valid

See Kerberos token is not valid error when authenticating with Windows Desktop SSO in AM (All versions) using Microsoft Edge for further information on this error.

Exporting the WDSSO module configuration

You can export this configuration using the following ssoadm command:

$ ./ssoadm get-auth-instance -e [realmname] -m [modulename] -u [adminID] -f [passwordfile]

Replacing [realmname], [modulename], [adminID] and [passwordfile] with appropriate values.

For example:

  • AM 7 and later: $ ./ssoadm get-auth-instance -e / -m wdsso -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt
  • Pre-AM 7: $ ./ssoadm get-auth-instance -e / -m wdsso -u amadmin -f pwd.txt

Example response:

Authentication Instance profile: iplanet-am-auth-windowsdesktopsso-returnRealm=false iplanet-am-auth-windowsdesktopsso-auth-level=0 iplanet-am-auth-windowsdesktopsso-kerberos-realm=FORGEROCK.COM iplanet-am-auth-windowsdesktopsso-lookupUserInRealm=false iplanet-am-auth-windowsdesktopsso-kdc=host1.example.com iplanet-am-auth-windowsdesktopsso-principal-name=HTTP/host1.example.com@FORGEROCK.COM iplanet-am-auth-windowsdesktopsso-keytab-file=/tmp/keytab

Checking keytab file details

Kerberos utility from Microsoft. For example:

$ klist

An example output from the Klist utility is:

Server: HTTP/host1.example.com @ FORGEROCK.COM KerbTicket Encryption Type: RSADSI RC4-HMAC(NT) Ticket Flags 0x40a10000 -> forwardable renewable pre_authent name_canonicalize Start Time: 3/17/2016 11:33:06 (local) End Time: 3/17/2016 21:31:54 (local) Renew Time: 3/24/2016 11:31:54 (local) Session Key Type: RSADSI RC4-HMAC(NT) Cache Flags: 0 Kdc Called: SVR1

You can then check the following and resolve as applicable:

  • Check the Kerberos service ticket was retrieved for AM:
    • If the Kerberos service ticket does exist for the AM FQDN - check your browser settings to ensure the browser is correctly set up for Windows authentication and update where necessary. See the Checking your browser settings are correct section below for further information.
    • If the Kerberos service ticket does not exist for the AM FQDN - continue troubleshooting.
  • Check you have used an appropriate encryption type (KerbTicket Encryption Type in example Klist output) when generating the keytab file and that you have updated the user account properties in Active Directory to match. The corresponding encryption type should be selected in the user account properties. If you want to use a 256-bit AES encryption type, you must have the Oracle® Java JCE unlimited strength jars installed in the $JAVA_HOME/jre/lib/security/ directory and your Microsoft Windows machine must also support this encryption. These jars can be downloaded from the following link for Java 8 and earlier: Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files Download. Java 9 and later uses the unlimited policy files by default.
  • Check the service principal defined in AM (iplanet-am-auth-windowsdesktopsso-principal-name in WDSSO module export) matches the one in the keytab file (Server in Klist output). This can be determined by looking at the Kerberos ticket with klist to see what Principal was actually authenticated in Kerberos.
  • The key version number (kvno) in the keytab file must equal the value of the msDS-KeyVersionNumber attribute for the AM principal in Active Directory +1. This is because Active Directory increases the value of kvno by 1 when you use the keypass command to create the keytab file and these values must match.
Note

You can query the value of msDS-KeyVersionNumber in Active Directory using the ldapsearch command.

Checking your browser settings are correct

The configuration required varies according to the browser you are using:

Microsoft Edge

If you use Microsoft Edge, there are three settings you need to check and configure in Internet Options:

  • Ensure the Enable Integrated Windows Authentication option is selected. This option is found on the Advanced tab under Security.
  • Ensure the Automatic logon with current user name and password option is selected. This option can be accessed from the Security tab. Select Trusted Sites and then click the Custom Level button. This option can then be found under User Authentication > Logon.
  • Add the AM FQDN to the trusted site list. This list can be accessed from the Security tab. Select Trusted Sites and then click the Sites button.

You must restart Microsoft Edge for these settings to take effect.

Note

Kerberos authentication only works with Microsoft Edge when the server uses HTTP persistent connection.

Chrome™

Chrome inherits its settings from Microsoft Edge when you are using Microsoft Windows so will work providing you have configured Microsoft Edge as detailed above.

If you are using Chrome on Mac® OS X®, WDSSO works without any additional configuration but only uses NTLM authentication (meaning it will only return a NTLM token during the SPNEGO handshake). For Kerberos authentication, you must make additional changes in Chrome to authorize specific host or domain names for SPNEGO protocol message exchanges. You can do this via the command line in the Mac OS Terminal or by joining macOS to Active Directory:

  • Command line - perform the following steps in the Terminal app (these settings persist in Chrome once set, but you must run kinit every 10 hours to allow Chrome to request service tickets for the IWA adapter):
    1. Get a ticket-granting ticket (TGT) from your Kerberos Domain Controller (to allow service tickets to be requested) by entering the following command: $ kinit username@DOMAIN.COMWhere DOMAIN.COM is the FQDN of the Active Directory domain and must be in upper case letters. For example, FORGEROCK.COM
    2. Enter your password when prompted.
    3. Configure the AuthServerAllowlist and AuthNegotiateDelegateAllowlist settings in Chrome for any domains you are using (including the domain you ran the kinit command against) using the following commands: $ cd /Applications/Google Chrome.app/Contents/MacOS $ ./"Google Chrome" --auth-server-allowlist="*.domain.com" --auth-negotiate-delegate-allowlist="*.domain.com"Where *.domain.com is the host or domain names you want to authorize for SPNEGO protocol message exchanges. This is a comma-separated list and must include the domain you ran the kinit command against.
  • Join macOS to Active Directory - see Integrate Active Directory for more information.

In Chrome version 81 and above, using an incognito browser window will prevent NTLM/Kerberos authentication from working. If you require authentication to work in incognito mode, you must use the AmbientAuthenticationInPrivateModesEnabled policy.

Firefox®

If you use Firefox, you need to set the following two settings: network.negotiate-auth.trusted-uris and network.automatic-ntlm-auth.trusted-uris.

You can change these settings via about:config. Search for each setting and add the AM FQDN. See Mozilla Integrated Authentication for further information.

Safari®

Safari has built-in support for Kerberos SSO and no additional configuration is required.

Checking other configuration details

You should also check the following configuration details: 

  • The krb5.conf file has been set up; this file contains the Kerberos configuration information (see krb5.conf for details).
  • An Active Directory datastore is configured for the realm you are using and you can see the Active Directory users on the Identities page in that realm.
  • Your credentials are correct. You can check them by logging into the realm using the authentication tree that includes the Kerberos node or the authentication chain that includes the WDSSO module using your Active Directory user credentials. For example, the URL would be similar to this, where the authentication tree is kerberos and the realm is top level: http://host1.example.com:8080/openam/XUI/#login/&service=kerberos
  • The Service Principal Name (SPN) for the AM service is correct in Active Directory; ensure the FQDN, which matches the SPN in Active Directory is used and the specified authcontext matches the node/module used for Kerberos authentication. You can use the following command to check the SPN: $ setspn -l [account] replacing [account] with the name of the account created for AM. An example command looks like this: $ setspn -l openam and gives an output as follows: Registered ServicePrincipalNames for CN=OpenAM,OU=employees,DC=example,DC=com: HTTP/host1.example.com
  • The Kerberos realm name (FQDN of the Active Directory domain) is all in upper case letters everywhere (keytab, WDSSO module configuration, etc). For example, FORGEROCK.COM.
  • The userPrincipalName must be unique for all users.
  • If you are using Oracle® JDK 7, you must ensure both TCP port 88 and UDP port 88 are open in your firewall to allow communication between AM and Kerberos.
  • The Kerberos Server Name is an A record and not a CNAME, and that the reverse (PTR) record for that IP also resolves back to that Server Name.
  • If you are using the Windows Desktop SSO module as part of an authentication chain and Windows Desktop SSO fails, you may no longer be able to POST data to non-NTLM-authenticated websites. For information on a possible workaround, see KB251404: You cannot post data to a non-NTLM-authenticated Web site.

Checking connection to Kerberos Key Distribution Center (KDC)

Your firewall must be configured to allow necessary communications with Kerberos; see Kerberos and Firewalls for the required ports. 

You can test the connection to the Kerberos KDC using a third-party tool called HelloKDC.java. This tool will determine if there is a connection issue and give you guidance on what the issue might be. If it shows there is a connection issue, it means the issue is outside of AM and will need resolving before you attempt any further configuration / testing within AM

Note

This is a third-party tool that we suggest can be used for troubleshooting but is not supported by ForgeRock.

The following links provide information about the HelloKDC.java tool:

Example

The following example shows a connection issue returned from HelloKDC.java, which correlates to an exception in the Authentication logs:

  • HelloKDC.java output: >>>KRBError: sTime is Thu Jul 20 14:21:25 GMT 2017 1498776265000 suSec is 154839 error code is 25 error Message is Additional pre-authentication required ... KRBError received: Need to use PA-ENC-TIMESTAMP/PA-PK-AS-REQ
  • Authentication logs: amAuth:20/07/2017 20 14:21:25 GMT: Thread[http-nio-8443-exec-1,5,main]: TransactionId[daffa5fe-cca9-4a16-8cc3-dec02f21a81f-57] Exception : com.sun.identity.authentication.spi.AuthLoginException: Service authentication failed. Additional pre-authentication required (25) - Need to use PA-ENC-TIMESTAMP/PA-PK-AS-REQ

As you can see, both are showing an error code 25: Additional pre-authentication required (Need to use PA-ENC-TIMESTAMP/PA-PK-AS-REQ). Seeing the same error returned from HelloKDC.java confirms this issue is independent of AM and will need to be resolved outside of ForgeRock support. 

See Also

How do I set up Kerberos authentication in AM (All versions)?

OpenAM Windows Desktop SSO deep dive – part 1

Configuring and troubleshooting WDSSO in AM

How do I collect all the data required for troubleshooting AM and Agents (All versions)?

Java 8 - Troubleshooting Kerberos Login

Java 11 - Kerberos Requirements

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.