Blog

Connecting your Drupal site to a Microsoft Active Directory server

Mark Davies explains how to configure Microsoft Active Directory and Drupal's LDAP module for Enterprise integration with Drupal

Drupal has become a hugely popular framework for building big websites and is becoming more and more widely used in government and public sector.  The likelihood of these organisations wanting to offer SSO to their users is pretty big also.

The Drupal Lightweight Directory Access Protocol or “LDAP” module allows, for organisations that hold their user data in an Active Directory installation, their users to login to the Drupal site using those credentials.

The setup of an Active Directory instance is a little outside the scope of this blogpost but there is a fantastic knowledge base article by Rackspace that guides you through the setup perfectly (http://www.rackspace.com/knowledge_center/article/installing-active-dire...).

The configuration screen (found at admin/config/people/ldap) is split into a number of tabs.  We will firstly be concerned with “Server”, this tab allows us to define our connection credentials to our Active Directory instance. Multiple server configurations can exist and we can even define multiple server configurations for a single physical LDAP server for things like, alternate base DN’s (Distinguished names) or alternate service accounts with different privileges.

Connection Settings

The connection settings screen is pretty self explanatory, fill it out with your server credentials, I would normally leave ‘Enabled’ un-ticked until you verify that everything is working correctly.

After the server connection details are entered, this is where things get a little more complicated.  The following fieldsets, Binding Method, LDAP User to Drupal User Relationships and LDAP Group Configuration all ask for DN’s or attributes belonging to LDAP objects.  I found the best way to navigate around the LDAP server was by using a third party piece of software called ‘Apache Directory Studio’.  It is available free on OSX, Windows and Linux!  Here are a few common terminologies used in LDAP.

  • DN - Distinguished name
  • DC - Stands for domain component and is used to specify domain or ap‐ plication partition objects
  • CN - Common name
  • O - Organization name
  • OU - Organizational unit name C Country name
  • DC - Domain component
  • UID - User ID

Binding Methods

The LDAP.module suggest using a Service account to allow for searches and to determine user objects and their groups memberships.  Within our LDAP instance we created a service account ‘Code Enigma’, we can use the Apache Directory Studio to drill down to that user object and determine its DN.

From the screenshot above we can see that our Code Enigma user has a Distinguished name of

CN=Code Enigma,CN=Users,DC=windows,DC=codeenigma,DC=com

We use this DN to populate the following section of the form, along with its password to allow it to authenticate to the Active Directory server.

Our base DN for users, groups and other entities can be found in the same way.  Our Base DN for our users for example is CN=Users,DC=windows,DC=codeenigma,DC=com which exists one level above our Code Enigma user.

 

LDAP Group Configuration

Name of Group Object Class
We find the name of the group object class in the same way, we drill down the LDAP tree and find the groups under CN=BuiltIn.  In this instance our group object class is named ‘group’.

Attribute in User Entry Containing Groups
This value is taken from the attribute that lists a users group memberships.  In our instance this is memberOf, from the screenshot below you can see that the user ‘mark’ is a member of both Administrators and Users.

Once you have your connection setup and working, we can move onto setting up how the site will interact with the LDAP server.

LDAP to OG group Configuration

The Drupal LDAP module comes bundled with “LDAP Authorization - OG (Organic Groups)” module that allows us to automatically join users to Drupal groups dependant on their LDAP groups.

The workflow for achieving this is to inspect your LDAP server and make note of the groups you want users to automatically join as an Organic Group.  The LDAP module does not provision these Organic Groups for us, therefore we need to create the Organic Groups and map them from LDAP to Drupal. 

Using ‘Apache Directory Studio’ we can find the DN to our individual groups, such as for Administrators.

CN=Administrators,CN=Builtin,DC=windows,DC=codeenigma,DC=com

The mapping of LDAP to OG group is in the format, DN|Organic Group Title:Member Type.  Using the screenshot above as an example, I created an Organic Group called 'Administrators' and used the following code in the "Mapping of LDAP to OG group (one per line)" textarea.

CN=Administrators,CN=Builtin,DC=windows,DC=codeenigma,DC=com|node:Administrators:member 

The help text here is great and explains things very well, note that once you save, the module appears to append a shorthand version of your definition in the format (raw: node:1:2).

This format can be helpful if your Organic Group's title contain a : in the title, you can then use the alternative definition format DN|Organic Group ID:Member Type.

LDAP to drupal role Configuration

The role configuration is much the same as the Organic Groups settings.  We simply discover what our Role DN's are in LDAP and map them to Drupal roles using the form provided.

The above configuration will map an Administrators group in Active Directory to an Administrtors role in our drupal install.  The common name (CN) of the group and the role name do not have to match here, we are simply mapping one onto the other.

The "Create drupal roles if they do not exist" is an important setting that is hidden under "Part III. Even More Settings.", without this ticked any roles will not be created and only existing roles will be mapped.  This may be the setup that you wish but it is without doubt a gotcha to look out for.

 

I hope this helps get your site up and running with Drupal, Active Directory and LDAP!

 

Add comment

Log in to post comments

5 Comments

One other awesome feature you didn't mention, is the ability to take AD fields and insert their values into user fields. This is great for bringing things over like department, phone, etc.

Very true, field mappings are fairly straightforward so we didn't bother, but yes - awesome feature! We use it with our own internal OpenLDAP set-up and Drupal intranet.

I gave 1x and 2x a go ~6 months ago .... if this is all actually working now; I might take another look at it ...

Hi,

I read your blog with Apache Directory Studio I am getting all the parameters LDAP service name, but not getting distinguished name. One thing you mentioned about Service account above. What it is? How we can create it and from where? Please guide me about LDAP.

The screenshots from the post are taken from OSX, Apache Directory Studio's layout may differ from platform to platform. Distinguished Name is commonly referred to as DN, can you see that anywhere on the LDAP attributes screens? In OSX it can be found just below the blue tab as seen in a few of the screenshots above.

The Apache Directory Studio user guides can also be found here: http://directory.apache.org/studio/users-guide.html which may help explain further.

The service account is just like any other user account, except that it doesn't belong to any 'real life' person and is generally used for admin/system tasks. I like to think of it as a system account that can be used without sharing sensitive login details of 'real' users.

You can create new user accounts by finding CN=Users in the LDAP tree, right clicking and selecting New Entry. This should list you with a number of Objects that you can create, within that list you should be able to find an inetOrgPerson or person depending on your preferences.

I hope this helps.