Extension:LDAP Authentication/Configuration Options
Jump to navigation
Jump to search
About - Requirements - Examples - Configuration Options - Changelog - Roadmap - Suggestions - User provided info - FAQ - Support
 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.1.0 (2018-10-11) |
| Compatibility policy | Master maintains backwards compatibility. |
| MediaWiki | 1.19-1.26 |
| Database changes | Yes |
| License | GNU General Public License 2.0 or later |
| Download | |
|
|
| 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[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
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;
}
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',
'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>