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


 * 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"=>"ssl" ); $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"=>"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( "exampleADDomain" ); $wgLDAPServerNames = array( "exampleADDomain"=>"exampleldapserver.example.com exampleldapserver2.example.com" ); $wgLDAPSearchAttributes = array( "exampleADDomain"=>"sAMAccountName" ); $wgLDAPBaseDNs = array( "exampleADDomain"=>"dc=exampledomain,dc=example,dc=com" ); $wgLDAPEncryptionType = array( "exampleADDomain"=>"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.

A quick warning about these examples
Some of these examples may be seriously outdated. Many of them use old configuration options, and will not work with newer versions of the plugin. When in doubt, check against the official documentation.

Authentication Against Microsoft Active Directory
After reading lots of comments on this and my own long way to get this working I thought this information might be useful for others.

I'm only using authentication of Users stored in Active Directory. No User Details, No email reminder, etc.

Working on:
 * MediaWIKI 1.5 runnning on Linux, Apache 2.0 PHP5
 * Windows 2000 Active Directory (should be fine on Windows 2003 too)
 * Domain is: ams.com (NetBIOS Name AMS
 * Domaincontroller is dc1.ams.com
 * with Sasha's tweak for Win2003, used on Windows 2003 Server, PHP 5.1.4, MySQL 5.0.22, MediaWiki 1.7.1, ISS 6.0, and see talk page for things to do first.

In my LocalSettings.php (at the very end): require_once( "includes/LdapAuthentication.php" ); $wgAuth = new LdapAuthenticationPlugin; $wgLDAPDomainNames = array( "AMS" ); $wgLDAPServerNames = array( "AMS"=>"dc1.ams.com" ); $wgLDAPSearchStrings = array( "AMS"=>"USER-NAME@ams.com" ); $wgLDAPUseSSL = false; //not recommended but OK for testing //$wgLDAPEncryptionType = array( "AMS"=>'clear' ); // this is needed in >= 1.1c $wgLDAPUseLocal = false; $wgMinimalPasswordLength = 1; $wgLDAPRetrievePrefs = false; //$wgLDAPRetrievePrefs = array( "AMS"=>false ); // this is needed in >= 1.1c


 * For me, working with Windows server 2003 / active directory domain environment, the right configuration was:
 * $wgLDAPSearchStrings = array( "AMS"=>"AMS\\USER-NAME" );


 * -- Sasha Gimelshtein

Don't know if this is an error but some of the examples above mention $wgLDAPSearchAttributes and others mention $wgLDAPSearchStrings - after spending about 3 days tearing my hair out trying to get this to work against AD I realised I had $wgLDAPSearchAttributes in my config file rather than $wgLDAPSearchStrings, so the correct settings for AD are:

$wgLDAPSearchStrings = array( "DOMAIN"=>"DOMAIN\\USER-NAME" );

Check out this link for further info on securing your wiki

-- Damian Connaughton

What I didn't get first: the $wgLDAPSearchStrings MUST contain the "USER-NAME" string if you want to use it in authentication. This string is replaced later with the name of the user that tries to log in! This site contains lot of information with $wpName instead. At this point wpName is not defined, so the search won'T succeed. If you use: $wgLDAPSearchStrings = array( "AMS"=>"$wpName@ams.com" ); The bind to the LDAP server is made with @ams.com

Looking closer at includes/LdapAuthentication.php shows:

function getSearchString($username) { global $wgLDAPSearchStrings, $wgLDAPBaseDNs; $userdn = $wgLDAPBaseDNs[$_SESSION['wsDomain']]; $this->SearchType = "proxy"; if (!isset($userdn)) { $tmpuserdn = $wgLDAPSearchStrings[$_SESSION['wsDomain']]; $userdn = str_replace("USER-NAME",$username,$tmpuserdn); $this->SearchType = "nonproxy"; }  return $userdn; }

OBS.: The same configuration in LocalSettings.php worked in the following enviroment:


 * Web Server with Windows 2000:
 * Microsoft IIS 5.0
 * PHP 5.1.4
 * MediaWiki 1.6.6
 * Windows 2000 Active Directory

SSL Configuration with MediaWiki 1.9
If you want to get Active Directory working with MediaWiki 1.9 and over SSL there are a few steps you have to take. First of all heres my LocalSettings.php configuration: // Active Directory LDAP Authentication require_once( "includes/LdapAuthentication.php" ); $wgAuth = new LdapAuthenticationPlugin; $wgLDAPDomainNames = array( "NETBIOS_DOMAIN" ); $wgLDAPServerNames = array( "NETBIOS_DOMAIN"=>"DNS_NAME_DC_SERVER" ); $wgLDAPEncryptionType = array( "NETBIOS_DOMAIN"=>"ssl" ); /** $wgLDAPUseSSL = true;   //Commented out because these options use syntax $wgLDAPUseLocal = false;    //for 1.0 and below (and are hence incorrect) $wgLDAPAddLDAPUsers = false; $wgLDAPUpdateLDAP = false; $wgLDAPMailPassword = false; $wgLDAPRetrievePrefs = true; */ $wgLDAPRetrievePrefs = array( "NETBIOS_DOMAIN"=>true ); //<- this is how to do it $wgMinimalPasswordLength = 1; $wgLDAPSearchStrings = array( "NETBIOS_DOMAIN"=>"NETBIOS_DOMAIN\\USER-NAME" ); //$wgLDAPDebug = 3; //for debugging //$wgShowExceptionDetails = true; //for debugging MediaWiki Second of all as said before under Windows you have do some steps to you PHP Config as well to get SSL working:
 * Windows Server 2003 with
 * Apache 2.0.59
 * PHP 5.2.0
 * MySQL 5.0.27
 * MediaWiki 1.9.0
 * LDAPAuthentication.php 1.1c
 * Windows 2003 Active Directory
 * Copy the following file from your PHP directory to your Windows System directory (C:\%windir%\system32)
 * libeay32.dll
 * ssleay32.dll
 * In your PHP.ini uncomment the following lines
 * extension=php_ldap.dll
 * extension=php_openssl.dll
 * You MUST create a directory  and create a file named  . In this File add   in the first line and save. Restart the Apache Web-Server

Now it is still not working with MediaWiki 1.9. For this to get it to work you have to make the following changes in the LDAPAuthentication.php: --JenZ 12:20, 24 January 2007 (UTC)
 * change  to
 * change  to   in the else if path in the   function. This should get it to work over SSL. You do not have to install any Certificates.

Running mediawiki 1.9 on Solaris with Ldap auth to Sun's Directory Server for Validation only. Came across exactly the same problems as Jen and other folks. The 2 fixes above got it all working ..... - way to go Jen :)
 * change  to
 * change  to   in the else if path in the   function. This should get it to work over SSL. You do not have to install any Certificates.

--Robertholt 17:05, 29 January 2007 (UTC)

Authentication Against Lotus Domino Directory
We used the following settings below to authenticate against a Domino Directry Server 6.5.1 configured with RC5 schema.

Working on:
 * MediaWIKI 1.5 runnning on Red Hat AS 3.0, Apache 2.0 PHP5
 * LdapAuthentication.php 1.0
 * Domino Directory Server 6.5.1 on Windows 2003
 * Domain is: something.com

The main change was getting the proxy agent user correct, the format was

$wgLDAPProxyAgent = "cn=/o="

We added this section to the bottom of the LocalSettings.php file.

require_once( 'LdapAuthentication.php' ); $wgAuth = new LdapAuthenticationPlugin; $wgLDAPDomainNames = array( "testLDAPdomain" ); $wgLDAPServerNames = array( "testLDAPdomain"=>"devldap.something.com" ); $wgLDAPSearchStrings = array( "testLDAPdomain"=>"uid=wikildap,dc=something,dc=com" ); $wgLDAPUseSSL = false; //Recommended!! $wgLDAPUseLocal = false; //Allow the use of the local database as well as the LDAP database $wgMinimalPasswordLength = 1; #If using mediawiki 1.5. Note: 1 is the minimum, feel free to go higher $wgLDAPAddLDAPUsers = true; //if true WikiDN and WikiPassword must be set $wgLDAPUpdateLDAP = true; //if true WikiDN and WikiPassword must be set //User and password used for proxyagent access $wgLDAPProxyAgent = "cn=Wiki Ldap/o=somthing"; $wgLDAPProxyAgentPassword = "password"; //You are able to use clear text passwords, but please try not to $wgLDAPSearchAttributes = array( "testLDAPdomain"=>"uid" ); $wgLDAPBaseDNs = array( "testLDAPdomain"=>"" );

Authentication against Tivoli or other IBM LDAP server
Not sure if this is with Tivoli or not, but when all else failed this worked. Note that there is a new setting called $wgLDAPSearchAttributes

require_once( 'LdapAuthentication.php' ); $wgAuth = new LdapAuthenticationPlugin; $wgLDAPDomainNames = array( "IBM Intranet" ); $wgLDAPServerNames = array( "IBM Intranet"=>"bluepages.ibm.com" ); $wgLDAPSearchAttributes = array( "IBM Intranet"=>"mail" ); // USER-NAME must map to "mail" $wgLDAPBaseDNs = array("IBM Intranet"=>"ou=bluepages, o=ibm.com"); $wgLDAPUseSSL = true; $wgLDAPUseLocal = true; $wgLDAPAddLDAPUsers = true; $wgLDAPUpdateLDAP = false; $wgLDAPMailPassword = false; $wgLDAPRetrievePrefs = false; $wgMinimalPasswordLength = 8;
 * 1) $wgLDAPSearchStrings = array( "IBM Intranet"=>"ou=bluepages, o=ibm.com -s sub mail=USER-NAME" );

