Extension:LDAPProvider

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki Stakeholders' Group Logo.svg This extension is maintained by a member of the MediaWiki Stakeholders' Group.

As a successor of LDAP Authentication 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
OOjs UI icon advanced.svg
LDAPProvider
Release status: experimental
MWStake LDAPStack Icon.svg
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 1.0.0-alpha
Compatibility policy release branches
MediaWiki 1.31+
Database changes Yes
License GNU General Public License 2.0 or later
Download
Translate the LDAPProvider extension if it is available at translatewiki.net
Check usage and version matrix.
Issues Open tasks · Report a bug

"Extension config" versus "Domain config"[edit]

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

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.

Domain config settings[edit]

Name Default Description
server - One or more hostnames of the LDAP backend. Seperated by a single space.
port 389 The port the LDAP server is listening to
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 ""
searchstring ""
grouprequest "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupUniqueMember::factory" Mechanism to fetch user group data. There are three types available:
  • "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupMember::factory"
  • "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupUniqueMember::factory"
  • "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\UserMemberOf::factory"

Which one to choose depends on the LDAP backend.

Domain config providers[edit]

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

This is the default way. Just set up the extension configuration $LDAPProviderDomainConfigs to point to a valid JSON file.

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

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