Extension:LDAP Authentication/Configuration Options

From MediaWiki.org
Jump to: navigation, search

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


MediaWiki extensions manualManual:Extensions
Crystal Clear action run.png
LDAP Authentication

Release status:Extension status stable

ImplementationTemplate:Extension#type User identity
DescriptionTemplate:Extension#description Provides LDAP authentication, and some authorization functionality for MediaWiki
Author(s)Template:Extension#username Ryan Lane (Ryan lanetalk)
Latest versionTemplate:Extension#version 2.1.0 (2014-03-28)
MediaWikiTemplate:Extension#mediawiki 1.19+
Database changesTemplate:Extension#needs-updatephp Yes
LicenseTemplate:Extension#license GNU General Public License 2.0 or later
Download
Hooks usedTemplate:Extension#hook
LoadExtensionSchemaUpdatesManual:Hooks/LoadExtensionSchemaUpdates

Translate the LDAP Authentication extension if it is available at translatewiki.net

Check usage and version matrix.

IssuesPhabricator

Open tasks · Report a bug

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:

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

When using password authentication[edit]

Edit $IP/LocalSettings.php

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

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

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.
//
// 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
// http://www.php.net/manual/en/function.ldap-set-option.php
// 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(
    '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[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
$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[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;
}