View source for Extension:LDAPProvider/en

<languages />
{{MWStake extension}}
As a successor of {{ll|Extension:LDAPAuthentication2|LDAPAuthentication2}}<ref name="ldapauthentication2" /><ref name="ldapsflow" /> a {{ll|LDAP Stack|stack of LDAP related extensions}} has been created.‎
They all need to interact with a remote LDAP resource<ref name="ldap" />.
To ease and unify configuration and maintenance, this extension was created.
It provides classes and configuration to query data from LDAP resources.
{{Extension
| description = Provides a common infrastructure to connect to a LDAP resource and run queries against it.
| status = stable
| license = 
| image = MWStake_LDAPStack_Icon.svg
| author = * [[User:Cindy.cicalese|Cindy Cicalese]],
* [https://mwstake.org/ Mark A. Hershberger],
* [[User:Osnard|Robert Vogel]]
| version = 
| compatibility policy = rel
| mediawiki = 
| download = {{WikimediaDownload|phab=ELDQ}}
| phabricator = mediawiki-extensions-LDAPProvider
| table1 = ldap_domains
}}

== Installation ==
{{ExtensionInstall
|LDAPProvider
|registration=required
|repo-name=LDAPProvider
|custom-steps=* Run <code>php maintenance/update.php</code> to create the necessary database table(s).
* [[#Configuration|Configure as required]]
}}

== 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 <code>LocalSettings.php</code>.
Be aware that those variables '''do not have a <code>wg</code> 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<ref name="dn" />.
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 ===
{| class="wikitable"
|+When using them in <code>LocalSettings.php</code>, these variables need to be prefixed with <code>$LDAPProvider</code>
!Name
!Default
!Description
|-
|<code>CacheType</code>
|<code>"CACHE_ANYTHING"</code>
|The sort of cache to use for the connection information.
|-
|<code>CacheTime</code>
|<code>500</code>
|How long cached items should stick around in seconds.
|-
|<code>ClientRegistry</code>
|<code>[]</code>
|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 <code>Client</code>.
|-
|<code>DomainConfigs</code>
|<code>"/etc/mediawiki/ldapprovider.json"</code>
|Stores per domain configuration. Only evaluated if <code>$LDAPProviderDomainConfigProvider</code> is set to use the default <code>LocalJSONFile</code>. See below.
|-
|<code>DomainConfigProvider</code>
|<code>"\\MediaWiki\\Extension\\LDAPProvider\\DomainConfigProvider\\LocalJSONFile::newInstance"</code>
|Specifies the mechanism for obtaining the domain configuration. Must be a callback that returns an <code>IDomainConfigProvider</code>.
|-
|<code>DefaultDomain</code>
|<code>""</code>
|Specifies the domain to fall back in case no domain was found for a user. This is often the case when using [[Special:MyLanguage/Extension:Auth_remoteuser|Extension:Auth_remoteuser]] for network based authentication.
|-
|<code>PreSearchUsernameModifierRegistry</code>
|<pre>[
 "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"
]</pre>
|Specifies factory callbacks for objects of type <code>MediaWiki\Extension\LDAPProvider\IPreSearchUsernameModifier</code>. The keys can be used in the domain configuration in the field <code>connection.presearchusernamemodifiers</code>. Example for a custom modifier:
<pre>
$LDAPProviderPreSearchUsernameModifierRegistry
['custom-prefix-modifier'] = function() {
  return new MediaWiki\Extension\LDAPProvider
  \PreSearchUsernameModifier\GenericCallback(
    function( $username ) {
      return "some_prefix_$username";
  } );
};
</pre>
|}

=== Domain config settings ===
{| class="wikitable"
|+
!Name
!Default
!Description
|-
|<code>server</code>
| -
|One or more hostnames of the LDAP backend. Separated by a single space.
|-
|<code>port</code>
|<code>389</code>
|The port the LDAP server is listening to
|-
|<code>user</code>
|<code>""</code>
|The FQDN of a user who has at least read rights
|-
|<code>pass</code>
|<code>""</code>
|The password for the user above
|-
|<code>options</code>
|<code>{}</code> (JSON object or indexed PHP array)
|[https://php.net/function.ldap-set-option LDAP specific options]. Must be string literals as key.
|-
|<code>enctype</code>
|<code>clear</code>
|Must be one of <code>'ldapi'</code>, <code>'ssl'</code>, <code>'tls'</code>, or <code>'clear'</code>
|-
|<code>groupbasedn</code>
|<code>""</code>
|Used for group membership queries
|-
|<code>userbasedn</code>
|<code>""</code>
|Used for user info queries. Also for resolving a local username into an appropriate user DN
|-
|<code>searchattribute</code>
|<code>""</code>
|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.
|-
|<code>searchstring</code>
|<code>""</code>
|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"
|-
|<code>grouprequest</code>
|<code>"MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupUniqueMember::factory"</code>
|Mechanism to fetch user group data. Following types are available:

* <code>"MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupMember::factory"</code>
* <code>"MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupUniqueMember::factory"</code>
* <code>"MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\UserMemberOf::factory"</code>
* <code>"MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\Configurable::factory"</code>
* <code>"MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupMemberUid::factory"</code>

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).

|-
|<code>groupobjectclass</code>
|<code>""</code>
|In case <code>Configurable</code> is used in <code>grouprequest</code> the <code>groupobjectclass</code> can be specified here. E.g. <code>group</code>
|-
|<code>groupattribute</code>
|<code>"member"</code>
|In case <code>Configurable</code> is used in <code>grouprequest</code> the <code>groupattribute</code> can be specified here. E.g. <code>member</code>
|-
|<code>presearchusernamemodifiers</code>
|<code>[]</code>
|Username modifiers, for the purpose of LDAP-query.<br/>Useful when LDAP usernames do not match MediaWiki username format.<br/>( e.g. LDAP accounts use underscores-instead-of-spaces, or need to be lower-cased )<br/>The modified username will be used with "searchstring" or "searchattribute" methods of determining user DN.
<br />'''Use one-or-more of the available modifiers:'''
* lowercase
* removespaces
* spacestounderscores
<br/>'''Sample Usage:'''<br/><code>[ "lowercase" ]</code><br/><code>[ "removespaces" ]</code><br/><code>[ "spacestounderscores", "lowercase" ]</code>
<br/><br/>'''Working Example:''' Login-User '''Joe Bloggs''' will be translated to '''joe_bloggs''' LDAP search query,<br/>
with config of: <code>[ "spacestounderscores", "lowercase" ]</code>
<br/><br/>Additional modifiers can be registered through the <code>$LDAPProviderPreSearchUsernameModifierRegistry</code> (see above) variable.
|-
|<code>nestedgroups</code>
|<code>false</code>
|Whether to use [https://ldapwiki.com/wiki/LDAP_MATCHING_RULE_IN_CHAIN LDAP_MATCHING_RULE_IN_CHAIN] to fetch nested groups. Will only work for Microsoft Active Directory and with <code>grouprequest = MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\GroupMember::factory</code>


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 <code>$LDAPProviderDomainConfigProvider</code>.
It needs to be a callback that returns an object of type <code>IDomainConfigProvider</code>.

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

<syntaxhighlight lang=php>
$LDAPProviderDomainConfigs = "$IP/../ldapprovider.json";
</syntaxhighlight>

====Example====
<syntaxhighlight lang="json">
{
	"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"
		}
	}
}

</syntaxhighlight>

===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 <code>$LDAPProviderDomainConfigs</code> callback return an instance of InlinePHPArray.

====Example====
<syntaxhighlight lang="php">
$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 );
};
</syntaxhighlight>

== Advanced configuration ==

=== Dynamic usergroup attribute ===
'''Example'''

<code>ldapprovider.json</code>:
<syntaxhighlight lang="json">
 {
 	"LDAP": {
 		"connection": {
 			"server": "...",
 			...
 			"grouprequest": "...Configurable::factory",
 			"groupobjectclass": "groupOfUniqueNames",
 			"groupattribute": "uniqueMember",
 			"group-attribute-value-callback": "myCoolCallback"
 		},
 },
</syntaxhighlight>
Here <code>"group-attribute-value-callback"</code> specifies the name of some callback function which contains logic for the calculation of <code>"groupattribute"</code> value.

<code>LocalSettings.php</code>:
<syntaxhighlight lang="php">
function myCoolCallback( $username ) {
 	return new \MediaWiki\Extension\LDAPProvider\EscapedString( $username );
 }
</syntaxhighlight>
That's an example of a simple callback which returns the unchanged username as <code>"groupattribute"</code> value.

== Versioning ==
{{LDAP Stack Version Matrix}}

== Troubleshooting ==

=== Exception: "No configuration available for domain 'XYZ'!" ===
Please make sure, that the values in the database field <code>ldap_domains.domain_id</code> match with the values set in the first level of the domain-configuration (e.g. in <code>ldapprovider.json</code>, you will need to replace "LDAP" at the top level with your domain.
This can be checked by viewing the <code>$_SERVER['USERDOMAIN']</code> entry in your server's <code>phpinfo()</code> ).
If they don't, you can either change the entries in the database using <code>UPDATE ldap_domains SET domain = "DomainNameAsInConfiguration";</code> 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 [[Special:MyLanguage/Extension:LDAPAuthorization|LDAPAuthorization]] extension (as recommended in the PluggableAuth documentation), you need to add the authorization configuration in the LDAPProvider domain config (more info on [[Special:MyLanguage/Extension:LDAPAuthorization#Configuration|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 ==
* [[Special:MyLanguage/Manual:Active Directory Integration|Manual:Active Directory Integration (PluggableAuth + LDAP Stack)]]

==References==
{{reflist|refs=
<ref name="ldapauthentication2">previously [[Special:MyLanguage/Extension:LDAP_Authentication|Extension:LDAP_Authentication]]</ref>
<ref name="dn">Distinguished Name (DN)</ref>
<ref name="ldap">Lightweight Directory Access Protocol (LDAP) <sup>([[w:en:Lightweight_Directory_Access_Protocol|en]])</sup></ref>
<ref name="ldapsflow">[[LDAP hub#LDAP stack flow|LDAP stack flow]]</ref>
}}

{{Used by}}

[[Category:LDAP extensions{{#translation:}}]]
[[Category:LDAP Stack Member{{#translation:}}]]