Tuesday, 29 November 2016

A Beginners Guide to OpenIDM - Part 6 - Provisioning to Active Directory

Last time we looked at configuring user registration. So now we have our users? How do we get them into our other systems? For example a user directory, in this case Active Directory (AD) ?

In this blog we will take a look at configuring OpenIDM provisioning, which consists of synchronisation to AD and reconciliation from AD. We will collect those accounts already in Active Directory and also create new AD accounts for our new identities.

Note that the concepts introduced here are easily applied to another LDAP ( such as OpenDJ ) or even other systems ( also likely to be covered in later blogs ). I have chosen Active Directory because it is a something I have commonly encountered throughout my career. Furthermore I am going to assume you have an Active Directory instance up and running. If not feel free to use OpenDJ or any other LDAP as the steps will be broadly similar.

Note: As many of you will be aware OpenIDM 4.5 has recently been released, for now I am going to continue using OpenIDM 4 for this blog but everything we talk about here is still applicable to 4.5, albeit with minor differences. I will likely move to OpenIDM 4.5 (or 5 even) when the beginners series is concluded.

This blog continues my OpenIDM Beginners series, catch up with the links below:

Provisioning in OpenIDM

I have always used provisioning as a bit of an umbrella term for both account creation and reconciliation. As we have discussed in previous blogs OpenIDM is based on the concepts of connectors and mappings. Connectors interface with external systems, while mappings define how attributes flow between OpenIDM and the external system.

So there are a few moving parts here. We need to:
  • Configure an AD connector.
  • Configure a mapping from AD accounts to an OpenIDM user object.
  • Configure a mapping to AD accounts from an OpenIDM user object.
So we have a little bit of work to do here. Lets get started.

Note: I will cover groups in another soon to be written blog entry.

Configuring the Active Directory Connector

Login to OpenIDM as the administrator. Navigate to connectors and create a new LDAP connector:

Select LDAP Type as AD LDAP Configuration, accept any prompts:

Enter your host name or IP, port, and Distinguished Name (DN) of the account you will be connecting as. 

Creating and updating users in Active Directory typically requires you to be connected over LDAPS (LDAP over SSL). For now Lets just get the connector working over LDAP. In a minute, we will configure LDAPS.

And the base context:

Then save your changes. As in the previous blog, to test if the connector is working we can view the accounts.

We should see a list of users in Active Directory:

Configuring LDAP over SSL

Now we have a working integration, we need to go back and configure SSL. First we need to get the AD LDAP SSL certificate into the OpenIDM truststore. The easiest way I have found to do this is as follows:

openssl s_client -connect -showcerts

The above command will retrieve the certificate from AD. You want to copy the certificate:


And copy it into another file somewhere as text e.g. ldaps.pem

Then you need to import into the OpenIDM truststore

keytool -import -alias ldaps -file ldaps.pem -keystore /usr/local/env/blog/openidm/security/truststore

Now, you can go back to the connector configuration and check the Over SSL box (ignore show certificate). Once done, save the connector and test. 

All being well it should still work and we can set about the interesting bit, provisioning!

Creating a Mapping

Now we need a mapping, navigate to configure, mappings, and create a new mapping from the User Object to our new User Directory. Note that this mapping, although data flows from OpenIDM to Active Directory, will manage provisioning of new AD accounts as well as reconciliation of existing ones and matching to user identities.

As before, we need to map AD attributes to user identity attributes. Let's just add the minimum required for now. Press "Add Missing Required Properties". This will add any required properties to the mapping as specified by the schema. In theory this should be the minimum set we need for the reconciliation to work.

Now we need to map dn and sn. Distinguished Name ( dn ) is an attribute that has to be generated from the data in our identity. Select dn and set a source property:

Press Update.

Select dn again and navigate to Transformation Script.

What we have here is an inline way to quickly write scripts to transform attributes.

Note: The source property we set above userName is used as the current value for the source value in the script above.

Enter the following inline script: 

"CN=" + source + ",OU=User Accounts,OU=trustzone1corp,DC=trustzone1,DC=forgedemo,DC=co,DC=uk"

Press Update.

Now we also need to map sn and typically we also need samAccountName. Add both in the usual way and we should have:

Note: I have had at least one report that you may also need to map the __ENABLE__ attribute here. If you get an issue, try that.

Press Save Properties.

Configuring Correlation

Then navigate to Association, Association Rules. Select Correlation Queries and Add Correlation Query.

Remember to set the Link Qualifier to default.

This will have the effect of linking AD accounts to users based on the sAMAccountName in AD matching the username in OpenIDM.

With this done, Submit, Save, then Save and Don't Reconcile ( you will see why in a moment ).

Navigate to Behaviors and as in the earlier blog, set the current policy to Default Actions and Save.

Remember, when a mapping is created this is set to Read-only, effectively a testing state for mappings where no changes will be made to data in OpenIDM or the target system. 

Now, scroll up and press Reconcile Now.

Expand In Progress:

And you should see the results of reconciliation, note we have 100 Absent conditions.

If you look at the Behaviors tab you should see that:

The Absent condition corresponds to the Create operation. So.. we should now have 100 users created in our Active Directory. Sure enough if you take a look in Active Directory Users & Computers that is indeed the case.

Reviewing Associations

Finally, you can take a closer look at the results in OpenIDM, again navigate to our mapping, view the Associations tab and scroll down. You should see something similar to the following:

If you play with the View selector you can see the results for each behavioural situation encountered.

Linked Systems

If you navigate to Manage, User, then select a user you should be able to see that they now have a Linked System for AD:

If matching accounts had already existed in AD, then OpenIDM would not re-create them. Instead they would be linked to a user as above based on the correlation query we defined earlier. If you quickly re-run the synchronization process we can confirm this:

This time we see Confirmed instead of Absent. As the accounts already exist.

All OpenIDM needs to do is Update the account if something has changed.


So in this blog we configured a basic provisioning integration between OpenIDM and Active Directory. Now typically you will want to set up more attributes, including a password. You will also want to reconcile and assign LDAP groups, probably based on roles. I plan to look at all of these requirements in a future blog building on the work we have already done here ( note it does not matter if you used AD or another LDAP for this exercise, any future exercise will still be valid ).

Hope you have found this useful!