Extension:LDAP Authentication/Configuration Options

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

MediaWiki extensions manual

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
Download	Download extension Git [?]: Download Git master browse repository (GitHub) commit history repository contributors (GitHub) code review
Parameters $wgLDAPAutoAuthUsername $wgLDAPGroupsUseMemberOf $wgLDAPDomainNames $wgLDAPEncryptionType $wgLDAPSearchAttributes $wgLDAPGroupUseFullDN $wgLDAPPort $wgLDAPWriterPassword $wgLDAPUserBaseDNs $wgLDAPGroupBaseDNs $wgLDAPUseLDAPGroups $wgLDAPAutoAuthDomain $wgLDAPWriteLocation $wgLDAPProxyAgentPassword $wgLDAPUseLocal $wgLDAPLockPasswordPolicy $wgLDAPLockOnBlock $wgLDAPLocallyManagedGroups $wgLDAPAddLDAPUsers $wgLDAPProxyAgent $wgLDAPServerNames $wgLDAPPasswordHash $wgLDAPAuthAttribute $wgLDAPGroupSearchNestedGroups $wgLDAPExcludedGroups $wgLDAPGroupNameAttribute $wgLDAPRequiredGroups $wgLDAPBaseDNs $wgLDAPGroupAttribute $wgLDAPOptions $wgLDAPGroupsPrevail $wgLDAPDisableAutoCreate $wgLDAPGroupObjectclass $wgLDAPLowerCaseUsername $wgLDAPUpdateLDAP $wgLDAPDebug $wgLDAPMailPassword $wgLDAPSearchStrings $wgLDAPPreferences $wgLDAPActiveDirectory $wgLDAPGroupUseRetrievedUsername $wgLDAPGroupSearchPosixPrimaryGroup $wgLDAPWriterDN
Hooks used BlockIpComplete LoadExtensionSchemaUpdates UnblockUserComplete
Hooks provided ChainAuth LDAPSetCreationValues LDAPRetrySetCreationValues LDAPUpdateUser SetUsernameAttributeFromLDAP
Check usage and version matrix.
Issues	Open tasks · Report a bug

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.

The following are options that are usable in "LocalSettings.php":

(These are examples of the extension options, this is not a working example however)

Options will not work if put at the beginning of LocalSettings.php. Please place them at the end of LocalSettings.php

Enabling the plugin

First, download the snapshot; specifically, always download the trunk version. Follow the directions from the Extension Distributor for where to extract the snapshot.

After extracting the snapshot, run the update script

The LdapAuthentication extension must add tables to MediaWiki's database. You must run update.php (only after you've enabled the extension in LocalSettings.php or it will be ignored):

# Run this from the top level of your MediaWiki installation directory
php maintenance/update.php

When using password authentication

Edit $IP/LocalSettings.php

For MediaWiki < 1.27:

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

For MediaWiki >= 1.27:

require_once( "$IP/extensions/LdapAuthentication/LdapAuthentication.php" );
$wgAuthManagerAutoConfig['primaryauth'] += [
    LdapPrimaryAuthenticationProvider::class => [
        'class' => LdapPrimaryAuthenticationProvider::class,
        'args' => [[
               'authoritative' => true, // don't allow local non-LDAP accounts
           ]],
        'sort' => 50, // must be smaller than local pw provider
    ],
];

When using auto-authentication

Edit $IP/LocalSettings.php

require_once( "$IP/extensions/LdapAuthentication/LdapAuthentication.php" );
require_once( "$IP/extensions/LdapAuthentication/LdapAutoAuthentication.php" );
// options go here
AutoAuthSetup();

You'll need to set up $wgLDAPProxyAgent and $wgLDAPProxyAgentPassword so LDAP can look up the user groups.

Domain, server and connection configuration options

// The names of one or more domains you wish to use
// These names will be used for the other options, it is freely choosable and not dependent
// on your system. These names will show in the Login-Screen, so it is important that the user 
// understands the meaning.
//
// REQUIRED
//
// Default: none
$wgLDAPDomainNames = array(
  'testADdomain',
  'testLDAPdomain',
);

