This post will walk you through the necessary steps to configure OpenAM to authenticate users automatically using Windows Desktop SSO (Integrated Windows Authentication). The OpenAM configuration is quite straightforward, but there are a number of things that need to be in place on the Windows side for everything to work correctly.
Overview of Steps
- Set up the required forward and reverse lookup DNS records for OpenAM.
- Make a Kerberos principal and keytab file in Active Directory using the ktpass command.
- Configure OpenAM for Windows Desktop SSO.
- Configure your web browser.
- Make sure profiles can be loaded from the Active Directory dataStore.
- Configure OpenAM to fallback to a username and password when Windows Desktop SSO fails.
This guide assumes the following prerequisites are in place:
- An OpenAM deployment (I’m using OpenAM 13.5 here) set up on the hostname openam.windom.example.com.
- A Windows Active Directory domain controller with Active Directory certificate services installed (this automatically enables LDAPS on port 636).
- This server has the hostname: svr1.windom.example.com, using the windows domain windom.example.com.
- OpenAM setup with an Active Directory dataStore, with users being able to log on using a username and password.
- A test Windows Desktop or a separate session on your test domain controller.
Setting up DNS
- A user may access OpenAM via a given hostname, which would often point to a load balancer.
- The user must be able to resolve the OpenAM IP address from a DNS forward lookup on the hostname.
- The hostname returned from a reverse DNS lookup on the OpenAM IP must match the hostname used in the forward lookup.
- A keytab file should be generated with a Kerberos principal name, which consists of a hostname and a realm name. The hostname in the principal name must match the hostname by which the user can access OpenAM, even if that is the external load balancer hostname.
- The principal name configured in the OpenAM Windows Desktop SSO module must match the principal name of your key in your keytab file.
For Windows Desktop SSO to work, the URL accessed by the user must resolve on a forward AND a reverse DNS lookup with the same IP address and host. This is part of the Kerberos Spec.If you don’t have a reverse lookup zone configured on a DNS server in your active directory domain (isn’t set up by default), you’ll need to set one up in DNS Management (dnsmgmt.msc):
Now it’s time to specify the subnet for your reverse lookup zone. Note that as part of the DNS standard, only class A, B and C blocks are supported.
The subnet here should contain what is seen to be the IP address of OpenAM from the user’s point of view. This is probably the subnet containing your load balancer address.
Now create a reverse DNS record for OpenAM. If OpenAM is behind a load balancer, use the IP address of the load balancer. If you don’t already have a forward lookup record (‘A’ record) then you can create both a forward reverse lookup record at the same time when creating an ‘A’ record by selecting “create associated pointer record”:
If you already have an ‘A’ record for OpenAM, you can assign a PTR record (reverse lookup record) to OpenAM by right clicking on your reverse lookup zone and selecting “New Pointer (PTR)…”
Now that everything is in place, you should be able to perform a forward and reverse DNS lookup on OpenAM and get matching results, like in the following screenshot:
Create an account in active directory for your Kerberos principal
Create an account in Active Directory Users and Computers (dsa.msc) to use as your Kerberos principal. Don’t worry about what the password is, you are about to change it in the next step.
Note that I have set the password never expires flag here. What option you choose is up to you (and your security policy) but remember that when the account password expires, the Kerberos key in your keytab file will need reissuing.
OpenAM uses the GSS API for Kerberos which supports the full 256bit strength of Kerberos encryption, as long as the Java unlimited strength cryptography policy is installed. Select the option to ensure the account supports 256 bit Kerberos encryption in the the account tab:
The following is an example of running the ktpass command on an active directory domain controller. The +rndpass and /maxpass options set a random 256 character password on the account which is then used to derive the key in the Kerberos principal.
ktpass -out fileName.keytab -princ HTTP/[email protected] -pass +rndPass -maxPass 256 -mapuser <userAccount> -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -kvno 0
As it is case sensitive, make sure that the principal name is in exactly the following format:
…where, openam.windom.example.com is the host name of OpenAM. If OpenAM is behind a load balancer, make this the hostname of the load balancer. MYDOMAIN.EXAMPLE.COM is the name of the Kerberos realm – the FQDN of the Active Directory domain.
In the domain we’ve been building so far, the command will look like the below:
You should now have a keytab file:
This file contains sensitive authentication keys. You should store it in a protected file system location, in a similar way to protecting private SSL keys.
Setting up Windows Desktop SSO in OpenAM
Once that is complete, you can make a chain in your realm to begin testing the new authentication module.
Configuring the web browser
Authentication should still succeed, but it’s not a very user friendly experience.
This is likely the only configuration required in the browser settings. However, if you are having problems with IE or Edge specifically, check that “Enable Windows Integrated Authentication” is selected on the advanced tab:
Now try authenticating using the “wdsso” chain:
Make sure your dataStore can load a profile after authentication
At this point, you should now be able to authenticate using Windows Desktop SSO. But what happens when the user isn’t using a domain-joined computer?
Configuring fallback to the dataStore module
Note: Versions of OpenAM prior to v.13.0.0 required a custom error page to be implemented, allowing a failed login on the Windows Desktop SSO module to progress to the next module in the chain. This is no longer required.
UPDATE: That’s not quite always true. The change in OpenAM 13 allows the WDSSO module to fall back to another module if the browser has negotiate support turned off, for example as it is by default in Safari and FireFox. However, this won’t prevent the login dialog (shown above) from appearing if negotiate support is turned on in the browser, as it is by default in IE. I’ll look into this in more detail in my next blog post. Thanks to my colleague Cyril Grosjean for pointing this out.
Windows Desktop SSO should now authenticate users who are logged in on a domain-joined computer to OpenAM.
Part 2 of this blog post will look at the mechanics behind Kerberos authentication by analysing the network traffic and will also address common scenarios that can cause Windows Desktop SSO to fail.