Extension:LDAP Authentication/FAQ

From mediawiki.org
MediaWiki extensions manual
OOjs UI icon advanced-invert.svg
LDAP Authentication
Release status: unmaintained
Implementation User identity
Description Provides LDAP authentication, and some authorization functionality for MediaWiki
Author(s) Ryan Lane (Ryan lanetalk)
Latest version 2.1.0 (2018-10-11)
Compatibility policy Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki 1.19-1.26
Database changes Yes
License GNU General Public License 2.0 or later
  • $wgAutoAuthUsername
  • $wgGroupsUseMemberOf
  • $wgDomainNames
  • $wgEncryptionType
  • $wgSearchAttributes
  • $wgGroupUseFullDN
  • $wgPort
  • $wgWriterPassword
  • $wgUserBaseDNs
  • $wgGroupBaseDNs
  • $wgUseLDAPGroups
  • $wgAutoAuthDomain
  • $wgWriteLocation
  • $wgProxyAgentPassword
  • $wgUseLocal
  • $wgLockPasswordPolicy
  • $wgLockOnBlock
  • $wgLocallyManagedGroups
  • $wgAddLDAPUsers
  • $wgProxyAgent
  • $wgServerNames
  • $wgPasswordHash
  • $wgAuthAttribute
  • $wgGroupSearchNestedGroups
  • $wgExcludedGroups
  • $wgGroupNameAttribute
  • $wgRequiredGroups
  • $wgBaseDNs
  • $wgGroupAttribute
  • $wgOptions
  • $wgGroupsPrevail
  • $wgDisableAutoCreate
  • $wgGroupObjectclass
  • $wgLowerCaseUsername
  • $wgUpdateLDAP
  • $wgDebug
  • $wgMailPassword
  • $wgSearchStrings
  • $wgPreferences
  • $wgActiveDirectory
  • $wgGroupUseRetrievedUsername
  • $wgGroupSearchPosixPrimaryGroup
  • $wgWriterDN

Check usage and version matrix.

Issues Open tasks · Report a bug
Warning Warning: The extension has not been fully updated for MediaWiki 1.27+ (AuthManager); LdapAutoAuthentication will not work with that version. See gerrit:286705 for details.

Where do I download the extension?[edit]

See the download section of the infobox on any of the pages of this documentation.

Is the extension compatible with...?[edit]

Solaris LDAP Client[edit]


If your server happens to use Solaris LDAP client instead of OpenLDAP (determiend through phpinfo()) then you will be unable to connect to LDAP servers. The cause is the expected Host name passed to ldap_connect(). The example below illustrates the issue.


Works on OpenLDAP, bombs on Solaris CLient


// LDAP variables
$ldaphost = "ldap://ldap.server.com";  // your ldap servers
$ldapport = 389;                 // your ldap server's port number

// Connecting to LDAP
$ldapconn = ldap_connect($ldaphost, $ldapport)
          or die("Could not connect to $ldaphost");

 echo $ldapconn;

The cause is the ldap:// portion

Works with Solaris Client


// LDAP variables
$ldaphost = "ldap.server.com";  // your ldap servers
$ldapport = 389;                 // your ldap server's port number

// Connecting to LDAP
$ldapconn = ldap_connect($ldaphost, $ldapport)
          or die("Could not connect to $ldaphost");

		  echo $ldapconn;

The code within LDAPAuthenticationPlugin.php adds ldap://, ldapi://, or ldaps:// for server names. This will cause it to fail.


Remove the $serverpre value for the block below;