// The fully qualified name of one or more servers per domain you wish to use. If you are
// going to use SSL or StartTLS, it is important that the server names provided here exactly
// match the name provided by the SSL certificate returned by the server; otherwise, you may
// have problems.
// REQUIRED
// Default: none
$wgLDAPServerNames = array(
  'testADdomain' => 'testADserver.AD.example.com',
  'testLDAPdomain' => 'testLDAPserver.LDAP.example.com testLDAPserver2.LDAP.example.com',
);

// Allow the use of the local database as well as the LDAP database.
// Mostly for transitional purposes. Unless you *really* know what you are doing,
// don't use this option. It will likely cause you annoying problems, and
// it will cause me annoying support headaches.
// Warning: Using this option will allow MediaWiki to leak LDAP passwords into
// its local database. It's highly recommended that this setting not be used for
// anything other than transitional purposes.
// Default: false
$wgLDAPUseLocal = false;

// The type of encryption you would like to use when connecting to the LDAP server.
// Available options are 'tls', 'ssl', and 'clear'
// Default: tls
$wgLDAPEncryptionType = array(
  'testADdomain' => 'tls',
  'testLDAPdomain' => 'clear',
);

// Custom LDAP configuration options; allows you to set options specified at
// https://www.php.net/function.ldap-set-option
// Default: none
$wgLDAPOptions = array(
  'testADdomain' => array( LDAP_OPT_DEREF, 0 ),
  'testLDAPdomain' => array( LDAP_OPT_DEREF, 1 ),
);

// Connect with a non-standard port
// Available in 1.2b+
// Default: 389 for clear/tls, 636 for ssl
$wgLDAPPort = array(
  'testADdomain' => 1389,
  'testLDAPdomain' => 1636,
);

Binding configuration options

Straight DN bind options

// The search string to be used for straight binds to the directory; USER-NAME will be
// replaced by the username of the user logging in.
// This option is not required (and shouldn't be provided) if you are using a proxyagent
// and proxyagent password.
// If you are using AD style binding (TDOMAIN\\USER-NAME or USER-NAME@TDOMAIN) and
// want to be able to use group syncing, preference pulling, etc., you'll need to set
// $wgLDAPBaseDNs and $wgLDAPSearchAttributes for the domain.
$wgLDAPSearchStrings = array(
  'testADdomain' => "TDOMAIN\\USER-NAME",
  'testLDAPdomain' => 'uid=USER-NAME,ou=people,dc=LDAP,dc=example,dc=com',
);

Proxied or search based bind options

// User and password used for proxyagent access.
// Please use a user with limited access, NOT your directory manager!
$wgLDAPProxyAgent = array(
  'testLDAPdomain' => 'cn=proxyagent,ou=profile,dc=LDAP,dc=example,dc=com',
);
$wgLDAPProxyAgentPassword = array(
  'testLDAPdomain' => 'S0M3L0ngP@$$w0r6ofS0meV@rie222y!',
);

// Search filter.
// These options are only needed if you want to search for users to bind with them. In otherwords,
// if you cannot do direct binds based upon $wgLDAPSearchStrings, then you'll need these two options.
// If you need a proxyagent to search, remember to set $wgLDAPProxyAgent, and $wgLDAPProxyAgentPassword.
// Anonymous searching is supported. To do an anonymous search, use SearchAttibutes and don't set a Proxy
// agent for the domain required.
$wgLDAPSearchAttributes = array(
  'testADdomain' => 'sAMAccountName',
  'testLDAPdomain' => 'uid'
);

// Base DNs. Group and User base DNs will be used if available; if they are not defined, the search
// will default to $wgLDAPBaseDNs
$wgLDAPBaseDNs = array(
  'testADdomain' => 'dc=AD,dc=example,dc=com',
  'testLDAPdomain' => 'dc=LDAP,dc=example,dc=com'
);
$wgLDAPGroupBaseDNs = array(
  'testADdomain' => 'ou=Domain Groups,dc=AD,dc=example,dc=com',
  'testLDAPdomain' => 'ou=group,dc=LDAP,dc=example,dc=com'
);
$wgLDAPUserBaseDNs = array(
  'testADdomain' => 'ou=Domain Users,dc=AD,dc=example,dc=com',
  'testLDAPdomain' => 'ou=people,dc=LDAP,dc=example,dc=com'
);

Options for using LDAP as a user backend

