Connecting your Drupal site to a Microsoft Active Directory server
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.
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
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
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.
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.
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!