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

Overview

Typically, AM is deployed in a site environment with multiple AM instances running behind a load balancer, where:

• Authentication modules share the same configuration across all AM instances behind the load balancer; the configuration is not server specific. In terms of the WDSSO authentication module, this means the keytab file is also shared.
• Multiple AM instances in a site act as one under the configured load balancer's hostname.

When you configure the WDSSO authentication module in this environment, you need to ensure the service provider name is set to the load balancer host/domain rather than to a single AM instance and that this service provider name is used to create the keytab file. The steps you should follow to complete this setup are detailed in the following section.

Setting up the WDSSO authentication module in a load balanced environment

The following example details are used in this process:

• Load balancer / site FQDN - https://lb.example.com:443/am
• Service principal name: HTTPS/lb.example.com@FORGEROCK.COM

You can configure the WDSSO authentication module in a load balanced environment as follows:

1. Set up your separate AM instances in a site with a load balancer:
   • Configure your sites per: Configure sites and add servers
   • Configure your load balancer per: Load balancing; ensuring your load balancer has been configured to use the amlbcookie for routing (standard setup).
   • Restart the web application container in which AM runs to apply these changes.
   • Ensure you can access the load balancer FQDN (for example: https://lb.example.com:443/am) and successfully log in.
2. Create an Active Directory® account to use as your Kerberos™ principal (user), for example: amKerberos. See OpenAM Windows Desktop SSO deep dive – part 1 (Create an account in active directory for your Kerberos principal section) for further information on this step if required.
3. Formulate a Service Principal in Active Directory that uses the load balancer URL, this is being formulated to use in the next step when creating the keytab file. You should specify the Kerberos™ principal for authentication in the following format, where DC-DOMAIN-NAME is in upper case and is typically the Kerberos realm name (the FQDN of the Active Directory domain): HTTP/lbhost.domain@DC-DOMAIN-NAME For example: HTTPS/lb.example.com@FORGEROCK.COM
4. Create the keytab file for the WDSSO authentication module using a ktpass command such as: $ ktpass -out lb.HTTP.keytab -princ HTTP/lb.example.com@FORGEROCK.COM -pass +rndPass -maxPass 256 -mapuser amKerberos -crypto All -ptype KRB5_NT_PRINCIPAL -kvno nWhere:
   • princ is the name of the service principal you formulated in step 3.
   • pass is set to use a very robust password with the +rndpass and -maxpass options setting a random 256 character password on the account, which is then used to derive the key in the Kerberos service principal.
   • mapuser is the name of the user you created in step 2.
   • crypto is set to All to allow all supported crypto types to be used. If you do specify a specific encryption type and 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.
   • kvno - 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.

This ktpass command gives the following output:Targeting domain controller: WIN2012LAB.forgerock.com Successfully mapped HTTP/lb.example.com to amKerberos. Password successfully set! Key created. Output keytab to lb.HTTP.keytab: Keytab version: 0x502 keysize 84 HTTP/lb.example.com@FORGEROCK.com ptype 1 (KRB5_NT_PRINCIPAL) vno 0 e type 0x12 (AES256-SHA1) keylength 32 (0xc2072ad3157629437adbc7c2fa637fa4f8b6569e 12c446d5970cd52cf35f6b71)See OpenAM Windows Desktop SSO deep dive – part 1 (Creating a KeyTab file) for further information on this step if required.

5. Copy the generated keytab file to all AM instances in your site. You must place this keytab file in the exact same location on all servers as the keytab location can only be set in one place and this location is then shared across all instances (for example: /tmp/am.HTTP.keytab).
6. Update the WDSSO authentication module on one AM instance to use the service principal name you formulated in step 3 (for example: HTTPS/lb.example.com@FORGEROCK.COM). You can do this in the AM admin UI by navigating to Realms > [Realm Name] > Authentication > Modules > [Module Name] > Service Principal and enter the new value.
7. Update the WDSSO authentication module on one AM instance to set the location of the keytab file to match where you placed it in step 5 (for example: /tmp/am.HTTP.keytab). You can do this in the AM admin UI by navigating to Realms > [Realm Name] > Authentication > Modules > [Module Name] > Keytab File Name and enter the new value.
8. Restart the web application container in which AM runs to apply these changes.
9. Test the WDSSO authentication module going through the load balancer; that is, check that the protected sites and agents are configured to use the load balancer FQDN instead of an individual AM server. For example, you can authenticate with the WDSSO authentication module via: https://lb.example.com:443/am

See Also

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

OpenAM Windows Desktop SSO deep dive – part 1

How do I specify multiple Kerberos servers in AM (All versions) for failover purposes?

Configuring and troubleshooting Kerberos and WDSSO in AM

Install AM

Windows Desktop SSO authentication module

Related Training

N/A

Related Issue Tracker IDs

N/A