Extension:LDAP Authentication/Options

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

MediaWiki extensions manual - list

LDAP Authentication Release status: stable
Implementation	User identity
Description	Provides LDAP authentication, and some authorization functionality for MediaWiki
Author(s)	Ryan Lane (Ryan laneTalk)
Last version	1.2d (2010-11-23)
MediaWiki	1.6+
License	GPL
Download	Download snapshot Subversion [Help] Browse source code View code changes

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.

When using password authentication

Edit $IP/LocalSettings.php

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

When using smartcard authentication

Edit $IP/LocalSettings.php

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

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.
//Default: none
//REQUIRED
$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.
//Default: none
//REQUIRED
$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.
//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://nz2.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

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

//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: false
$wgLDAPLowerCaseUsername = array(
  "testLDAPdomain"=>true,
  "testADdomain"=>true
  );
 
//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.
//Default: false
//Available in 1.2b+
$wgLDAPGroupsUseMemberOf = array(
  "testLDAPdomain"=>false,
  "testADdomain"=>true
  );

Synchronizing LDAP groups with MediaWiki security groups

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

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;
}