Extension:LDAP Authentication/FAQ

From MediaWiki.org
Jump to: navigation, search

About - Requirements - Examples - Configuration Options - Changelog - Roadmap - Suggestions - User provided info - FAQ - Support

MediaWiki extensions manual - list
Crystal Clear action run.png
LDAP Authentication

Release status: stable

Implementation User identity
Description Provides LDAP authentication, and some authorization functionality for MediaWiki
Author(s) Ryan Lane (Ryan lanetalk)
Latest version 2.0d (2012-11-21)
MediaWiki 1.19+
Database changes yes
License GPL
Download
Hooks used
LoadExtensionSchemaUpdates

Translate the LDAP Authentication/FAQ extension if possible

Check usage and version matrix; code metrics

Where do I download the extension?[edit | edit source]

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

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

Solaris LDAP Client[edit | edit source]

Problem[edit | edit source]

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.

Example[edit | edit source]

Works on OpenLDAP, bombs on Solaris CLient

<?php

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

<?php

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

Remedy[edit | edit source]

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 | edit source]

Official workaround[edit | edit source]

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

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( '' );

to:


       $user->mPassword = '' ;

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 | edit source]

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->addToDatabase();
-               $u->setPassword( $this->mPassword );
+
+               if ( $wgAuth->allowPasswordChange() ) {
+                       $u->setPassword( $this->mPassword );
+               }
+
                $u->setEmail( $this->mEmail );
                $u->setRealName( $this->mRealName );
                $u->setToken();
 
-               global $wgAuth;
                $wgAuth->initUser( $u );
 
                $u->setOption( 'rememberpassword', $this->mRemember ? 1 : 0 );

How do I install the extension?[edit | edit source]

See the install section of the about page.

How do I configure the extension?[edit | edit source]

See the configuration pages.

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

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:
     ;extension=php_ldap.dll

    to:

    extension=php_ldap.dll
  3. Restart your web server

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

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

C:\openldap\sysconf\ldap.conf

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

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

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 | edit source]

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".--80.179.206.193 16:47, 23 April 2009 (UTC)
you can edit LdapAuthentication.php page line 1014 like this
$userdn = str_replace( "USER-NAME", '_'.$username, $tmpuserdn );

AutoAuth[edit | edit source]

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 | edit source]

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 | edit source]

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 | edit source]

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 | edit source]

See Extension:ConfirmAccount/Integration with LDAP Authentication extension

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

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 | edit source]

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.