$servers = "";
		$tmpservers = $wgLDAPServerNames[$_SESSION['wsDomain']];
		$tok = strtok( $tmpservers, " " );
		while ( $tok ) {
			$servers = $servers . " " . $serverpre . $tok;
			$tok = strtok( " " );
		$servers = rtrim($servers);

MediaWiki 1.9[edit]

Official workaround[edit]

LdapAuthentication.php up to 1.1c (>=1.1d can skip this)[edit]

I've added a bug into MediaWiki's bugzilla to get part of this fixed. One part of the workaround is in my code (which will be fixed and released soon), and the other is in MediaWiki's code. So, to make it work, please change the following in LdapAuthentication.php in the initUser() function (if using 1.1c or below):

       $user->setPassword( '' );


       $user->mPassword = '' ;


I lost ability to login with LDAP-only users with a NULL password, I would like this to be changed to a nonworking dummy value, which worked for me - read more...

and add the following function to LdapAuthentication.php:

         * Can the wiki change passwords in LDAP?
         * Return true if yes.
         * @return bool
         * @access public
        function allowPasswordChange() {
                global $wgLDAPUpdateLDAP, $wgLDAPMailPassword;

                if ( isset($wgLDAPUpdateLDAP[$_SESSION['wsDomain']]) ) {
                        $updateLDAP = $wgLDAPUpdateLDAP[$_SESSION['wsDomain']];
                if ( isset($wgLDAPMailPassword[$_SESSION['wsDomain']]) ) {
                        $mailPassword = $wgLDAPMailPassword[$_SESSION['wsDomain']];
                if ( $updateLDAP || $mailPassword ) {
                        return true;
                } else {
                        return false;
SpecialUserlogin.php (all Versions MediaWiki 1.9.x)[edit]

And in includes/SpecialUserlogin.php you can use the following patch (you probably want to patch by hand since this patch is against SVN):

--- SpecialUserlogin.php        (revision 19677)
+++ SpecialUserlogin.php        (working copy)
@@ -307,13 +307,18 @@
         * @private
        function initUser( $u ) {
+               global $wgAuth;
-               $u->setPassword( $this->mPassword );
+               if ( $wgAuth->allowPasswordChange() ) {
+                       $u->setPassword( $this->mPassword );
+               }
                $u->setEmail( $this->mEmail );
                $u->setRealName( $this->mRealName );
-               global $wgAuth;
                $wgAuth->initUser( $u );
                $u->setOption( 'rememberpassword', $this->mRemember ? 1 : 0 );

How do I install the extension?[edit]

See the install section of the about page.

How do I configure the extension?[edit]

See the configuration pages.

How do I configure PHP with LDAP on Windows?[edit]

You need to:

  1. Add the PHP directory to the PATH system variable
    • Ensure libeay32.dll and ssleay32.dll are in this path
  2. Edit the php.ini (in your apache/bin directory NOT your php directory!!!) file, and change:


  3. Restart your web server

How do I fix certificate trust issues with LDAPS or LDAP with StartTLS on Windows?[edit]

If you are having trust issues with LDAPS or LDAP with StartTLS, you'll need to modify your ldap.conf file. This file seems to be hardcoded in PHP on Windows. Put your openldap options into the following file (create the directories and file):


See: Extension:LDAP Authentication/Requirements#Certificate trusts 3

My LDAP server requires SSL/TLS client authentication, where do I configure this?[edit]

PHP has no method to set a client certificate and key, and as such, this isn't configurable in the LDAP extension. You can, however, define this at the Apache level. Set the HOME and LDAPRC variables to point to a custom .ldaprc file (see 'man 5 ldap.conf') in /etc/apache2/envvars (on Debian/Ubuntu), or via SetEnv directives (Red Hat). In this file you should point to your client certificate and key.

Authentication fails for usernames with underscores; how do I fix this?[edit]

This is currently unsupported in the extension. MediaWiki replaces underscores with spaces in usernames, and the extension therefore, gets the username with the underscores replaced.

Here is a user submitted hack for getting this to work:

I added a line at the beginning of the function "getSearchString":

$username = str_replace(' ','_',$username);

This replaces the space with an underscore when it creates the user username that is sent to the LDAP server. As far as MediaWiki is concerned it will still use the space in the name.
--JoeD July 7th 2007

One more change, if one is restricting access to a specific group in LDAP, the group lookups fail with the underscore again being removed from the username.

For the latest (2010-11-23) LdapAuthentication.php, a modified "authenticate" function will fix the group lookups. Look for this in "authenticate":

      $this->printDebug( "Entering authenticate", NONSENSITIVE );

And add the following directly after:

      $username = str_replace(' ','_',$username);

For older (2009-02) LdapAuthentication.php, look for this in the "getGroups" function:

      if ( $value != "*" )
                        $value = $this->getLdapEscapedString( $value );

And add the following directly after:

      $value = str_replace(' ','_',$value);
You might also have to do the same str_replace in the function "authenticate".-- 16:47, 23 April 2009 (UTC)
you can edit LdapAuthentication.php page line 1014 like this
$userdn = str_replace( "USER-NAME", '_'.$username, $tmpuserdn );


When using auto authentication you might also have to add the following code in LdapAutoAuthentication.php within the function Authenticate around line 59:

         $wgAuth->printDebug( "User exists in LDAP; finding the user by name ($mungedUsername) in MediaWiki.", NONSENSITIVE );
/*Add*/  $mungedUsername = str_replace( "_", " ", $mungedUsername ); /*this line*/
         $localId = User::idFromName( $mungedUsername );
         $wgAuth->printDebug( "Got id ($localId).", NONSENSITIVE );

Can I use one attribute to authenticate users, but use another as the username?[edit]

You can do this using the 'SetUsernameAttributeFromLDAP' hook. For instance, in the following configuration, authentication is done with the "cn" attribute, but the username is being set with the "uid" attribute:

require_once( "$IP/extensions/LdapAuthentication.php" );
$wgAuth = new LdapAuthenticationPlugin();

$wgLDAPDomainNames = array( "testLDAPdomain" );
$wgLDAPServerNames = array( "testLDAPdomain"=>"testLDAPserver.LDAP.example.com testLDAPserver2.LDAP.example.com" );
$wgLDAPProxyAgent = array( "testLDAPdomain"=>"cn=proxyagent,ou=profile,dc=LDAP,dc=example,dc=com" );
$wgLDAPProxyAgentPassword = array( "testLDAPdomain"=>"S0M3L0ngP@$$w0r6ofS0meV@rie222y!" );
$wgLDAPSearchAttributes = array( "testLDAPdomain"=>"cn" );
$wgLDAPBaseDNs = array( "testLDAPdomain"=>"dc=LDAP,dc=example,dc=com" );

$wgHooks['SetUsernameAttributeFromLDAP'][] = 'SetUsernameAttribute';
//This function allows you to get the username from LDAP however you need to do it.
//This is the username MediaWiki will use.
function SetUsernameAttribute(&$LDAPUsername, $info) {
        $LDAPUsername = $info[0]['uid'][0];
        return true;

I installed the extension, but now I don't have a Sysop user; how do I give myself Sysop rights?[edit]

There are a few ways of doing this; however, the easiest method is:

  1. Log in with your regular account (to ensure your account is created)
  2. Disable the extension
  3. Log in as WikiSysop
  4. Go to Special:Userrights and add the sysop group to your regular account
  5. Re-enable the extension

How do I remove the domain list from Special:Userlogin?[edit]

You can hide this with CSS; edit MediaWiki:Common.css, and add the following:

#mw-user-domain-section {
    display: none !important;

How do I integrate LDAP authentication with Confirm Account creation extension ?[edit]

See Extension:ConfirmAccount/Integration with LDAP Authentication extension

Authentication is working for some users, but not others[edit]

There are a number of things you should check:

  1. Is the user's password shorter than the configurable minimum ($wgMinimalPasswordLength)? MediaWiki forbids this.
  2. Is the user's password the same as their user name? MediaWiki forbids this.
  3. If you are doing group restrictions, is that user a member of that group?
    1. Is the user a member of that group due to group nesting? If so, do you have nested group searching enabled?
    2. Is that group the user's primary group? If so, the extension most likely won't find it.
  4. Does the username contain an underscore? MediaWiki converts underscores in usernames to spaces. This is currently an open bug in the LDAP extension.

The extension won't write a debug log[edit]

The most frequent reason this fails is because the web server isn't allowed to write to the location defined in the configuration. Another often hit situation is when writing to a temporary folder when SELinux is enabled. Ensure that you are writing to a location allowed by your SELinux policy, or change the label of the directory being used.

Finally, do not modify 'ldap' in $wgDebugLogGroups['ldap']; regardless of how you name your domain. Example, assume you have configured your extension using:

$wgLDAPDomainNames = array('MyDomain');

You may be tempted to call out:

$wgDebugLogGroups['MyDomain'] = '/tmp/debug.log';

However, this is incorrect. The line should remain:

$wgDebugLogGroups['ldap'] = '/tmp/debug.log';

Another reason why you may not be able to find the log file you configured is SystemD. With the introduction of service-private /tmp, instead of /tmp/debug.log your file will be under something like /tmp/systemd-private-*/tmp/debug.log.

Another reason is that the $wgLDAPDebug line is set before require_once() line. Set it after that.

"It looks like you are missing LDAP support; please ensure ..." but I have installed php5-ldap package[edit]

Restart the web server (apache / nginx). Otherwise it won't notice the installed package.