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.
Troubleshooting 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 = firstname.lastname@example.org 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 email@example.com format shown in this example.
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. For the long version of how Global Catalogs work, you can checkout this TechNet article here.
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)
Enabling SSL over Global Catalog
While pointing the Moodle LDAP plugin to port 3268 provides the searching benefits provided by Global Catalog; it also does so in an insecure manner much like connecting to standard LDAP port 389 for queries.
If you are connecting to a remote Global Catalog, or to ensure your Global Catalog LDAP queries are secure, Active Directory provides port 3269.
Port 3269 works identical to 3268 except this communication is wrapped in SSL and works in the same manner is LDAPS would on port 636 while still providing the benefits of global catalog. Also note that using port 3269 has the same requirements as LDAPS therefore ensure that certificates are present and the port is open if troubleshooting.
Example host URL connecting to a secure Global Catalog port: ldaps://dc01.example.org:3269
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 - see Microsoft KB248717 for more information.
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.
Modifying the number of Active Directory objects to search:
By default Active Directory only allows searches returning a limited number of objects (1000) per search. PHP versions earlier than 5.4 do not support page control which would enable smaller paged searches. If using PHP prior to version 5.4, a workaround may be to modify your Active Directory MaxPageSize setting to make sure LDAP Client searches can return enough user objects to support the number of authenticating users. Be aware though that increasing MaxPageSize setting could adversely affect your Active Directory infrastructure. If you find that the script is not running through all of your users properly and you have MS Active Directory + over 1000 users, follow the instructions here to set the MaxPageSize setting to a number higher than your total number of users (both now and in future) to fix it. This is a forest-wide setting.
MS Active Directory + SSL
If the Certificate Authority is not installed you'll have to install it first as follows:
- Click Start -> Control Panel -> Add or Remove programs.
- Click Add/Remove Windows Components and select Certificate Services.
- Follow the procedure provided to install the Certificate Authority. Enterprise level is a good choice.
Verify that SSL has been enabled on the server by installing suptools.msi from Windows installation cd's \Support\tools directory. After support tools installation:
- Select Start -> Run, write ldp in the Open field.
- From the ldp window select Connection -> Connect and supply valid hostname and port number 636. Also select the SSL check box.
If successful, you should get information about the connection.
See Enabling LDAPS on the client side (Moodle server) for details on the client side configuration.
- LDAP authentication in Moodle
- Directory services overview in Wikipedia
- LDAP in Wikipedia
- Using Moodle Using multiple LDAP servers - Our students are on separate domain forum discussion
- Using Moodle How to use multiple LDAP servers with Moodle 1.8 forum discussion
- Microsoft TechNet Article - How Global Catalogs Work