Extension:LDAPProvider

As a successor of LDAPAuthentication2 a stack of LDAP related extensions has been created.‎ They all need to interact with a remote LDAP resource. To ease and unify configuration and maintenance, this extension was created. It provides classes and configuration to query data from LDAP resources.

MediaWiki extensions manual

LDAPProvider Release status: stable
Description	Provides a common infrastructure to connect to a LDAP resource and run queries against it.
Author(s)	Cindy Cicalese, Mark A. Hershberger, Robert Vogel
Latest version	3.0.0-alpha
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
Database changes	Yes
Composer	mediawiki/ldap-provider
Tables	ldap_domains
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Download Git master browse repository (Phabricator · GitHub) commit history repository contributors (GitHub) code review
Parameters $wgCacheTime $wgCacheType $wgPreSearchUsernameModifierRegistry $wgDefaultDomain $wgDomainConfigs $wgDomainConfigProvider $wgClientRegistry
Hooks used LoadExtensionSchemaUpdates
Quarterly downloads	373 (Ranked 8th)
Translate the LDAPProvider extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

Installation

• Download and move the extracted LDAPProvider folder to your extensions/ directory.
  Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/LDAPProvider
• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'LDAPProvider' );
  

• Run php maintenance/update.php to create the necessary database table(s).
• Configure as required
•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

"Extension config" versus "Domain config"

This extension features two kinds of configuration. On the one side there is the classic "extension configuration". It can be set up by using global variables within the LocalSettings.php. Be aware that those variables do not have a wg prefix. Those settings affect the extension as a whole.

On the other side there is a configuration that is specific to a remote LDAP resource, like connection settings, group membership query mechanism or base DNs. Multiple domains can be configured independently. These settings only affect the communication to the LDAP resource, based on the domain that this resource serves.

Extension config settings

When using them in LocalSettings.php, these variables need to be prefixed with $LDAPProvider

Name	Default	Description
CacheType	"CACHE_ANYTHING"	The sort of cache to use for the connection information.
CacheTime	500	How long cached items should stick around in seconds.
ClientRegistry	[]	Allows registration of custom clients. The key is the domain to be handled, the value is a callback that returns an objects which derives from Client.
DomainConfigs	"/etc/mediawiki/ldapprovider.json"	Stores per domain configuration. Only evaluated if $LDAPProviderDomainConfigProvider is set to use the default LocalJSONFile. See below.
DomainConfigProvider	"\\MediaWiki\\Extension\\LDAPProvider\\DomainConfigProvider\\LocalJSONFile::newInstance"	Specifies the mechanism for obtaining the domain configuration. Must be a callback that returns an IDomainConfigProvider.
DefaultDomain	""	Specifies the domain to fall back in case no domain was found for a user. This is often the case when using Extension:Auth_remoteuser for network based authentication.
PreSearchUsernameModifierRegistry	[ "removespaces": "\\MediaWiki\\Extension\\LDAPProvider\\PreSearchUsernameModifier\\RemoveSpaces::newInstance", "spacetounderscore": "\\MediaWiki\\Extension\\LDAPProvider\\PreSearchUsernameModifier\\SpacesToUnderscores::newInstance", "spacestounderscores": "\\MediaWiki\\Extension\\LDAPProvider\\PreSearchUsernameModifier\\SpacesToUnderscores::newInstance", "strtolower": "\\MediaWiki\\Extension\\LDAPProvider\\PreSearchUsernameModifier\\ToLower::newInstance", "lowercase": "\\MediaWiki\\Extension\\LDAPProvider\\PreSearchUsernameModifier\\ToLower::newInstance" ]	Specifies factory callbacks for objects of type MediaWiki\Extension\LDAPProvider\IPreSearchUsernameModifier. The keys can be used in the domain configuration in the field connection.presearchusernamemodifiers. Example for a custom modifier: $LDAPProviderPreSearchUsernameModifierRegistry ['custom-prefix-modifier'] = function() { return new MediaWiki\Extension\LDAPProvider \PreSearchUsernameModifier\GenericCallback( function( $username ) { return "some_prefix_$username"; } ); };

Domain config settings

Name	Default	Description
server	-	One or more hostnames of the LDAP backend. Separated by a single space.
port	389	The port the LDAP server is listening to
user	""	The FQDN of a user who has at least read rights
pass	""	The password for the user above
options	{} (JSON object or indexed PHP array)	LDAP specific options. Must be string literals as key.
enctype	clear	Must be one of 'ldapi', 'ssl', 'tls', or 'clear'
groupbasedn	""	Used for group membership queries
userbasedn	""	Used for user info queries. Also for resolving a local username into an appropriate user DN
searchattribute	""	Attribute to use in searches for user DN. "uid" and "samaccountname" are common. A "searchstring" will skip this search, if your user's DNs follow a single pattern.
searchstring	""	Provides a pattern for user DN, in lieu of searching for it by "searchattribute" and username. Value should be an example DN with "USER-NAME" in the place of a real username. e.g. "CN=USER-NAME,OU=Users,DC=example,DC=com"
grouprequest	"MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupUniqueMember::factory"	Mechanism to fetch user group data. Following types are available: "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupMember::factory" "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupUniqueMember::factory" "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\UserMemberOf::factory" "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\Configurable::factory" "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupMemberUid::factory" Which one to choose depends on the LDAP backend. GroupMember searches for "group" objects by "(member=$userDN)", including nested groups, if configured (see "nestedgroups" below). GroupUniqueMember searches for "groupofUniqueName" objects where "(uniqueMember=$userDN)". UserMemberOf searches for "memberOf" attributes of the user's own LDAP object. "Configurable" does a custom search, "(&(objectclass=$objectClass)($groupAttribute=$userDN))". See groupobjectclass and groupattribute, below. GroupMemberUid searches for "posixGroup" objects by "(member=$userUid)", or nested groups, if configured (see "nestedgroups" below).
groupobjectclass	""	In case Configurable is used in grouprequest the groupobjectclass can be specified here. E.g. group
groupattribute	"member"	In case Configurable is used in grouprequest the groupattribute can be specified here. E.g. member
presearchusernamemodifiers	[]	Username modifiers, for the purpose of LDAP-query. Useful when LDAP usernames do not match MediaWiki username format. ( e.g. LDAP accounts use underscores-instead-of-spaces, or need to be lower-cased ) The modified username will be used with "searchstring" or "searchattribute" methods of determining user DN. Use one-or-more of the available modifiers: lowercase removespaces spacestounderscores Sample Usage: [ "lowercase" ] [ "removespaces" ] [ "spacestounderscores", "lowercase" ] Working Example: Login-User Joe Bloggs will be translated to joe_bloggs LDAP search query, with config of: [ "spacestounderscores", "lowercase" ] Additional modifiers can be registered through the $LDAPProviderPreSearchUsernameModifierRegistry (see above) variable.
nestedgroups	false	Whether to use LDAP_MATCHING_RULE_IN_CHAIN to fetch nested groups. Will only work for Microsoft Active Directory and with grouprequest = MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupMember::factory Specifically, this is a search for group objects where "(member:1.2.840.113556.1.4.1941:=$userDN)".

