Using the LDAP Authentication Plugin for MediaWiki – The Basics (Part 1)

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.
[toc title=”Table of Contents”]

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:

  1. Domain name
  2. Server names
  3. 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" => "" );

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 | 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

Copy everything in between, and including:




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>

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, or leave me a comment (the former is preferred).

  • John

    How can I set Wiki/ADauth not to worry about self-signed certificates?

  • Brandon Leon

    Hello and thank you for a great plugin,
    I’m having trouble with setting this up and after seeing various example configurations I realize there’s more than what’s talking about in this article that can be configured, do you have documentation on all the settings?

    After following the instructions on this page, I am just unable to log into my wiki at all, getting the message “Incorrect password entered. Please try again.”, I have verified my password, so I’m sure I’m just not getting communication to AD.

    • Hey, I’m not really maintaining this extension anymore. The official docs have a section that show all config options, with good docs around how they work.

      • BTW, the extension should still be maintained, just not by me. The Wikimedia Foundation took over the maintenance a while back.