// User and password used for writing to the directory.
// Please use a user with limited access, NOT your directory manager!
// Defaults: none; disabled
$wgLDAPWriterDN = array(
  'testLDAPdomain' => 'uid=priviledgedUser,ou=people,dc=LDAP,dc=example,dc=com'
);
$wgLDAPWriterPassword = array(
  'testLDAPdomain' => 'S0M3L0ngP@$$w0r6ofS0meV@rie222y!'
);

// A location to add users to if you are using $wgLDAPSearchAttributes and $wgLDAPAddLDAPUsers.
// This option requires $wgLDAPWriterDN and $wgLDAPWriterPassword to be set.
// Default: none; disabled
$wgLDAPWriteLocation = array(
  'testLDAPdomain' => 'ou=people,dc=LDAP,dc=example,dc=com'
);

// Options for adding users, and/or updating user preferences in LDAP. If you use these options
// you must set $wgLDAPWriterDN and $wgLDAPWriterPassword.
// Defaults: false
$wgLDAPAddLDAPUsers = array(
  'testADdomain' => false,
  'testLDAPdomain' => true
);
$wgLDAPUpdateLDAP = array(
  'testADdomain' => false,
  'testLDAPdomain' => true
);

// Change the hashing algorithm that is used when changing passwords or creating
// user accounts. The default (not setting this variable) will use a base64 encoded
// SHA encrypted password. I do not recommend setting this variable unless you need to
// store clear text or crypt passwords.
// Default: sha
$wgLDAPPasswordHash = array(
  'testLDAPdomain' => 'crypt'
);

// Option for mailing temporary passwords to users
// (notice, this will store the temporary password in the local directory
// if you cannot write LDAP passwords because writing is turned off,
// this probably won't help you much since users will not be able to change
// their password)
// This option requires $wgLDAPWriterDN, $wgLDAPWriterPassword and $wgLDAPUpdateLDAP
// Default: false
$wgLDAPMailPassword = array(
  'testLDAPdomain' => true
);

// Option for allowing the retreival of user preferences from LDAP.
// Only pulls a small amount of info currently.
// Default: false
// DEPRECATED in 1.2a
$wgLDAPRetrievePrefs = array(
  'testADdomain' => true,
  'testLDAPdomain' => true
);

// Option for pulling specific preferences. Available options
// are 'email', 'realname', 'nickname', 'language'
// Ensure all attribute names given are in lower case.
// Default: none; disabled
// Available in 1.2a
$wgLDAPPreferences = array(
  'testADdomain' => array( 'email' => 'mail','realname' => 'cn','nickname' => 'samaccountname'),
  'testLDAPdomain' => array( 'email' => 'mail','realname' => 'displayname','nickname' => 'cn','language' => 'preferredlanguage')
);

MediaWiki user creation options

// Don't automatically create an account for a user if the account exists in LDAP
// but not in MediaWiki.
// Default: false.
$wgLDAPDisableAutoCreate = array(
  'testADdomain' => true
);

// Shortest password a user is allowed to login using. Notice that 1 is the minimum so that
// when using a local domain, local users cannot login as domain users (as domain user's
// passwords are not stored)
// Default: 0
$wgMinimalPasswordLength = 1;

Debugging options

Make sure you set this after the require_once line. Otherwise it won't work.

// Option for getting debug output from the plugin. 1-3 available. 1 will show
// non-sensitive info, 2 will show possibly sensitive user info, 3+ will show
// sensitive system info. Setting this on a live public site is probably a bad
// idea.
// Default: 0
$wgLDAPDebug = 1;

Specifying the debug file

This is required in version 1.2b+:

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

Group options

Using LDAP groups in any way requires $wgLDAPBaseDNs to be set!

The following settings pertain to both synchronizing groups, and group based login restriction.

// Whether the username in the group is a full DN (AD generally does this), or
// just the username (posix groups generally do this)
// Default: false
$wgLDAPGroupUseFullDN = array(
  'testLDAPdomain' => true,
  'testADdomain' => true
);

// Munge the case of the username to lowercase when doing searches in groups
// Default: true
$wgLDAPLowerCaseUsername = array(
  'testLDAPdomain' => true,
  'testADdomain' => false
);

