Setting up an Active Directory DataStore in OpenAM

In this post, I've going to set up an Active Directory DataStore in OpenAM 13.5. If you are familiar with OpenAM's authentication and profile store facilities but struggle with the Windows side of things, then this post is for you.

Overview of Steps

1. Get OpenAM to trust the certificate on an Active Directory LDAPS service.
2. Create an account in the Windows domain for OpenAM to lookup accounts with (You aren't using the domain admin account, are you?! ).
3. Configure a DataStore in a new realm in OpenAM.
4. Testing login with the default DataStore module

Prerequisites

You'll need these things in place before you can follow the steps below:

1. An OpenAM deployment (I'm using OpenAM 13.5 here) set up on the hostname openam.windom.example.com. 
2. A Windows Active directory domain controller with active directory certificate services installed (this automatically enables LDAPS on port 636). 
3. This server has the hostname: svr1.windom.example.com, using the windows domain windom.example.com.

I've previously written a blog post on setting up a test active directory domain, including the full installation steps and a script for generating test data. I've used this setup as a basis for the steps in this post.

Trusting Active Directory LDAPS certificates

If we want OpenAM to use LDAPS to connect to active directory, then it needs to trust the public SSL certificate for the connection. If you followed my blog post on setting up an active directory domain, then this certificate will have been issued by active directory certificate services. So to get OpenAM to trust that certificate, we can get it to trust the certificate services CA.

First, let's use certutil on our Windows domain controller to export the public CA certificate from certificate services:

certutil -ca.cert -f ca.cer

Then import the certificate into the java cacerts truststore on each of the OpenAM servers in your deployment. On CENTOS 7, that command would look like this:

sudo keytool -import -trustcacerts -file ~/ca.cer -alias windom-ca -keystore /etc/pki/java/cacerts

Create an account in your Active Directory domain

The account we are creating here is used by OpenAM for authentication operations and profile manipulation. If you are using something more established than a simple test Active Directory domain, ask your Windows SysAdmin to do this for you.

In this example, the user is called openamLdap and it is located in an OU called "Service Accounts". This OU is put in place by the sample data script from my blog post on setting up active directory.

Use “Active Directory Users and Computers” to do add the openamLdap account (dsa.msc):

Note that I have set the password never expires flag here. What you choose to do here is up to you (and your security policy) but remember if you choose not to do this, you will need to keep track of password changes for this account.

Once you’ve done that, delegate some admin rights to that account using the active directory delegate control wizard. Below, I'm delegating control of the "User Accounts" OU to the user I've just created. Right click on the OU and select delegate control:

Above we are allowing openamLdap to manipulate users in our User Accounts OU. What you choose to do in your setup is up to you.

Once you’ve done that, enable advance view in active directory users and computers:

Then edit your new account, go to the attribute editor tab and scroll down to distinguished name. Copy this value, you’ll need it in a minute for the OpenAM setup:

Creating a DataStore in OpenAM

In OpenAM, create a realm in the top level realm called employees. In the employees realm, remove the default dataStore and add a new active directory dataStore:

Add the hostname(s) of AD servers with the port number, and add the DN of the user you created earlier. You can use the end of the user DN to get the LDAP base DN of the domain.

In this example, LDAPS is used (this is required if you want to change properties of accounts in AD). LDAPS is not enabled by default in AD. If you don’t have it setup, note that a quick way of enabling it is to install the Active Directory Certificate Services role and reboot. After having done that, you need to add the public cert of the Windows CA to the java cacerts file on your OpenAM server.

You may wish to alter the User and Groups OUs in the DataStore configuration. By default both of these point to the Users container in active directory, but this is usually not used in production active directory services because you cannot create OUs underneath this container. If you choose to alter the default search filters, remember that Active Directory does not support LDAP extensible match rules.

In my setup, I have set the LDAP organisation DN to point to my windomcorp OU, OpenAM is not concerned with anything outside of this. I've changed the default people container naming attribute to OU and my people container value to "User Accounts". This matches "OU=User Accounts,OU=windomcorp,DC=windom,DC=example,DC=com", the location of my regular user accounts which were set up by the script from my previous blog post.





I've done the same thing in the group configuration. The groups configuration must point to a valid LDAP entry that is accessible from our LDAP user account, otherwise OpenAM will fail to load the profile of a user after authentication.



Set the root DN for persistent search:

Now scroll to the top and hit save. Once you head back to the realm options, you should be able to see your users in the subjects tab. If you don’t go back and double check your settings and also look for any exceptions (..and "caused by" exceptions) in the "idrepo" debug log.

If you log out of OpenAM, you should be able to log in as a Windows user from the login page of the customers realm:

http://openam.windom.example.com:8000/am1350/XUI/#login/employees

What next?

In the steps above, we hardly touched on OpenAM's powerful authentication capabilities - we simply used the "DataStore" authentication module that is available by default. If we want our user to logon with something other than the CN, the best option is to use the Active Directory authentication module, which allows you login with different usernames. For example, you could specify sAMaccountName and mail as usernames.

The active directory authentication module also supports the LDAPv3 behera standard, which allows OpenAM to respond to situations such as account lockouts, expired passwords and passwords that must be changed.

In my next blog post, I'll go through the steps to configure this OpenAM deployment to authenticate users with Windows Desktop SSO - the Kerberos part of what is commonly referred to as Integrated Windows Authentication.