Active Directory

Microsoft's Active Directory (AD) provides a variety of network directory services including Lightweight Directory Access Protocol (LDAP) like functions. It is included in Windows 2000 Server and later versions of their operating system. The focus of this page will be with the LDAP authentication functions.

Trouble shooting AD and LDAP authentication

Warning: The PHP LDAP module does not seem to be present. Please ensure it is installed and enabled.

This usually means that the main ldap dll or one of the supporting dlls are missing. Let's start with the main one itself. Browse to http://(moodleserver)/admin/phpinfo.php and examine the "Configuration File (php.ini) Path" field to determine which php.ini is being used and open it with an editor. Find the line 'extension=php_ldap.dll' and take out the semi-colon if it is there. That semi-colon will stop it loading the module all together! While you have that file open, search for 'extension_dir' and note which folder it is set to. Open that folder and ensure the php_ldap.dll file is in there. If it isn't then put it in there. If that still hasn't fixed it you are missing a supporting dll, but you don't get told that. To see what dlls are missing open the Command Prompt and navigate to the php directory and execute the following line 'php -m'. You should get some error messages now. Ugly, but at least they give you information! Find the dlls listed and copy them to the php directory. You may now need to restart the apache/httpd service. Run 'php -m' again and you should be error free and the message in Moodle should be gone now.

LDAP-module cannot connect any LDAP servers

LDAP-module cannot connect any LDAP servers: 
Server: 'ldap://my.ldap.server/' 
Connection: 'Resource id #26' Bind result:

Getting this message when you are trying to log in is a result of incorrect details for the Bind user, or the user account having insufficient permissions in Active Directory. The best way to test and resolve this is use ldp.exe to test binding until it suceeds. There are instructions on installing ldp.exe below. Open the program and Connect to AD, giving the server name, then from the Connection menu choose Bind. Enter the details you think are correct and you will probably find that an error is returned. Try adjusting the accounts priveleges or another account until you are returned an "Authenticated as" message. Once you are sure your account can be used to bind to AD, check that the DN of that users name is correct. Expand the tree on the left until you find the user you used to bind. Right click on that item and choose Copy DN. Go to the User Authentication page in Moodle and paste the value into the ldap_bind_dn field. Add the password and you can now feel safe your user is binding sucessfully.

Getting correct CNs for Contexts and Creators

For those not familiar with AD this could be very confusing, and not that easy for some who are familiar with it. Again, ldp.exe is your friend. There are instructions on installing ldp.exe below. Open it up and expand the tree on the left until you find the group or user you want to use and right click on it and select Copy DN. Go back to the Moodle User Authentication page and paste that value into either ldap_contexts or ldap_creators.

Getting the right user_attribute

By default, Moodle uses an accounts cn (full name) to verify against, but most networks don't use a full given name for logon as it's too easy to guess and you can easily have two people with the same name. If this is the case for you too you need to tell Moodle to look at another field for the logon id. In ldp.exe navigate the tree on the left to find a user account, preferably your own. Double-click the item in the tree and full-details will be loaded into the screen on the right. Look down the details until you find your logon id and note the item listed against it. For me, and a lot of people, it is sAMAccountName. Copy this name and paste it into the ldap_user_attribute on the Moodle User Authentication page. There are instructions on installing ldp.exe below.

Installing ldp.exe Server Tool

ldp.exe comes as part of the Server Tools on most versions of Windows Server. Find your Windows Server installation disc and find a folder on it called Support\Tools. In there will be a SupTools.msi which will install the server tools if run. You should now have a folder under Program Files called Support Tools, in which will be ldp.exe. ldp.exe is also available in the Windows XP Support Tools, which you can download from Microsoft here. Alternatively, a single download of ldp.exe is available here.

Example Active Directory Configuration

Below is an example configuration for Active Directory. As detailed above, the values may vary based on your local Active Directory configuration, but should provide a good starting point for most cases.

ldap_host_url = ldap://ads.example.com
ldap_version = 3
ldap_preventpassindb = yes
ldap_bind_dn = bind-user@example.com
ldap_bind_pw = bind-password
ldap_user_type = MS ActiveDirectory
ldap_contexts = ou=moodleusers,dc=example,dc=com
ldap_user_attribute = sAMAccountName

Note that the ldap_bind_dn value should work in either the CN=bin-user,CN=Users,DC=example,DC=com format as shown in the main instructions or the bind-user@example.com format shown in this example.

Global Catalogs

Moodle currently only has limited support for multiple domain controllers; specifically it expects each of the LDAP servers listed to contain identical sets of information. If you have users in multiple domains this presents an issue. One solution when working with MS-AD is to use the Global Catalog. The Global Catalog is designed to be a read-only, partial representation of an entire MS-AD forest, designed for searching the entire directory when the domain of the required object is not known.

Enabling the Global Catalog