// Use the exact name retrieved from LDAP after the user has authenticated to search for groups.
// This requires the SetUsernameAttributeFromLDAP hook to be used (see the smartcard section).
// Default: false
$wgLDAPGroupUseRetrievedUsername = array(
  'testLDAPdomain' => false,
  'testADdomain' => false
);

// The objectclass of the groups we want to search for
$wgLDAPGroupObjectclass = array(
  'testLDAPdomain' => 'groupofuniquenames',
  'testADdomain' => 'group',
);

// The attribute used for group members
$wgLDAPGroupAttribute = array(
  'testLDAPdomain' => 'uniquemember',
  'testADdomain' => 'member',
);

// The naming attribute of the group
$wgLDAPGroupNameAttribute = array(
  'testLDAPdomain' => 'cn',
  'testADdomain' => 'cn',
);

// Use the memberOf attribute to find groups.
// If memberOf is used, it will be the only method used for searching for groups.
// This means it will search $wgLDAPUserBaseDNs for the memberOf attribute and compare
// all results to $wgLDAPRequiredGroups and not take $wgLDAPGroupBaseDNs into account
// for limiting the search.
// Default: false
// Available in 1.2b+
$wgLDAPGroupsUseMemberOf = array(
  'testLDAPdomain' => false,
  'testADdomain' => true,
);

Synchronizing LDAP groups with MediaWiki security groups

Warning: MediaWiki group names cannot contain whitespace, but LDAP group names can. If you synchronize an LDAP group name that contains whitespace, it will not work properly on Special:UserRights. See bug T87376.

// Pull LDAP groups a user is in, and update local wiki security group.
// Default: false
$wgLDAPUseLDAPGroups = array(
  'testADdomain' => true,
  'testLDAPdomain' => true,
);

// A list of groups that won't automatically have their members
// removed, but will have them added. The sysop, bureaucrat, and bot
// groups are always considered locally managed.
$wgLDAPLocallyManagedGroups = array(
  'testADdomain' => array( 'adtestgroup', 'adtestgroup2' ),
  'testLDAPdomain' => array( 'ldaptestgroup', 'ldaptestgroup2' ),
);

// Get every group from LDAP, and add it to $wgGroupPermissions. This
// is useful for plugins like Group Based Access Control. This is very
// resource intensive, and probably shouldn't be used in very large
// environments.
// Default: false
$wgLDAPGroupsPrevail = array(
  'testADdomain' => true,
  'testLDAPdomain' => true
);

Group based login restriction configuration options

// An array of the groups the user is required to be a member of.
$wgLDAPRequiredGroups = array(
  'testLDAPdomain' => array(
    'cn=testgroup,ou=groups,dc=LDAP,dc=example,dc=com',
    'cn=testgroup2,ou=groups,dc=LDAP,dc=example,dc=com',
  ),
  'testADdomain' => array(
    'cn=testgroup,ou=groups,dc=AD,dc=example,dc=com',
  )
);

// An array of the groups the user cannot be a member of.
// Available in 1.2b+
$wgLDAPExcludedGroups = array(
  'testLDAPdomain' => array(
      'cn=evilgroup,ou=groups,dc=LDAP,dc=example,dc=com',
      'cn=evilgroup2,ou=groups,dc=LDAP,dc=example,dc=com',
      ),
  'testADdomain' => array(
      'cn=evilgroup,ou=groups,dc=AD,dc=example,dc=com',
      )
);

// Whether or not the plugin should search in nested groups
// Not currently used for group synchronization
// Default: false
$wgLDAPGroupSearchNestedGroups = array(
  'testLDAPdomain' => false,
  'testADdomain' => true,
);

// Whether or not to do group searches using an active directory
// optimized way.
// Available in 2.0e
// Default: false
$wgLDAPActiveDirectory = array(
    'testLDAPDomain' => false,
    'testADLDAPDomain' => true,
);

Search based login restriction configuration options

// Used with a proxy search
// Require the following additional search string.
$wgLDAPAuthAttribute = array(
  'testADdomain' => '!(userAccountControl:1.2.840.113556.1.4.803:=2)',
  'testLDAPdomain' => '!(nsaccountlock=true)',
);

Auto authentication options

It is highly recommended to see the Smartcard Configuration Examples, and Kerberos Configuration Examples pages before messing with these options.

If you use Smartcard and/or Kerberos authentication, it would be foolish not to use HTTPS and SSL/TLS

