MediaWiki

Extension:SimpleSAMLphp

Translate this page
Languages:
This extension requires the PluggableAuth extension to be installed first.
MediaWiki extensions manual
SimpleSAMLphp
Release status: stable
Implementation User identity
Description Extends the PluggableAuth extension to provide authentication using SimpleSAMLphp.
Author(s) Robert Vogel, Cindy Cicalese
Latest version 7.0.1 (2023-06-12)
Compatibility policy Master maintains backward compatibility.
MediaWiki 1.35+
License MIT License
Download
Download extension
Git [?]:
Parameters
  • $wgSimpleSAMLphp_MandatoryUserInfoProviders
  • $wgSimpleSAMLphp_InstallDir
Quarterly downloads 67 (Ranked 67th)
Translate the SimpleSAMLphp extension if it is available at translatewiki.net
Issues Open tasks · Report a bug

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.

Installation

edit
This extension requires the PluggableAuth extension and SimpleSAMLphp to be installed first.


  • Download and move the extracted SimpleSAMLphp 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/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
  •   Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

edit

Values must be provided for the following mandatory configuration variables:

Flag Default Description
$wgSimpleSAMLphp_InstallDir no default value The path on the local server where SimpleSAMLphp is installed.

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'
	]
];

Fields for data

edit

All versions

edit
Field name Default Description
authSourceId no default value The AuthSourceId to be used for authentication.
usernameAttribute no default value The name of the attribute to be used for the user's username (by default the username is lowercased, see below if it is not desired).
realNameAttribute no default value The name of the attribute(s) to be used for the user's real name. This may be a single attribute name or an array of attribute names. In the latter case, the attribute values will be concatenated with spaces between them to form the value for the user's real name.
emailAttribute no default value The name of the attribute to be used for the user's email address.
userinfoProviders [  'username' => 'username',  'realname' => 'realname',  'email' => 'email']
attributeProcessors [

"...\\MapGroups::factory"

]

This can be used to set up the group synchronization mechanism and to add processing of arbitrary SAML response data. Example see below. The factory callback has the following signature: 
callback(
    \User $user,
    array $attributes,
    \Config $config,
    SimpleSAML\Auth\Simple $saml )
: MediaWiki\Extension\SimpleSAMLphp\IAttributeProcessor

Prior to version 7.0.0

edit

In version 7.0.0, support for group mapping was moved to PluggableAuth with slight changes in syntax. For information on configurating group synchronization in version 7.0.0 and later, see the PluggableAuth documentation.

Field name Default Description
mapGroups_Map [] Mapping from SAML attributes to MediaWiki groups of the form:

'mapGroups_Map' => [ 'mediawiki group' => ['saml attribute' => ['group 1', 'group 2', '...']]]

No group mapping is performed if $mapGroups_Map is null.

syncAllGroups_GroupAttributeName "groups" If configured to use "SyncAllGroups", this SAML attribute will be read out
syncAllGroups_GroupNameModificationCallback null If configured to use "SyncAllGroups", this can be used to change/normalize the groups coming from the IdP. Example see below.
syncAllGroups_LocallyManaged [ "sysop" ] If configured to use "SyncAllGroups", these local user groups will not be influenced by what is set in the SAML response
groupAttributeDelimiter null If the IdP returns the list of groups in a single string (e.g. "saml attribute" => [ "group 1,group 2,group 3" ] instead of "saml attribute" => [ "group 1", "group 2", "group 3" ]) this value can be set to split up the string. Be aware that in this case only the first element of the SAML attribute value is being evaluated. This setting applies to both group synchronization mechanisms "MapGroups" and "SyncAllGroups"

Do not lowercase usernames

edit

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'
		]
	]
];

Define custom user info provider

edit

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'
		]
	]
];

Username using real name

edit

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'
		]
	]
];

Group mapping (Prior to version 7.0.0)

edit

In version 7.0.0, support for group mapping was moved to PluggableAuth with slight changes in syntax. For information on configurating group synchronization in version 7.0.0 and later, see the PluggableAuth documentation.

Use case: your SAML IdP reads groups from LDAP or Database and stores this information inside an attribute of the SAML response. You want to use this to map MediaWiki groups to users belonging to some known groups given by your IdP.

