Manual:Active Directory Integration

From mediawiki.org

PluggableAuth with Active-Directory LDAP[edit]

With the evolution of Extension:PluggableAuth and LDAP Stack, getting integrated with Active-Directory LDAP is possible, but somewhat complex for new-comers.

A configuration example is provided here, to ease the setup process for those wishing to integrate with MS-AD via LDAP.

Objectives / Aims[edit]

  • Configure Mediawiki to use LDAP settings from a single location - ldap.json
  • Users will login with NT-Logon Username, also known as SAMAccountName attribute in a standard AD-schema.

Method[edit]

  • LDAP Stack extensions use a number of LDAP attributes to auto-configure the Mediawiki User: SAMAccountName, DisplayName, Mail.
  • LDAP Stack extensions use memberof attribute values to determine if any Security-Groups / Distribution-Lists map to Mediawiki Groups

Versioning[edit]

  • LDAP Stack extensions should all be at the same version - Long Term Support (LTS) versions are recommended (e.g. 1.35)
  • Direct downloads can be performed from: https://extdist.wmflabs.org/dist/extensions/


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

Required Extensions[edit]

Required AD Bind-Account[edit]

  • Mediawiki uses an LDAP Bind-User / Bind-Password for communications with Active-Directory.
  • Ensure an AD user is provisioned, and grab the LDAP Distinguished Name for the User
  • Sample: CN=MediawikiAuthenticator,OU=Users,DC=acme,DC=com

LDAP Environment[edit]

The important configuration entities are detailed below - replace the default-values with your own when tuning ldap.json

Entity Value Comments
Domain acme.com AD-Forest Domain Name
Root Distinguished-Name (DN) dc=acme,dc=com Use MS "Domains and Trusts" console, with Advanced-View enabled, to view domain LDAP attribute (DN)
User Distinguished-Name (DN) dc=acme,dc=com Use MS "Domains and Trusts" console, with Advanced-View enabled, to view domain LDAP attribute (DN)
Bind-Account Distinguished-Name (DN) CN=MediawikiAuthenticator,OU=Users,DC=acme,DC=com Use MS "Domains and Trusts" console, with Advanced-View enabled, to view AD User attribute (DN)

This value is case-sensitive.

Encryption clear No TLS/SSL is used in the example.
User Search Attribute samaccountname Utilise MS-AD samaccountname attribute to locate a single LDAP record.
User Group Membership Attribute memberof Utilise MS-AD memberof attribute, to get list of Group-DNs that user is a member of.

Configuration Example: LDAP Configuration with 1 Group-Mapping[edit]

This example works for a small single-domain forest, or multi-domain forest (by using the parent domain).

Install Mediawiki and Extensions[edit]

  1. Install PHP, and the php-ldap module (usually available on the same package-manager as PHP)
  2. Install Mediawiki, perform install and update routines.
  3. Install all extensions listed above (Required Extensions) into /extensions/

Prepare ldap.json[edit]

Create an LDAP configuration file. For simplicity, we place this new file at /var/www/ldap.json then protect it for reading by the web-server.

touch /var/www/ldap.json
chown www-data:www-data /var/www/ldap.json
chmod 600 /var/www/ldap.json

# use your favourite editor to add the following json
vi /var/www/ldap.json

{
	"acme.com": {
		"connection": {
			"server": "my-domain-controller.acme.com",
			"port": "3269",
			"use-tls": "true",
			"user": "CN=MediawikiAuthenticator,OU=Users,DC=acme,DC=com",
			"pass": "foobar",
			"enctype": "clear",
			"options": {
				"LDAP_OPT_DEREF": 1
			},
			"basedn": "dc=acme,dc=com",
			"userbasedn": "dc=acme,dc=com",
			"groupbasedn": "dc=acme,dc=com",
			"searchattribute": "samaccountname",
			"usernameattribute": "samaccountname",
			"realnameattribute": "cn",
			"emailattribute": "mail",
			"grouprequest": "MediaWiki\\Extension\\LDAPProvider\\UserGroupsRequest\\UserMemberOf::factory",
			"presearchusernamemodifiers": [ "spacestounderscores", "lowercase" ]
		},
		"userinfo": [],
		"authorization": [],
		"groupsync": {
			"mapping": {
				"engineering": "CN=EngineeringCoreTeam,OU=Groups,DC=acme,DC=com",
				"bureaucrat": "CN=Mediawiki Admins,OU=Groups,DC=acme,DC=com",
				"interface-admin": "CN=Mediawiki Admins,OU=Groups,DC=acme,DC=com",
				"sysop": "CN=Mediawiki Admins,OU=Groups,DC=acme,DC=com"
			}
		}
	}
}
  • A critical piece of configuration is the acme.com key in line #2 of the JSON.
  • Replace this with your AD Domain
  • Replace the following values in connection
    • server
    • user
    • pass
    • basedn
    • userbasedn
  • Replace the groupsync -> mapping values with some valid Group-DNs taken from MS "Domains and Trusts" console.
    • This allows you to specify a DN which provides sysop privileges