// Enable smartcard authentication
// DEPRECATED in 1.2a
$wgLDAPAutoAuthMethod = 'smartcard';

// The domain that will be using smartcard authentication
// DEPRECATED in 1.2a
$wgLDAPSmartcardDomain = 'testADdomain-smartcard';

// The domain that will be using auto authentication
// Available in 1.2a
$wgLDAPAutoAuthDomain = 'testADdomain-auto';

// The attribute from the smartcard you wish to search LDAP for
// DEPRECATED in 1.2a
$wgLDAPSSLUsername = $_SERVER['SSL_CLIENT_S_DN_CN'];

// The attribute from the webserver you wish to search LDAP for
// Available in 1.2a
$wgLDAPAutoAuthUsername = $_SERVER['SSL_CLIENT_S_DN_DN'];

User-name mapping configuration hook

// This hook is called by the LdapAuthentication plugin. It is a configuration hook. Here we
// are specifying what attibute we want to use for a username in the wiki.
// Note that this hook is NOT called on a straight bind.
// The hook calls the function defined below.
$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]['samaccountname'][0];
        return true;
}

Yet another working AD configuration example - with SSO

Wiki-PHP-Configuration-File: LocalSettings.php

require_once( "$IP/extensions/LdapAuthentication/LdapAutoAuthentication.php" );
require_once ("$IP/extensions/LdapAuthentication/LdapAuthentication.php");

$wgAuth = new LdapAuthenticationPlugin();

$wgLDAPDebug = 99; # 3
$wgDebugLogGroups['ldap'] = '/tmp/debug-ldap.log' ;


$wgLDAPAutoAuthDomain     = 'myAD';
$wgLDAPDomainNames        = array('myAD');
$wgLDAPServerNames        = array('myAD' => 'my.ldapserver.com');
$wgLDAPBaseDNs            = array('myAD' => 'dc=example,dc=com');
$wgLDAPGroupBaseDNs       = array('myAD'=> 'OU=Group,OU=STW,dc=example,dc=com');
$wgLDAPUserBaseDNs        = array('myAD'=> 'OU=User,OU=STW,dc=example,dc=com');

$wgLDAPRetrievePrefs      = array('myAD' => true);
$wgLDAPPreferences        = array('myAD' => array('email' => 'mail',
                                                  'realname' => 'displayname',
                                                  'nickname' => 'samaccountname',
                                                  'language' => 'msexchuserculture'));

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

$wgLDAPProxyAgent         = array('myAD' => 'CN=agentProxyUser,CN=Users,dc=example,dc=com');
$wgLDAPProxyAgentPassword = array('myAD' => 'agentPassword');

$wgLDAPUseLDAPGroups      = array('myAD' => true);

$wgLDAPEncryptionType     = array('myAD' => 'clear'); # ssl, clear
$wgLDAPUseLocal           = false;
$wgLDAPGroupsUseMemberOf  = array('myAD' => true);


## All users must be in this group to be able to login
$wgLDAPRequiredGroups     = array('myAD' => array('CN=Group1,OU=Applikationen,OU=Group,OU=STW,dc=example,dc=com',
                                                  'CN=Group2,OU=Group,OU=STW,dc=example,dc=com'
                                                 )
                                 );


if (isset($_SERVER['REMOTE_USER'])) {
    $wgLDAPAutoAuthUsername = preg_replace( '/@.*/', '', $_SERVER['REMOTE_USER']);
}

AutoAuthSetup();

Apache-Configuration-File: /etc/apache2/sites-enabled/001_wiki_apache_host_configuration.conf

<VirtualHost *:80>
        ServerAdmin webmaster@yourMailDomain.com
        DocumentRoot /var/www/html/wiki
        ServerName yourWikiDomain.com

        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined

    <Location />
        AuthType Kerberos
        AuthName "Kerberos"
        KrbServiceName HTTP/spn-host-entry.example.com
        KrbAuthRealms EXAMPLE.COM
        KrbMethodNegotiate on
        KrbSaveCredentials off
        KrbMethodK5Passwd off
        Krb5Keytab /etc/apache2/file.keytab

        Order deny,allow
        Deny from all
        require valid-user
        Satisfy Any
    </Location>

</VirtualHost>