PORTFOLIO

Drupal 7 / LDAP Tutorial

What is LDAP?

TheLightweight Directory Access Protocol(LDAP (http://www.openldap.org/)) is an open,

vendor-neutral, industry standard application protocol for accessing and maintaining

distributed directory information services over an Internet Protocol (IP) network."

This is a guide for a common integration of syncing users and groups between LDAP

andDrupal 7.

What We Need:

* An LDAP server for testing.

Note: Best practices dictate that your Drupal instances user credentials come from and are

managed by the LDAP server.

If you dont have your own LDAP server, heres a working public server (Open LDAP) you can

use to test your con guration (http://www.forumsys.com/tutorials/integration-how-

to/ldap/online-ldap-test-server/):

Server: ldap.forumsys.com
Port: 389
Bind DN: cn=read-only-admin,dc=example,dc=com
Bind Password: password
Individual users are represented with: uid
Groups are represented with: ou
All accounts except nogroup and test have an email address associated with them:
@username@ldap.forumsys.com

*A running Drupal instance with the following modules enabled:

Backup and Migrate (https://www.drupal.org/project/backup_migrate)

Context (https://www.drupal.org/project/context)
CTools (https://www.drupal.org/project/ctools)
Devel (https://www.drupal.org/project/devel)
Entity (https://www.drupal.org/project/entity)
EntityReference (https://www.drupal.org/project/entityreference)
Features (https://www.drupal.org/project/features)
Feeds (https://www.drupal.org/project/feeds)
Job_Scheduler (https://www.drupal.org/project/job_scheduler)
LDAP (https://www.drupal.org/project/ldap)
OG (https://www.drupal.org/project/og)
Panels (https://www.drupal.org/project/panels)
Views (https://www.drupal.org/project/views)

*Apache Directory Studio (https://directory.apache.org/studio/) - if youre operating o of your

own server, you will likely need some method of navigating through the LDAP directory and
dialing down to speci c information, such as organization and labeling parameters.

Getting Started:

Before we hop into our Drupal instance and start the LDAP con guration, lets take a look at the
LDAP server and make sure that we can connect to it and identify some essential pieces of

information - Ill be usingApache Directory Studio. We need to enter the hostname, port, bind
DN, and bind password (use simple authentication). Depending on your server's

con guration, you'll want to make note of how groups (ou) and users (uid) are categorized. On
the test server, we have three primary groups (chemists, mathematicians and scientists) and

fouteen users. Take a look at the screenshots below to see how our test server is con gured.

Now its time to enable the new modules we committed, so lets head over to our Drupal

instance make our way to Modules.

Once all that's done, were ready to start con guring the LDAP module. Lets navigate over

to:/admin/con g/people/ldap (example: dev-your-site-name.com/admin/con g/people/ldap

or, from within Drupal, click Con guration at the top of the navigation bar, and then, in the
upper-left section, People, select LDAP Con guration. We'll continue the con guration in our
next post, please stay tuned.

LDAP Module Con guration - /admin/con g/people/ldap

There are seven sections in the LDAP module, lets walk through the settings for each one

(based on the LDAP settings we looked at earlier):

1. Settings (no settings need to be changed)

2. Servers
3. User
4. Authentication
5. Authorization
6. Queries
7. Help

Servers - let's start by selecting Add LDAP Server Con guration, and here we'll de ne our

various Connection Settings - note, these are based on the attributes that we obtained from
the LDAP server earlier. If you're using the test server provided, just follow along. Name your
server, de ne the LDAP Server Type as Open LDAP, the LDAP Server will contain the server
address (we're using ldap.forumsys.com) and the Port is 389.
Our Binding Method is Service Account Bind, and our DN is cn=read-only-
admin,dc=example,dc=com. Our password is...well, password.

Within Base DNs for LDAP users, groups, and other entries, we're going to use the high-level

dc=example,dc=com - that way we get all of the groups and their users. Next we have to de ne
some basic attributes, the AuthName attribute is uid and the Email attribute is mail.
Within LDAP Group Con guration we need to de ne the Name of Group Object Class, which is

ou. Because we're using nested groups, select the checkbox for Nested groups are used in my
LDAP. For LDAP Group Entry Attribute Holding User's DN, CN, etc. we will once again use uid,

and for User attribute held in "LDAP Group Entry Attribute Holding..." we're going to use cn.

Save the settings for Servers and we'll move on to User momentarily - let's run the test function
and make sure that our Drupal instance can communicate with our LDAP server.
Looks good. Make sure to enable the server before moving on.

(/)
(/)
SERVICES (/SERVICES) CLIENTS (/CLIENTS) WORK (/WORK) TESTIMONIALS (/TESTIMONIALS)
For How to resolve LDAP con icts with manually created Drupal accounts (e.g. admin on

Drupal
ABOUT+US
admin on the LDAP
(/ABOUT-US) server),
BLOG (/BLOG)select Reject manual creation of Drupal accounts that

con ict with LDAP Accounts... and be sure to select the server settings for LDAP that we
(https://www.facebook.com/blackantelope)
created within the module earlier, in our case it'smyldap.
(https://www.behance.net/blackantelope) Within Drupal Account Provisioning
(/contact)
Events I prefer to select both Create or Synch... settings in order to keep user changes

consistent on both systems (i.e. Jane Doe changes her password in one place instead of
several).
Existing Drupal User Account Con ict - select Associate Drupal account with the LDAP
entry..., and for Application of Drupal Account settings to LDAP Authenticated Users select

Account creation settings...do not a ect "LDAP Associated" Drupal accounts. Please note

that I prefer to avoid deleting accounts whenever possible, so under Action to perform on
Drupal account that no longer have a corresponding LDAP entry, I select Perform no action,

but email list of orphaned accounts. It would make plenty of sense for others to select Disable

the account and keep its content.

In our example, I select None under LDAP Servers to Provision LDAP Entries on because I
don't want our Drupal instance committing changes to the LDAP server.
On to the Authentication section of the module - the settings here are pretty straightforward

and it's mostly the defaults. Be sure to select Mixed mode in the Allowable Authentications

and that our server is selected within Authentication LDAP Server Con gurations.

For the entire Email section, I'd only suggest the following alterations: Email Template
Handling - select Use the template if no email address was provided by the LDAP server, and
beneath that, the template is: @username@ldap.forumsys.com, you'll want this for any users

on the LDAP server that don't have an associated email address. Best practices require that
users have an email address associated with an account in any content management system,
so con guring the module to implement a correctly structured email address based on the

username and proper domain name (@ldap.forumsys.com, for example) is likely appropriate.


Authorization, Queries & Help are the last sections of the LDAP module, but we won't be using

Authorization or Help. We'll most de nitely need Queries later on - the next part of this guide,
actually.

Writing an LDAP Query -

/admin/con g/people/ldap/query/add

For con guration purposes we're going to pull all users from the LDAP server and as long as
they have a valid username and email address, theyll populate in the system (using the test

server I provided earlier, two will be ignored).

For our base DNs to query were going to enter the following: dc=example,dc=com
Our lter is going to be any user (no groups) that are designated a user: (objectClass=person)
Because the LDAP server were using isnt particularly intricate in its con guration, Im going to opt to pull all
attributes, so I dont need to enter anything in the section Attributes to return.

Please note that Base DN's to search in query and Filter are what drive our query and are
crucial in this con guration to adequately pull the data we need from our LDAP server (DN's,

uid's, email addresses, etc.) As I indicated earlier - we're using an open-ended, generic query for
our test server because we're simply pulling all users and their attributes from the LDAP test
server to our Drupal instance.

Now it's time to test our query.

Success! As you can see, our query returns all of the users from the LDAP server - from their
DNs to their email addresses.

Advanced LDAP Queries

For a more comprehensive guide on writing your own queries please see the following link:

https://www.google.com/support/enterprise/static/gapps/docs/admin/en/gads/admin/ldap.5.4.html
(https://www.google.com/support/enterprise/static/gapps/docs/admin/en/gads/admin/ldap.5.4.html)

Adding Fields to User Settings -

/admin/con g/people/accounts/ elds

This section is pretty straight-forward, were going to add some elds for use in our LDAP Feed -
this part 1 of where we link elds in Drupal to the IDs we obtained from the LDAP server

earlier.

Were going to make two new elds based on our LDAP servers con guration: Full Name and
DN Field (Distinguished Name Field). Both are Field Type = Text and the Widgets = Text Area.
You don't need to make any speci c changes to the eld itself during the creation process, we

just need two text elds that we'll refer to during the creation of our feed in the next part of the
walkthrough. Take a look below if you're unfamiliar with creating new elds within Drupal.

That's all for now - our next and nal entry will detail the creation & automation of a feed

(this is how we'll set Drupal to execute our query and pull in new users and updated user
passwords automatically.)

Creating an LDAP Feed - /admin/structure/feeds/create

To begin, name your feed and click Create to continue. There are four sections to complete:

1. Basic Settings (leave Periodic Import OFF until youve successfully imported your LDAP servers users
using the query we created earlier - this is detailed in the next section, LDAP Import)
2. Fetcher (we will be using LDAP Query Fetcher instead of the Drupal User LDAP Entry Fetcher)
3. Parser
4. Processor

Theres actually very well-written Drupal community documentation for this section, please see
the following link for a generic setup - our setup is slightly di erent:
https://www.drupal.org/node/1300812/ (https://www.drupal.org/node/1300812/)

Let's begin with Basic settings - we need to name our feed, set Attach to content type to Use
standalone form, and again - leave Periodic import OFF.
Next, we're going to change Fetcher and select LDAP Query Fetcher.

Now, withing Fetcher settings you'll want to select the LDAP Query we created earlier ("pull
ldap users").
In the change section of Parser select LDAP Entry Parser for Feeds.

Within the Processor section we need to select User processor (after all, our intent is to pull

users and their attributes from the LDAP server.)

In the Settings for User processor section, we're going to select Update existing users, Plain
text for formatting, and set the users to Active. Of course this all depends on your setup's
speci c needs - some of you may want to Replace existing users, or you'll want the users

imported and updated but blocked in order to avoid giving them access to the system during
testing.

Last but not least, in Mapping for User processor we need to de ne the elements/attributes

that we're using, as these will de ne the Drupal users that we create based on the LDAP
server's users. In our example we want to bring over the Full Name (cn) that we de ned earlier,
the User Name (sn), and the Email address (mail). We also want to make sure that we mark

these as Unique. Now it's time to test our feed!



LDAP Import - /import

From the Import page were going to select the feed we created earlier (it should be the rst

availabe option in the list) and it will take us to a page where we can test our LDAP query -
simply select the query we created earlier ("ldap feed") and hit import. As long as the accounts
in question have valid usernames and email addresses they should all import without issue. If
theres a problem during the import Drupal will note success/failure and there are sections to

assist you in troubleshooting - the Log tab identi es what failed and why, and the Delete Items
tab allows you to remove all users generated via the import (in case you need to try again -
which is likely if you have a more intricate query executing).

Import Automation - /admin/structure/feeds

Lets head back to the feed we created earlier, select Edit and under the Basic Settings section
on the left, select Settings. Simply set Periodic Import to Every 15 minutes and Save, thereby
setting your feed to import any users created within the LDAP server automatically.

Congratulations! You've written a query that recurringly executes via feed and further changes
to your LDAP user and group base will be a ected in Drupal.

Tags
Drupal (/blog/tag/drupal)
Tutorial (/blog/tag/tutorial)
LDAP (/blog/tag/ldap)

Recent Posts
Drupal 7 / LDAP Tutorial (/blog/drupal-7-ldap-tutorial)

Programatically creating a nested taxonomy list in Drupal 7 (/blog/programatically-creating-nested-

taxonomy-list-drupal-7)

Tags
Drupal (/blog/tag/drupal) LDAP (/blog/tag/ldap) Programming (/blog/tag/programming)
 Tutorial (/blog/tag/tutorial)

2016 Black Antelope. All Rights Reserved.

(https://www.facebook.com/blackantelope)
(https://www.behance.net/blackantelope) (/contact) Get in touch with us
$
RECENT POSTS (/contact)

Drupal 7 / LDAP Tutorial (/blog/drupal-7-ldap-tutorial)

March 15th, 2016

Programatically creating a nested taxonomy list in Drupal 7 (/blog/programatically-creating-nested-taxonomy-list-

drupal-7)
March 15th, 2016