Tune LocalSettings.php[edit]

// Safe IP or not (for bypassing external login via AD)
$safeIPs = array('127.0.0.1','localhost');
$ipsVars = array('HTTP_X_FORWARDED_FOR','HTTP_X_REAL_IP','REMOTE_ADDR');
foreach ($ipsVars as $ipsVar) {
 if (isset($_SERVER[$ipsVar]) && mb_strlen($_SERVER[$ipsVar]) > 3 ) { $wikiRequestIP = $_SERVER[$ipsVar]; break; }
}
$wikiRequestSafe = ( isset($wikiRequestIP ) && ( in_array($wikiRequestIP,$safeIPs) ));


// Create Wiki-Group 'engineering' from default user group
$wgGroupPermissions['engineering'] = $wgGroupPermissions['user'];


// Private Wiki. External LDAP login. Default NS requires login.
$wgEmailConfirmToEdit = false;
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['read'] = false;
$wgGroupPermissions['*']['createaccount'] = false;
$wgGroupPermissions['sysop']['createaccount'] = false;
$wgGroupPermissions['*']['autocreateaccount'] = true;
$wgBlockDisablesLogin = true;

// Load LDAP Config from JSON
$ldapJsonFile = "$IP/ldap.json";
$ldapConfig = false;
if (is_file($ldapJsonFile) && is_dir("$IP/extensions/LDAPProvider")) {
  $testJson = @json_decode(file_get_contents($ldapJsonFile),true);
  if (is_array($testJson)) {
    $ldapConfig = true;
  } else {
    error_log("Found invalid JSON in file: $IP/ldap.json");
  }
}

// Activate Extension
if ( $ldapConfig ) {

  wfLoadExtension( 'PluggableAuth' );
  wfLoadExtension( 'LDAPProvider' );
  wfLoadExtension( 'LDAPAuthentication2' );
  wfLoadExtension( 'LDAPAuthorization' );
  wfLoadExtension( 'LDAPUserInfo' );
  wfLoadExtension( 'LDAPGroups' );

  $LDAPProviderDomainConfigs = $ldapJsonFile;

  // Force LDAPGroups to sync by choosing a domain (e.g. first JSON object in ldap.json)
  $LDAPProviderDefaultDomain = array_key_first(json_decode(file_get_contents($LDAPProviderDomainConfigs), true));

  $wgPluggableAuth_Config = array(
      array(
        'plugin' => 'LDAPAuthentication2',
        'buttonLabelMessage' => 'pt-login-button',
        'data' => ['domain'=> $LDAPProviderDefaultDomain]
         ),
      array('plugin' => 'LDAPAuthorization'),
    );


  if ($wikiRequestSafe) { $LDAPAuthentication2AllowLocalLogin = true; }
}

Run update.php and test LDAP login[edit]

  • After configuring LocalSettings.php and browsing to your Wiki, you should be able to load the public index / Main Page.
  • LDAP login will fail until you run: php /.../mediawiki/maintenance/update.php
  • This is because the LDAP extensions require some new SQL tables.
  • After running update.php, start a fresh browser session and perform a test login.

Debugging[edit]

  • If you encounter problems, enable debug and review the output during login.
  • Validate config values and system connectivity using ldapsearch 
    ldapsearch -h server -p port -D "user"  -w "pass" -x -v -b "basedn"
  • Validate config files and PHP Connectivity to LDAP using CheckLogin and ShowUserInfo located in extensions/LDAPProvider/maintenance/
  • If running SELinux check to see if webserver (Apache) is allowed to connect to LDAP
    # getsebool -a | grep ldap
authlogin_nsswitch_use_ldap --> off
httpd_can_connect_ldap --> off

# setsebool -P httpd_can_connect_ldap on

# getsebool -a | grep ldap
authlogin_nsswitch_use_ldap --> off
httpd_can_connect_ldap --> on
  • Also see Manual:How to debug/Login problems
Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Active_Directory_Integration&oldid=6176667"