Contact
subscribe to this post
Mar 23, 2009 
Configuring the LDAP Authentication plugin for MediaWiki can be a daunting task. In this series of posts, I’ll go over the basics of configuring the plugin for common environments. In a later series of posts, I’ll go into each environment in detail.
Part 1 will discuss basic password authentication for Active Directory (AD). Part 2 will discuss basic password authentication for LDAP domains with the posix schema. Part 3 will discuss enabling group restrictions and synchronization, and retrieving preferences for AD. Part 4 will discuss group restrictions and synchronization, and retrieving preferences for LDAP domains with the posix schema.
Basic MediaWiki administration experience is assumed. This series of posts should only be considered current for version 1.2a or 1.2b of the LDAP plugin.
Create a local sysop
Before enabling the plugin, you should create a user in the local wiki database that exists in AD, and promote that user to sysop. After the plugin is enabled, you will not be able to log in as any user who does not exist in AD.
Enabling the plugin
To enable the plugin, first download the current stable version, and place it at $IP/extensions/LdapAuthentication/LdapAuthentication.php. After downloading the plugin, place the following in LocalSettings.php:
require_once( "$IP/extensions/LdapAuthentication/LdapAuthentication.php" ); $wgAuth = new LdapAuthenticationPlugin();
Configuring the plugin
For basic password authentication against an AD domain, you need to configure three things:
- Domain name
- Server names
- How to bind to the AD servers
Setting the domain name
The domain name is used for all of the LDAP configuration settings, and is also the domain name visible to users when logging in. It is recommended to use the short name of your AD domain as the domain name. For example, if your AD domain is TESTAD.EXAMPLE.COM, then you should use TESTAD as your domain name. We will use TESTAD for the examples in this post.
Place the following in LocalSettings.php file to set the domain name:
$wgLDAPDomainNames = array( "TESTAD" );
Setting the server names
The plugin needs to know the fully qualified domain name (FQDN) of each of your AD servers to contact. Currently, the plugin can not do automatic domain discovery. You may add multiple servers, delimited by spaces, for server failover.
Place the following in LocalSettings.php to set the server names:
$wgLDAPServerNames = array( "TESTAD" => "adserver1.testad.example.com adserver2.testad.example.com" );
Telling the plugin how to bind to the AD server
Binding to AD is straightforward; you simply tell the server the domain, username, and password. AD takes the domain and the username in either of the following formats: username@DOMAIN or DOMAINusername. The LDAP plugin supports either of these formats; for this example we’ll use the former.
To specify the format to bind with, place the following into LocalSettings.php:
$wgLDAPSearchStrings = array( "TESTAD" => "USER-NAME@TESTAD" );
Notice that USER-NAME is a special string, and should not be modified. When the user logs in, USER-NAME will be replaced with whatever username is used.
By default the LDAP plugin is set to bind using encryption. Specifically, the plugin defaults to tls using LDAP (port 389). AD doesn’t support tls, so the encryption type needs to be changed. The supported encryption types are clear, tls, and ssl. AD doesn’t allow clear text binds by default, and only supports the ssl encryption type using LDAPS (port 636). If you wish to use clear text binds, you’ll need to change your AD security settings (not recommended).
To change the encryption type, place the following into LocalSettings.php:
$wgLDAPEncryptionType = array( "TESTAD" => "ssl" );
Configuring the server
Configuring the SSL trust
For ssl to work properly, it is important to ensure the LDAP client (the web server) trusts the root Certificate Authority (CA) of the AD server. If your organization is using a third party CA that is in most normal trust lists (like in IE or Firefox), this step can likely be skipped. If your AD servers are using self signed certificates or a local CA, this step is needed.
You can find out which CA issued the AD server’s certificate using openssl. Run the following command:
openssl s_client -connect adserver1.testad.example.com:636 | egrep "subject|issuer"
If the subject and the issuer are the same, the certificate is self signed. If the subject and issuer are not the same, the certificate was signed by a CA. If the CA is local, ask someone in your organization for a copy of the CA certificate. If the certificate is self signed, you can get the certificate by running the previous command without the grep:
openssl s_client -connect adserver1.testad.example.com:636
Copy everything in between, and including:
-----BEGIN CERTIFICATE-----
and:
-----END CERTIFICATE-----
Paste the text into a file, and place the file wherever your OS normally stores its CA certificates; Red Hat Enterprise Linux 5 and newer versions of Fedora place these in /etc/pki/tls/certs.
Now place the following into /etc/openldap/ldap.conf:
TLS_CACERT <pathToCACert> TLS_CACERTFILE <pathToCACert>
Restart your web server for this to take effect.
Test your configuration by logging in with an AD user
Everything should be working at this point. If you have any questions, you should post them on the discussion page for the plugin on mediawiki.org, or leave me a comment (the former is preferred).
Related posts:
- Using the LDAP Authentication Plugin for MediaWiki – The Basics (Part 2)
- Using the LDAP Authentication Plugin for MediaWiki – The Basics (Part 3)
- Semi-anonymous users in MediaWiki using the LDAP Authentication extension
- New OpenSSO authentication plugin for MediaWiki
- OpenSSO web agent conflicts with the MediaWiki parser, and a workaround
77 Comments 
eDRoaCH says: 
Ahriman 
DGseam 
D Sherwood 
helpdesk 
Ranjan 
AH 
Charles 
Charles 
Bill 
Drew 
Thiago 
Sebas 
Corey 
David Miller 
Mike 
Tobias 
Mahesh 
John 
Marcel 
Martin von Herrmann 
Ajay Rungta 
Rolf 
Ian 