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.
Prerequisites
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.
I’ve previously written blog posts on setting up a test Active Directory domain and setting up an Active Directory dataStore. I’ve used these as a starting point for the steps in this post.
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:
Creating a KeyTab file
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/hostname.of.openam@KERBEROS.REALM.NAME -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.
For now, I’ve made a chain that only contains the Windows Desktop SSO module in order to observe any error messages that may occur.
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:
http://openam.windom.example.com:8000/am1350/XUI/#login/employees&service=wdsso
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.
That’s it!
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.
Comments are closed.
Hi Simon, great article, very thorough. Too bad it wasn’t available a month ago, it would have saved me a lot of time :)
One thing I wanted to point out (which perhaps you’ll mention in part 2 and I am jumping the gun) is that while Kerberos has no issue with associating multiple SPNs to the same set of credentials, Active Directory apparently does, but in a non-intuitive and convoluted way (This doesn’t seem to be an issue in MIT Kerberos as I didn’t run into this issue in a pure MIT Kerberos setup).
You can run the setspn -A command as many times as you want and associate multiple SPNs to the same AD user, but when you run the ktpass command to create a keytab, AD updates the UPN of that account to the princ variable of the ktpass command you just ran. Since Active Directory looks up the UPN of the service account to validate credentials, it effectively means that the relationship between the Active Directory User and an SPN is one to one (You can set the -setUpn command in ktpass which will not update the UPN, but then your service account is un-usable since your SPN doesn’t have a matching UPN and it will still fail the same way as below).
If you try to associate 2 SPNs to the same AD user and generate a keytab to add the second SPN, you just broke the first SPN.
Kerberos will fail with these exceptions:
javax.security.auth.login.LoginException: Client not found in Kerberos database (6)
…
Caused by: KrbException: Client not found in Kerberos database (6)
…
Caused by: KrbException: Identifier doesn’t match expected value (906)
…
Now most of the time, it won’t matter, because like you mentioned your OpenAM domain will be pointing to a virtual host for load balancing, so you only need one SPN, but in the case you need to have 2 SPNs it effectively means, you need 2 Active Directory Users (an Active Directory user per SPN).
Active Directory 2008 and 2012 have this issue/feature, I am not sure about earlier versions.
Disclaimer: I am not an AD expert, so if I missed something and there is a way around this in AD, I will be ecstatic to be corrected.
Great post, thank you!
We followed the detailed instructions, however we found ourselves struggling for three days trying to figure out why OpenAM was not accepting the kerberos tickets.
It turned out that we were missing the krb5.ini configuration file for Java. This file contains the required setup for kerberos to function correctly. Without it, Windows Desktop SSO is completely broken.
On a windows machine, this file is located at C:\WINDOWS\krb5.ini (linux is /etc/krb5.conf).
I think it would be beneficial to add this crucial piece of information to the guide as a separate step with instructions on what the contents should be. Here is the krb5.ini configuration that worked for us:
[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM
[libdefaults]
default_realm = EXAMPLE.COM
permitted_enctypes = aes128-cts aes256-cts arcfour-hmac-md5
default_tgs_enctypes = aes128-cts aes256-cts arcfour-hmac-md5
default_tkt_enctypes = aes128-cts aes256-cts arcfour-hmac-md5
[realms]
EXAMPLE.COM = {
kdc = ad.example.com
admin_server = ad.example.com
default_domain = example.com
}