However, after this I ran into another issue with SpecialUserLogin.php "Fatal error: Call to a member function on a non-object in /home/john.varghese@us.ibm.com/public_html/wiki/includes/SpecialUserlogin.php on line 314" Apparently $u which is a User object suddenly becomes invalid. This error occurs only if the password is correct.


 * The above issue was solved, look in the LDAP Authentication's discussion page for more info. -- Ryan Lane

Authentication against Novell eDirectory
Didn't have much luck with the preceding examples, but managed to get things working with the following setup on Ubuntu 6.06.1:


 * MediaWiki: 1.8.2
 * PHP: 5.1.2 (apache2handler)
 * MySQL: 5.0.22-Debian_0ubuntu6.06-log
 * LDAP Authentication Plugin (version 1.1e)

require_once( 'LdapAuthentication.php' ); $wgAuth = new LdapAuthenticationPlugin; $wgLDAPDomainNames = array( "somefriendlynamehere" ); $wgLDAPServerNames = array( "somefriendlynamehere"=>"IP or DNS of LDAP server here" ); $wgLDAPSearchStrings = array( "somefriendlynamehere"=>"cn=USER-NAME,ou=someorgunit,o=novell" ); $wgLDAPEncryptionType = array( "somefriendlynamehere"=>"clear" ); $wgMinimalPasswordLength = 1; $wgLDAPDebug = 3; $wgLDAPUseLocal = false;

Note that debugging is turned on for convenience (just delete the line if it's working) and this is set to not use the local user database (if it exists). Also, there is no encryption on here. If you'd like more help there's a rather good eDirectory-orientated resource on Novell's site:


 * Using eDirectory to control access to MediaWiki

--Roobarb!

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)