The Global Catalog is available on Windows 2000 and Windows 2003 Active Directory servers. To enable, open the ‘Active Directory Sites and Services’ MMC (Microsoft Management Console) snap-in. Extend ‘Sites’ and then the name of the Site containing the active directory forest you wish to use. Expand the server you wish to enable the Global Catalog on, right click ‘NTDS settings’ and select the ‘Properties’ tab. To enable, simply click the ‘Global Catalog’ checkbox. Under a Windows 2000 server it is necessary to restart the server (although it won’t prompt you to); under Windows 2003 server it is not necessary to restart the server. In either case you will generally have to wait for the AD forest to replicate before the Global Catalog offers a representation of the entire AD forest. Changes made in Active Directory will also be subject to a short delay due to the latency involved with replication. If your AD servers are firewalled port 3268 will need to be opened for Global Catalog servers. If your organisation uses Microsoft Exchange then it its highly likely that at least one Domain Controller will already have Global Catalog enabled – Exchange 2000 and 2003 rely on the Global Catalog for address information, users also access the Global Catalog when using the GAL (Global Address List)

Child Domains

If your organisation has a main domain example.org, staff and students are contained in two child domains staff.example.org and students.example.org. The 3 domains (example.org, staff.example.org and students.example.org) each have a domain controller (dc01, dc02 and dc03 respectively.) Each domain controller contains a full, writable, representation of only the objects that belong to its domain. However, assuming that the Global Catalog has been enabled (see below) on one of the domain controllers (for example dc01) a query to the Global Catalog would reveal matching objects from all three domains. The Global Catalog is automatically maintained through replication across the active directory forest, it can also be enabled on multiple servers (if, for example, you need redundancy / load balancing.)

To make use of this in Moodle to allow logins from multiple domains is simple. The Global Catalog runs on port 3268 as opposed to 389 for standard LDAP queries. As a result, still assuming the Global Catalog is running on dc01, the 'ldap_host_url' would be ldap://dc01.example.org:3268. The rest of the settings are the same as for other MS-AS Auth setups.

You should use the 'ldap_contexts' setting to indicate the locations of individuals you wish to grant access. To extend the example above a little: In the example.org domain users are all in the 'Users' OU, in the staff.example.org domain users are in two OUs at the root of the domain, 'Support Staff' and 'Teaching Staff' , and in the students.example.org domain students are in an OU indicating the year that they enrolled, all of which are under the 'Students' OU. As a result our 'ldap_contexts' setting may look a little like this: 'OU=Users,DC=example,DC=org; OU=Support Staff,DC=staff,DC=example,DC=org; OU=Teaching Staff,DC=staff,DC=example,DC=org; OU=Students,DC=students,DC=example,DC=org.' The 'ldap_search_sub' option should be set to 'Yes' to allow moodle to search within the child OUs.

Its worth noting that the Global Catalog only contains a partial representation of the attributes of each object, as defined in the Partial Attribute Set supplied by Microsoft. However common information likely to be of use to a general Moodle installation (Forename, Surname, Email Address, sAMAccountName etc) is included in the set. For specific needs the schema can be altered to remove or add various attributes.

In most cases the Global Catalog is read-only, update queries must be made over the standard LDAP ports to the domain controller that holds the object in question (in our example, updating a student's details would require an LDAP query to the students.example.org domain controller - dc03, it would not be possible to update details by querying the Global Catalog.) The exception to this would be in an environment where there is only a single domain in the active directory forest; in this case the Global Catalog holds a writable full set of attributes for each object in the domain. However, for the purposes of Moodle authorisation, there would be no need to use the Global Catalog in this case.

Group Policy Objects

Modifying the number of Active Directory objects to search:

By default most Active Directory Lightweight Directory Service (ADLS) only allows searches returning a limited number of objects per search. Since there is currently no Page control support in PHP 5.2.x which would enable smaller page searches you may need to check and verify you MaxPageSize settings to make sure LDAP Client searches can return enough user objects to support the number of authenticating users.

As your organization grows, you might need to change the number of objects to search
at some point in time. A simple rule of thumb is to maintain a MaxPageSize which is at least equal to the number of users being 
searched in an average organizational Unit or Group DN.

Setting the number for a group policy object (MaxPageSize):

  1. Start the MMC Active Directory Users and Computers snap-in. (Select Programs,   Administrative Tools, 
      Active Directory Users and Computers from the Start menu.)
  2. Right-click the container, and select Properties.
  3. Select the Group Policy tab.
  4. Select the Group Policy Object, and select Edit.
  5. Select the User Configuration branch, and expand Administrative Templates, Desktop, Active Directory.
  6. Double-click Maximum size of Active Directory searches.
  7. Select Enabled, and set the number (e.g.,1000)
     Click Apply.
  8. Click OK.
  9. Close the Group Policy Editor.

    MaxPageSize - This value controls the maximum number of objects that are 
    returned in a single search result, independent of how large each returned object is. 
    To perform a search where the result might exceed this number of objects, the client
    must specify  the paged search control. This is to group the returned results in 
    groups that are no larger than the MaxPageSize value.

    To summarize, MaxPageSize controls the number of objects that are returned 
    in a single search result.