Extension:LDAP Authentication/Configuration Options

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

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

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

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]

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]

Edit $IP/LocalSettings.php

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

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

Domain, server and connection configuration options[edit]

// 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.
// Default: none
$wgLDAPDomainNames = array(

// 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.
// 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[edit]

Straight DN bind options[edit]

// 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[edit]

// 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[edit]

// 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[edit]

// 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[edit]

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

This is required in version 1.2b+:

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

Group options[edit]

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

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

// An array of the groups the user is required to be a member of.
$wgLDAPRequiredGroups = array(
  'testLDAPdomain' => array(
  'testADdomain' => array(

// An array of the groups the user cannot be a member of.
// Available in 1.2b+
$wgLDAPExcludedGroups = array(
  'testLDAPdomain' => array(
  'testADdomain' => array(

// 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[edit]

// 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[edit]

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

// 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[edit]

// 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[edit]

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',

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


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