Domain config providers

By default the domain specific configuration is held in a static JSON file. But one can also use a PHP based (dynamic) configuration. The relevant extension configuration is $LDAPProviderDomainConfigProvider. It needs to be a callback that returns an object of type IDomainConfigProvider.

Static JSON file

This is the default way. Just set up the extension configuration $LDAPProviderDomainConfigs to point to a valid JSON file (should be outside of web root).

$LDAPProviderDomainConfigs = "$IP/../ldapprovider.json";

Example

{
	"LDAP": {
		"connection": {
			"server": "ldap.forumsys.com",
			"user": "cn=read-only-admin,dc=example,dc=com",
			"pass": "password",
			"options": {
				"LDAP_OPT_DEREF": 1
			},
			"basedn": "dc=example,dc=com",
			"groupbasedn": "dc=example,dc=com",
			"userbasedn": "dc=example,dc=com",
			"searchattribute": "uid",
			"searchstring": "uid=USER-NAME,dc=example,dc=com",
			"usernameattribute": "uid",
			"realnameattribute": "cn",
			"emailattribute": "mail"
		}
	}
}

Dynamic PHP array

As an alternative to the JSON file one can use a PHP array to configure the domains. In this case, just have the $LDAPProviderDomainConfigs callback return an instance of InlinePHPArray.

Example

$LDAPProviderDomainConfigProvider = function() {
	$config = [
		'LDAP' => [
			'connection' => [
				"server" => "ldap.forumsys.com",
				"user" => "cn=read-only-admin,dc=example,dc=com",
				"pass" => 'password',
				"options" => [
					"LDAP_OPT_DEREF" => 1
				],
				"basedn" => "dc=example,dc=com",
				"groupbasedn" => "dc=example,dc=com",
				"userbasedn" => "dc=example,dc=com",
				"searchattribute" => "uid",
				"searchstring" => "uid=USER-NAME,dc=example,dc=com",
				"usernameattribute" => "uid",
				"realnameattribute" => "cn",
				"emailattribute" => "mail"
			]
		]
	];

	return new \MediaWiki\Extension\LDAPProvider\DomainConfigProvider\InlinePHPArray( $config );
};

Advanced configuration

Dynamic usergroup attribute

Example

ldapprovider.json:

 {
 	"LDAP": {
 		"connection": {
 			"server": "...",
 			...
 			"grouprequest": "...Configurable::factory",
 			"groupobjectclass": "groupOfUniqueNames",
 			"groupattribute": "uniqueMember",
 			"group-attribute-value-callback": "myCoolCallback"
 		},
 },

Here "group-attribute-value-callback" specifies the name of some callback function which contains logic for the calculation of "groupattribute" value.

LocalSettings.php:

function myCoolCallback( $username ) {
 	return new \MediaWiki\Extension\LDAPProvider\EscapedString( $username );
 }

That's an example of a simple callback which returns the unchanged username as "groupattribute" value.

Versioning

LDAP Stack Extensions are targeted/qualified for MediaWiki LTS releases only.
However, this table helps to determine which extension-releases to use across all recent versions.

MediaWiki Release	Recommended Extension Version	Test Status	Latest Test Date
1.35 (LTS)	LDAPxxx_master	Tested	March 2020

Troubleshooting

Exception: "No configuration available for domain 'XYZ'!"

Please make sure, that the values in the database field ldap_domains.domain_id match with the values set in the first level of the domain-configuration (e.g. in ldapprovider.json, you will need to replace "LDAP" at the top level with your domain. This can be checked by viewing the $_SERVER['USERDOMAIN'] entry in your server's phpinfo() ). If they don't, you can either change the entries in the database using UPDATE ldap_domains SET domain = "DomainNameAsInConfiguration"; or adapt the configuration. Attention: In the current version, the domain name is case sensitive.

Exception: "No section 'authorization' found in configuration for domain 'LDAP'"

If you enabled the LDAPAuthorization extension (as recommended in the PluggableAuth documentation), you need to add the authorization configuration in the LDAPProvider domain config (more info on LDAPAuthorization Configuration)

Warning: The supplied credentials are not associated with any user on this wiki.

Check that "userbasedn" and "searchattribute" are correct.

End to End Samples

• Manual:Active Directory Integration (PluggableAuth + LDAP Stack)