Example:

  • Your IdP sends an attribute named "groups" with a list of names like "administrator", "student", "teacher", ... in the SAML response after authentication.
  • All users that have the value "administrator" in the "groups" attribute shall be mapped to the MediaWiki "sysop" group to give them admin rights within your MediaWiki instance.
  • Create a group map in your LocalSettings.php as follows: $wgSimpleSAMLphp_GroupMap = ['sysop' => ['groups' => ['administrator']]];

You can come up with rather complex mappings that fit your needs. If you have more than one attribute from SAML, just add it to the array with the array of values you like to map.

If a MediaWiki group does not exist, it will be created "on the fly" on first successful mapping of a user.

If a user belongs to a MediaWiki group that is no longer mapped to that user (for example, by losing the group membership in the SAML user data source), the user will be removed from that MediaWiki group at next log in. In that way you can mass remove groups from SAML and their memberships, too - just scramble the mapping values so they don't match the SAML response, but don't mess up the MediaWiki group name.

Group mapping #2

edit

Since version 4.3 one can also configure an alternative group synchronization mechanism. Besides the default "MapGroups" 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 );
};

Processing arbitrary data from the SAML response

edit

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.

Before 5.0, this used to be $wgSimpleSAMLphp_AttributeProcessorFactories.

Compatibility

edit
Tested configurations
MediaWiki Core Extension:PluggableAuth Extension:SimpleSAMLphp SimpleSAMLphp (ServiceProvider / library) Notes
1.39.5 7.0 7.0 2.1.1 (minimum PHP version required is PHP 8.0) OK
1.39.3 7.0 7.0 2.0.2 OK
1.39.3 7.0-dev 7.0-dev 1.19.6 OK
1.39.3 6.2 5.0.1 1.18.4 Error
1.39 6.1 5.0 2.0.0-rc1 OK
1.39 6.1 5.0 1.19.6 OK
1.39 6.1 5.0 1.18.8 OK
1.35 5 4.0 1.18.8 OK


Release notes

edit
Version 7.0.0
  • 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
  • Fix group sync
Version 5.0.0
  • Stable release
Version 5.0.0-beta
Version 4.5.2
  • fixed bug: Groups are not removed in MW if the attribute is not existing (T246351)
Version 4.5.1
  • fixed warning: $wgSimpleSAMLphp_GroupMap is not an array
  • improved loading UserInfo and Groups
  • improved tests
Version 4.5
  • added support for custom user info providers
  • updated to manifest version 2
Version 4.4
Version 4.3
  • 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
  • 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
  • Implements PluggableAuthPopulateGroups hook to populate MediaWiki groups from SAML attributes. Thank you to Poikilotherm for contributing this functionality.
Version 4.0
  • Added optional error message to authenticate()
  • Bumped version number to synchronize with PluggableAuth and OpenID Connect extensions

Debugging

edit

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

Known bugs

edit

Session handler collision between MediaWiki and SimpleSAML Service Provider

edit

If you are using MediaWiki 1.27 or later with PluggableAuth 2.0 or later, 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',

Logout error message

edit
 

Since MediaWiki 1.35 by default (Skin "Vector") the logout is no longer performed by calling "Special:UserLogout", but by an XHR POST request. This is not compatible to how SAML works and will result in an error message prior to version 7.0.0 of this extension (see screenshot).

See also task T305031

As a workaround in versions prior to 7.0.0, one can change the "Logout" link to point to "Special:Logout" again by adding 

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

Full Examples of Authentication and Authorization

edit

Example for MW 1.35

edit
  • System RockyLinux8/RHEL8
  • MediaWiki 1.35.11
  • PluggableAuth 6.3
  • SimpleSAMLphp 5.0.1
// 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']['data'] += [ 'mapGroups_Map'  => [

     'sysop'           => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansSysop'          ]],
     'bureaucrat'      => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansBureaucrat'     ]],
     'interface-admin' => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansInterfaceAdmin' ]],
     'Viewer'          => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansViewer'         ]],
     'Contributor'     => ['SAMLresponseMemberOfAttributeName' => [ 'StringFoundInYourSAMLresponseRoleAttributeValuesThatMeansContributor'    ]]

]];

Example for MW 1.39

edit
  • 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'         ],
                                    ]
                     ] ]
];
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:SimpleSAMLphp&oldid=6760848"