Extension:SimpleSAMLphp

The SimpleSAMLphp extension extends the PluggableAuth extension to provide authentication using SimpleSAMLphp. It is primarily designed to support SP-initiated authentication flows with just-in-time provisioning of user accounts.

• Download and move the extracted SimpleSAMLphp folder to your extensions/ directory.
  Developers and code contributors should install the extension from Git instead, using:

  cdextensions/
  gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/SimpleSAMLphp
  

• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'SimpleSAMLphp' );
  

• Install and configure SimpleSAMLphp
  • Note that you will likely need to change the session store type in SimpleSAMLphp to something other than phpsession (see #Known bugs)
• Configure as required
• Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Values must be provided for the following mandatory configuration variables:

In addition, the following optional configuration variables are provided:

Add the plugin to $wgPluggableAuth_Config:

$wgPluggableAuth_Config['Log in using my SAML'] = [
	'plugin' => 'SimpleSAMLphp',
	'data' => [
		'authSourceId' => 'default-sp',
		'usernameAttribute' => 'username',
		'realNameAttribute' => 'name',
		'emailAttribute' => 'email'
	]
];

callback(
 \User $user,
 array $attributes,
 \Config $config,
 SimpleSAML\Auth\Simple $saml )
: MediaWiki\Extension\SimpleSAMLphp\IAttributeProcessor

By default, usernames are lowercased. The original case can be kept by setting:

$wgPluggableAuth_Config['Log in using my SAML'] = [
	'plugin' => 'SimpleSAMLphp',
	'data' => [
		// ...
		'userinfoProviders' => [
			'username' => 'rawusername'
		]
	]
];

If you want to modify any of the fields username, realname or email before login, for instance, if your SAML source does not provide an explicit username attribute and you want to use the email address without the domain for the username, you can configure a custom callback for $wgSimpleSAMLphp_MandatoryUserInfoProviderFactories. To create the object a valid ObjectFactory specification must be configured.

For simple usecases one can use MediaWiki\Extension\SimpleSAMLphp\UserInfoProvider\GenericCallback, assuming your email attribute is called mail (if it's called something else, change the two instances of $attributes['mail'] to $attributes['YourEmailAttributeName']):

$wgSimpleSAMLphp_MandatoryUserInfoProviders['myusername'] = [
	'factory' => function() {
		return new \MediaWiki\Extension\SimpleSAMLphp\UserInfoProvider\GenericCallback( function( $attributes ) {
			$mailAttribute = 'mail';
			if ( !isset( $attributes[$mailAttribute] ) ) {
				throw new Exception( 'missing email address' );
			}
			$parts = explode( '@', $attributes[$mailAttribute][0] );
			return strtolower( $parts[0] );
		} );
	}
];

Make sure to also set myusername in the userinfoProviders of the data field:

$wgPluggableAuth_Config['Log in using my SAML'] = [
	'plugin' => 'SimpleSAMLphp',
	'data' => [
		// ...
		'userinfoProviders' => [
			'username' => 'myusername'
		]
	]
];

The SimpleSAMLphp extension does not by default support concatenating multiple attributes to create a username. Below is an example of a custom provider that uses the given name and surname attributes. This is suitable for Microsoft Entra ID use cases, but can easily be adapted to other cases by changing the given name and surname attributes.

$wgSimpleSAMLphp_MandatoryUserInfoProviders['myusername'] = [
	'factory' => function() {
		return new \MediaWiki\Extension\SimpleSAMLphp\UserInfoProvider\GenericCallback( function( $attributes ) {
			$givenNameAttribute = 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname';
			$surnameAttribute = 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname';
			if ( empty( $attributes[$givenNameAttribute] ) || empty( $attributes[$surnameAttribute] ) ) {
				throw new Exception( 'Missing given name and/or surname attributes in SAML assertion.' );
			}
			return $attributes[$givenNameAttribute][0] . ' ' . $attributes[$surnameAttribute][0];
		} );
	}
];
$wgPluggableAuth_Config['Log in using my SAML'] = [
	'plugin' => 'SimpleSAMLphp',
	'data' => [
		// ...
		'userinfoProviders' => [
			'username' => 'myusername'
		]
	]
];

Besides the default "MapGroups" for group synchronization, one can use "SyncAllGroups", which takes all groups from the SAML response and assign the user to them.

To do so, add the following to the LocalSettings.php:

$wgSimpleSAMLphp_AttributeProcessorFactories = [
	"MediaWiki\\Extension\\SimpleSAMLphp\\AttributeProcessor\\SyncAllGroups::factory"
];

If the IdP returns group names that are not suitable for the wiki, one can set up a callback to modify the group names. E.g. some IdP-Setups may return LDAP-DNs like "CN=Admin,OU=Groups,DC=SomeDomain". One could then specify in LocalSettings.php:

$wgSimpleSAMLphp_SyncAllGroups_GroupNameModificationCallback = function ( $origGroupName ) {
 return preg_replace( '#^CN=(.*?),OU=.*$#', '1ドル', $origGroupName );
};

The "attribute processors" can also be used to handle arbitrary data from the SAML response. In this case one must first create a new PHP class that implements the MediaWiki\Extension\SimpleSAMLphp\IAttributeProcessor interface. For convenience the base class MediaWiki\Extension\SimpleSAMLphp\AttributeProcessor\Base can be used, which has a proper factory callback and constructor implemented. An example

use MediaWiki\Extension\SimpleSAMLphp\AttributeProcessor\Base;
class SyncLanguage extends Base {
 public function run() {
 //Set gender on $this->user from a value in $this->attributes
 }
}

It then needs to be instantiated by using the $wgSimpleSAMLphp_AttributeProcessors.

Version 7.0.1 (6 February 2024)

• Fixed group sync on initial user creation
• Dropped support for MW < 1.39

Version 7.0.0 (12 June 2023)

• Made compatible with PluggableAuth 7.0.0
• Use new PluggableAuth group population framework; supports retrieval of attributes including groups
• Code improvements
• Bug fixes:
  • T305031: Error when logging out via API

Version 5.0.1 (21 October 2022)

• Fix group sync

Version 5.0.0 (27 July 2022)

• Stable release

Version 5.0.0-beta (29 March 2022)

• Add compatibility to PluggableAuth version 6

Version 4.5.2 (12 April 2020)

• fixed bug: Groups are not removed in MW if the attribute is not existing (T246351)

Version 4.5.1 (26 October 2019)

• fixed warning: $wgSimpleSAMLphp_GroupMap is not an array
• improved loading UserInfo and Groups
• improved tests

Version 4.5 (28 February 2019)

• added support for custom user info providers
• updated to manifest version 2

Version 4.4 (20 November 2018)

• Fixed signature of populateGroups() function to match PluggableAuthPopulateGroups hook

Version 4.3 (24 October 2018)

• Added support for attribute processors
• Fixed bug in SAML attribute processing
• Added PSR-4 compatible namespace
• Dropped support for MW < 1.31

Version 4.2 (21 April 2018)

• Broke out username, real name, and email functions so they could be overridden in a subclass to allow custom rules
• Coding style and directories
• Improved debugging

Version 4.1 (11 July 2017)

• Implements PluggableAuthPopulateGroups hook to populate MediaWiki groups from SAML attributes. Thank you to Poikilotherm for contributing this functionality.

Version 4.0 (19 April 2017)

• Added optional error message to authenticate()
• Bumped version number to synchronize with PluggableAuth and OpenID Connect extensions

SSO can be difficult to configure correctly, especially for first-time sysadmins tasked with connecting their new MediaWiki instance to the company's IdP. The PluggableAuth and SimpleSAMLphp extensions themselves are quite stable, so most issues are usually associated with configuration.

To start debugging, set $wgDebugLogFile to a filepath on your local system. You do not need to set $wgShowExceptionDetails to true; in fact, you probably shouldn't, due to security concerns.

Visit your wiki, and try logging in with PluggableAuth. Once you have encountered your error, visit the debug file and look for lines that start with [PluggableAuth] and [SimpleSAMLphp].

If there was an issue with authentication, the debug log will say [PluggableAuth] Authentication failed somewhere.

The SimpleSAMLphp extension works like this:

1. User clicks on SSO login button on wiki.
2. User is taken to Special:PluggableAuthLogin. It detects the wiki is using Extension:SimpleSAMLphp. SimpleSAMLphp (the software, not the extension) detects no login session has been set yet.
3. Special:PluggableAuthLogin calls Extension:SimpleSAMLphp's authenticate() function, which calls SimpleSAMLphp's API to begin the authentication process.
4. SimpleSAMLphp redirects user to the IdP's login page.
5. After user successfully authenticates with IdP, it generates an assertion and redirects to your local SimpleSAMLphp instance's ACS (assertion consumer service) URL, which then redirects to the wiki's Special:PluggableAuthLogin.
6. Special:PluggableAuthLogin now recognizes the session cookie and handles logging the user in.

If you are encountering a login redirect loop, the authentication process will never have a chance to log either an error or success message. This indicates that the call to SimpleSAMLphp's requireAuth() method never finishes, which means SimpleSAMLphp is trying to start the auth process all over again. This is usually because it is not detecting the login session despite it being set. Make sure you are not making common mistakes, such as leaving store.type in your SimpleSAMLphp configuration as phpsession instead of changing it to another method, or putting your SimpleSAMLphp instance on a different domain than your wiki without a proper proxy. (For instance, if your SimpleSAMLphp instance is at the canonical domain saml.mywiki-sso.com but your wiki is located at my.wiki, the session will never be stored on my.wiki and Special:PluggableAuthLogin will redirect back to the IdP instead of logging the user in, creating a login loop.)

If you are encountering an error message on Special:PluggableAuthLogin after a successful redirect from the IdP, there is probably a PluggableAuth/SimpleSAMLphp misconfiguration in your LocalSettings.php. Check to see if you properly configured your attributes. The attributes may sometimes need to be URLs (such as if you are using Azure Active Directory).

Problems have been observed when SimpleSAMLphp is configured to use phpsession for store.type. This may be due to phab:T147161. To fix this, use a different store type in the configuration of the SimpleSAMLphp software by adjusting simplesamlphp/config/config.php (see https://simplesamlphp.org/docs/stable/simplesamlphp-maintenance#section_2_3). For example, for SQLite, use:

'store.type' => 'sql',
'store.sql.dsn' => 'sqlite:/path/where/the/apache/user/can/write/sqlitedatabase.sq3',

For MySQL, use:

'store.type' => 'sql',
'store.sql.dsn' => 'mysql:host=xxx;port=xxx;dbname=xxx',
'store.sql.username' => 'xxx',
'store.sql.password' => 'xxx',

\Hooks::register(
	'SkinTemplateNavigation::Universal',
	function( \SkinTemplate $sktemplate, array &$links ) {
		if ( !isset( $links['user-menu']['logout'] ) ) {
			return;
		}
		$links['user-menu']['custom-logout'] = $links['user-menu']['logout'];
		unset ( $links['user-menu']['logout'] );
	}
);

to the LocalSettings.php file.

• System RockyLinux8/RHEL8
• SimpleSAMLphp (ServiceProvider / library) v2.2.1
• MediaWiki v1.39.7
• Extension:PluggableAuth v7.0.0
• Extension:SimpleSAMLphp v7.0.0

// Load and Configure PluggableAuth for SAML IDP/SSO
wfLoadExtension( "PluggableAuth" );
$wgPluggableAuth_EnableAutoLogin = true;
$wgPluggableAuth_EnableLocalLogin = false;
$wgPluggableAuth_EnableLocalProperties = false;
$wgGroupPermissions['*']['autocreateaccount'] = true;
// Load and Configure SimpleSAMLphp for SAML IDP/SSO
wfLoadExtension( "SimpleSAMLphp" );
$wgSimpleSAMLphp_InstallDir = '/opt/simplesamlphp';
// SAML AuthENTICATION (Tell Mediawiki "WHO" the user "IS")
$wgPluggableAuth_Config['Log in using SAML'] = [
 'plugin' => 'SimpleSAMLphp',
 'data' => [ 
'yourIDPauthSourceId' => 'default-sp',
'NameOfYourIDPusernameAttribute' => 'ValueOfYourIDPusernameAttribute',
'NameOfYourIDPrealNameAttribute' => 'ValueOfYourIDPrealNameAttribute',
'NameOfYourIDPemailAttribute' => 'ValueOfYourIDPemailAttribute'
 ]
];
// SAML AuthORIZATION (Tell Mediawiki "WHAT" roles the user "HAS")
$wgPluggableAuth_Config['Log in using SAML'] += [
 'groupsyncs' => [ [ 'type' => 'mapped',
 'map' => [ 
'sysop' => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansSysop' ],
'bureaucrat' => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansBureaucrat' ],
'interface-admin' => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansInterfaceAdmin' ],
'Contributor' => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansContributor' ],
'Viewer' => [ 'NameOfYourIDPMemberOfAttribute' => 'ValueInIDPMemberOfAttributeValuesThatMeansViewer' ],
 ]
 ] ]
];

• PluggableAuth plugins
• Stable extensions
• User identity extensions
• MIT licensed extensions
• Extensions in Wikimedia version control
• All extensions
• Extensions included in BlueSpice
• Extensions included in semantic::core
• Extensions included in WikiForge
• Extensions by MITRE

• Extensions without an image
• Extensions with master compatibility policy
• Extensions with manual MediaWiki version