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

Background information

The Kerberos node or WDSSO module allows users logged in to Microsoft® Windows® to access a resource protected by AM without further authentication. Prior to setting up the Kerberos node or WDSSO module, you should ensure Kerberos is configured correctly; in particular, you should ensure the krb5.conf file has been set up (see krb5.conf for details) and that your firewall allows necessary communications (see Kerberos and Firewalls for the required ports).

Some key things to be aware of when configuring the Kerberos node or WDSSO module are:

• The userPrincipalName must be unique for all users.
• 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.
• You must restart the web application container in which AM runs after making configuration changes to the Kerberos node or WDSSO module.
• If you are using the WDSSO authentication 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.

Setting up Kerberos authentication

The following steps are required to set up Kerberos authentication:

1. Configure your browser for Kerberos authentication. The settings needed are specific to the browser you are using as detailed in the Browser Settings section below.
2. Configure either the Kerberos node or the WDSSO module:
   • Kerberos node: navigate to: Realms > [Realm Name] > Authentication > Trees > [Tree Name] in the AM admin UI and configure the node according to your setup. See Kerberos node for further information.
   • WDSSO module: navigate to: Realms > [Realm Name] > Authentication > Modules > [Module Name] in the AM admin UI and configure the module according to your setup. See Windows Desktop SSO authentication module for further information on these options.
3. Restart the web application container in which AM runs to apply these configuration changes.
4. Set the login URL for the resource you are protecting so that it includes your Kerberos node or WDSSO module. For example:
   • Kerberos node:https://am.example.com:8443/am/XUI/?realm=/myrealm#login&service=kerberos
   • WDSSO module:https://am.example.com:8443/am/XUI/?realm=/myrealm#login&module=WDSSO

This means a user won't need to authenticate again when accessing this URL providing they are already logged in to Microsoft Windows.

Video demonstration

There is a video demonstration available for setting up the WDSSO module in OpenAM 10.0.0: Windows Deskop SSO; although the appearance has changed between OpenAM 10.x and later versions, the principles and processes are still applicable.

Browser Settings

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

• Microsoft Edge
• Chrome
• Firefox
• Safari

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.

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.

Safari®

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

See Also

OpenAM Windows Desktop SSO deep dive – part 1

How do I set up the WDSSO authentication module in AM (All versions) in a load balanced environment?

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

How do I enable debug logging for troubleshooting Kerberos and WDSSO issues in AM (All versions)?

Configuring and troubleshooting Kerberos and WDSSO in AM

Authenticating with Windows Desktop SSO in AM (All versions) does not proceed when using a non-Microsoft Edge browser

Windows Desktop SSO authentication module

Related Training

N/A

Related Issue Tracker IDs

N/A