Extension:LDAP Authentication/Generic LDAP Configuration Examples

This documentation has been updated to reflect version 1.1
The documentation has been updated to reflect version 1.1. The user provided examples may have been written for older version of the plugin.

Introduction
As many people are having problems getting this patch working for their specific environment, and as every situation is different, I believe a few example configurations are needed to ease configuration for your specific case.

This patch is very powerful, and as such, it is complicated to implement. However, if you are using one of the more normal cases (90%+ people are), these examples should help you, and in many cases will be the exact thing you need to get the patch working for you.

These examples will only deal with Mediawiki 1.5 and above. All that is needed is for you do drop "LdapAuthentication.php" into the includes directory, and to modify "LocalSettings.php". The examples below will show how you need to modify "LocalSettings.php".

General Setup
Remember, if your web server does not use SSL (URL starts with https:// ), your password will be transmitted in clear text from the client browser to the web server. This is independent of the SSL settings described below from the web server to the LDAP server.

Also, be sure to enable LDAP authentication within PHP. Make sure that you have installed the necessary packages for your distro. Currently, Mediawiki does not complain about missing LDAP support for PHP - it will just give you a blank screen after trying to log in.


 * RedHat EL based distro (CentOS 4.3):

yum install php-ldap

Make sure, that  contains


 * Ubuntu 6.06.1 (Dapper Drake) and others:

sudo apt-get install php-ldap

or possibly..

sudo apt-get install php5-ldap


 * Other distros:

Modify php.ini, and uncomment the line:

;extension=php_ldap.dll

change to:

extension=php_ldap.dll

Single Domain Requiring Straight Binding Only
In this example, we have an Active Directory (AD) or non AD based LDAP server, and we will be doing straight binds to the directory. This is not how typical LDAP authentication plugins operate as it does not attempt a search first, see "Single Domain Requiring Search Before Binding."

Configuration for an AD server
Our LDAP servers are "exampleldapserver.example.com" and "exampleldapserver2.example.com", and the domainname is "EXAMPLEDOMAIN". "USER-NAME" is not to be changed as this string is replaced in LdapAuthentication.php. In this example, we do not require the ability to change passwords, or create new LDAP users through Mediawiki, just authentication.

(In LocalSettings.php) require_once 'LdapAuthentication.php';

$wgAuth = new LdapAuthenticationPlugin;

$wgLDAPDomainNames = array( 'exampleADDomain', );

$wgLDAPServerNames = array( 'exampleADDomain' => 'exampleldapserver.example.com exampleldapserver2.example.com', );

$wgLDAPSearchStrings = array( 'exampleADDomain' => 'EXAMPLEDOMAIN\\USER-NAME', );

$wgLDAPEncryptionType = array( 'exampleADDomain' => 'clear', );

$wgLDAPUseLocal = false; $wgMinimalPasswordLength = 1;

Notice that SSL is enabled. AD by default requires SSL if you are binding over LDAP. If you do not require SSL (if you set AD to not require signed communications), you can set that option to "false". Be aware that doing so will cause your domain user's passwords to be sent over the line in the clear.

For SSL to work, you must install an SSL certificate on your AD server, your wiki's server must trust the AD server's CA, and the DNS name of your AD must resolve to the cn on the certificate issued.

Extra configuration for AD to allow for preference pulling, group sync, etc.
If you want to be able to pull preferences, and such, you'll need to set a couple other options. These other options will allow the plugin to bind as the user, and then search for the user's DN. Without a DN, any extras provided by the plugin will fail.

(In LocalSettings.php after your other LDAP configuration) $wgLDAPBaseDNs = array( 'exampleADDomain' => 'cn=Users,dc=example,dc=com' );

$wgLDAPSearchAttributes = array( 'exampleADDomain' => =sAMAccountName' );

Configuration for a Non-AD Server
Our LDAP servers are "exampleldapserver.example.com" and "exampleldapserver2.example.com" ,and the domain is "exampledomain.example.com". In this example, we do not require the ability to change passwords, or create new LDAP users through Mediawiki, we just require authentication.

Our naming attribute for users is "uid", and all users are kept in "ou=people,dc=exampledomain,dc=example,dc=com".

(In LocalSettings.php) require_once 'LdapAuthentication.php';

$wgAuth = new LdapAuthenticationPlugin;

$wgLDAPDomainNames = array( 'exampleNonADDomain', );

$wgLDAPServerNames = array( 'exampleNonADDomain' => 'exampleldapserver.example.com exampleldapserver2.example.com', );

$wgLDAPSearchStrings = array( 'exampleNonADDomain' => 'uid=USER-NAME,ou=people,dc=exampledomain,dc=example,dc=com', );

$wgLDAPEncryptionType = array( 'exampleNonADDomain' => 'ssl', );

$wgMinimalPasswordLength = 1;

Notice that SSL is enabled. If you do not require SSL, you can set that option to "false". Be aware that doing so will cause your domain user's passwords to be sent over the line in the clear.

For SSL to work, you must install an SSL certificate on your LDAP server, your wiki's server must trust the AD server's CA, and the DNS name of your LDAP server must resolve to the cn on the certificate issued.

Single Domain Requiring Search Before Binding
This is typically how LDAP authentication is performed. First, a search is performed for the identifier presented (username) and a DN is returned. This DN is then used with the password provided to attempt a bind against the LDAP server. This is useful in cases when the username does not match anything in the DN or users are stored in multiple OUs.

Configuration for an AD Server
In this situation, you could use the "Single Domain Requiring Straight Binding Only" as AD will search through multiple OUs for you anyway.

Our LDAP servers are "exampleldapserver.example.com" and "exampleldapserver2.example.com", and the domain is "exampledomain.example.com". In this example, we do not require the ability to change passwords, or create new LDAP users through Mediawiki, we just require authentication.

Our naming attribute for users is "sAMAccountName", some users are kept in "ou=accounting,ou=people,dc=exampledomain,dc=example,dc=com", and other users are kept in "ou=graphics,ou=people,dc=exampledomain,dc=example,dc=com".

(In LocalSettings.php) require_once 'LdapAuthentication.php';

$wgAuth = new LdapAuthenticationPlugin;

$wgLDAPDomainNames = array( 'exampleNonADDomain', );

$wgLDAPServerNames = array( 'exampleNonADDomain' => 'exampleldapserver.example.com exampleldapserver2.example.com', );

$wgLDAPSearchStrings = array( 'exampleNonADDomain' => 'uid=USER-NAME,ou=people,dc=exampledomain,dc=example,dc=com', );

$wgLDAPEncryptionType = array( 'exampleNonADDomain' => 'ssl', );

$wgMinimalPasswordLength = 1;

AD by default will not allow anonymous searches, so you are required to have a user search for you, see "Using a ProxyAgent."

Notice that SSL is enabled. AD by default requires SSL if you are binding over LDAP. If you do not require SSL (if you set AD to not require signed communications), you can set that option to "false". Be aware that doing so will cause your domain user's passwords to be sent over the line in the clear.

For SSL to work, you must install an SSL certificate on your AD server, your wiki's server must trust the AD server's CA, and the DNS name of your AD must resolve to the cn on the certificate issued.

Configuration for a Non-AD Server
Our LDAP servers are "exampleldapserver.example.com" and "exampleldapserver2.example.com" ,and the domain is "exampledomain.example.com". In this example, we do not require the ability to change passwords, or create new LDAP users through Mediawiki, we just require authentication.

Our naming attribute for users is "uid", some users are kept in "ou=accounting,ou=people,dc=exampledomain,dc=example,dc=com", and other users are kept in "ou=graphics,ou=people,dc=exampledomain,dc=example,dc=com".

(In LocalSettings.php) require_once 'LdapAuthentication.php';

$wgAuth = new LdapAuthenticationPlugin;

$wgLDAPDomainNames = array( 'exampleNonADDomain', );

$wgLDAPServerNames = array( 'exampleNonADDomain' => 'exampleldapserver.example.com exampleldapserver2.example.com' , );

$wgLDAPSearchAttributes = array( 'exampleNonADDomain' => 'uid', );

$wgLDAPBaseDNs = array( 'exampleNonADDomain' => 'dc=exampledomain,dc=example,dc=com', );

$wgLDAPEncryptionType = array( 'exampleNonADDomain' => 'ssl', );

$wgMinimalPasswordLength = 1;

Notice that SSL is enabled. If you do not require SSL, you can set that option to "false". Be aware that doing so will cause your domain user's passwords to be sent over the line in the clear.

For SSL to work, you must install an SSL certificate on your LDAP server, your wiki's server must trust the LDAP server's CA, and the DNS name of your LDAP server must resolve to the cn on the certificate issued.

Using a ProxyAgent
The proxyagent entry is at "cn=proxyagent,ou=Users,dc=exampledomain,dc=example,dc=com". Add the following options to your configuration:

(In LocalSettings.php) $wgLDAPProxyAgent = array(  'exampleNonADDomain' => 'cn=proxyagent,ou=Users,dc=exampledomain,dc=example,dc=com', );

$wgLDAPProxyAgentPassword = array( 'exampleNonADDomain' => 'eX@mP1eP$$wRd', );

Configuration for an AD domain and a non-AD domain
If you are using multiple domains, this is your most likely scenario. In this example, we have two different domains that are not part of a single-sign-on enviroment.

The AD domain is called "ADDOMAIN", and has servers named "exampleldapserver.example.com" and "exampleldapserver2.example.com". The non-AD domain is called "NonADDomain", has servers named "nonadserver.example.com", "nonadserver2.example.com", and "nonadserver3.example.com", and users are stored in "ou=people,dc=example,dc=com". In this example, we do not require the ability to change passwords, or create new LDAP users through Mediawiki, just authentication.

(In LocalSettings.php) require_once 'LdapAuthentication.php';

$wgAuth = new LdapAuthenticationPlugin;

$wgLDAPDomainNames = array( 'exampleADDomain', 'exampleNonADDomain', );

$wgLDAPServerNames = array( 'exampleADDomain' => 'exampleldapserver.example.com exampleldapserver2.example.com',  'exampleNonADDomain' => 'nonadserver.example.com nonadserver2.example.com nonadserver3.example.com', );

$wgLDAPSearchStrings = array( 'exampleADDomain' => 'ADDOMAIN\\USER-NAME', 'exampleNonADDomain' => 'uid=USER-NAME,ou=people,dc=example,dc=com', );

$wgLDAPEncryptionType = array( 'exampleADDomain' => 'ssl', 'exampleNonADDomain' => 'ssl', );

$wgMinimalPasswordLength = 1;

Notice that SSL is enabled. AD by default requires SSL if you are binding over LDAP. If you do not require SSL (if you set AD to not require signed communications), you can set that option to "false". Be aware that doing so will cause your domain user's passwords to be sent over the line in the clear.

For SSL to work, you must install an SSL certificate on your AD server, your wiki's server must trust the AD server's CA, and the DNS name of your AD must resolve to the cn on the certificate issued.

For the time being, many options are available for all domains only. For instance, in this example, both of your domains are required to use ssl, neither can add users or update ldap, neither can mail passwords, neither can retreive preferences, and both require passwords with atleast 1 character.

Authentication Failover/Fallover
To enable the LDAP Authentication to Failover (or Fallover) to the local database simply add the following line: $wgLDAPUseLocal = true;


 * There are some security considerations with using the local database. Using the local database was mostly meant for transitionary purposes. Your domain passwords will probably be synced to the local database, and anyone will be able to create users with the same name as domain users. If you are going to do this, make *SURE* that this server is well protected, and kept up to date with security patches from both the vendor, and mediawiki, as it will be keeping domain username/password combos in a hash that is probably less secured than what is on your domain controller. I personally don't recommend doing this. -- Ryan Lane

It should be noted that this is also a good solution if you do use a bot as the bot can use the local password of the wiki and does not have to be in the LDAP directory.--GunterS 17:44, 27 March 2007 (UTC)


 * That is true. Maybe I should add an option to be able to limit local logins to specific users --Ryan lane 17:59, 27 March 2007 (UTC)