Jump to content

Extension:Shibboleth

From mediawiki.org
This extension requires the PluggableAuth extension to be installed first.
MediaWiki extensions manual
Shibboleth
Release status: stable
Implementation User identity
Description Uses the PluggableAuth extension to provide authentication using Shibboleth.
Author(s)
Latest version 2.0.0 (2024-10-14)
MediaWiki 1.39+
PHP 7.1+
License MIT License
Download
README
  • $wgShibboleth_Username
  • $wgShibboleth_Email
  • $wgShibboleth_DisplayName
  • $wgShibboleth_DisplayNameFormatString
  • $wgShibboleth_GroupMap
  • $wgShibboleth_GroupMap_attr_may_be_empty
  • $wgShibboleth_Logout_Base_Url
  • $wgShibboleth_Logout_Target_Url
Quarterly downloads 5 (Ranked 128th)

The Shibboleth extension uses the PluggableAuth extension to provide authentication using Shibboleth Apache module.

Installation

[edit]
This extension requires the PluggableAuth extension and Shibboleth Apache module to be installed first.
  • Download and place the file(s) in a directory called Shibboleth in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:

wfLoadExtension( 'Shibboleth' );

  • Configure as required
  • Done! Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configure

[edit]

Values must be provided for the following mandatory configuration variables:

Flag Default Description
$wgShibboleth_Username eppn The name of the attribute to be used for the user's username.
$wgShibboleth_Email mail The name of the attribute to be used for the user's email address.
$wgShibboleth_DisplayName displayName The name of the attribute to be used for the user's real name.
$wgShibboleth_Logout_Base_Url no default value Single Logout (SLO) base URL
$wgShibboleth_Logout_Target_Url no default value Single Logout (SLO) target URL

In addition, the following optional configuration variable is provided:

Flag Default Description
$wgShibboleth_GroupMap null Mapping from SAML attributes to MediaWiki groups, see example below. No group mapping is performed if $wgShibboleth_GroupMap is null.
$wgShibboleth_GroupMap_attr_may_be_empty false Allow empty group mapping attribute. Is you use an entitlement for group mapping this is needed to enable people without any entitlement to login.
$wgShibboleth_DisplayNameFormatString null Allows a custom format string which creates the display name (see vsprintf())

Display name

[edit]

You can either use a single SAML attribute as display name or multiple attributes:

$wgShibboleth_DisplayName = 'displayName';
$wgShibboleth_DisplayName = ['givenName', 'sn'];

If you define multiple attributes their values are concatenated with spaces. If you still want more you can use a user defined format string:

$wgShibboleth_DisplayName = ["displayName", "mail"];
$wgShibboleth_DisplayNameFormatString = "%s <%s>";

This results in

Christopher Odenbach <odenbach@uni-paderborn.de>

Group mapping

[edit]
The syntax of the group mapping variable has changed completely from the previous version v1.0. If you want to upgrade you will have to redefine your group mapping. The newer form is much more powerful.

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.
  • For some reason you may also want to grant sysop rights to someone with a special pairwise-id but who is not in the administrator group.
  • Create a group map in your LocalSettings.php as follows:
  $wgShibboleth_GroupMap = [
     'groups' => [
         'administrator' => 'sysop',
     ],
     'pairwise-id' => [
         'OTCROY5S7ZWGWYD6Z7EAXRXMA44YMW5S@uni-paderborn.de' => 'sysop',
     ],
 ];

So the variable contains a list of SAML attributes ('groups' and 'pairwise-id' here). Each of the attributes points to a list of key-value pairs where the key is a string or a regular expression of the attribute's value, and the value contains the mediawiki group which should be assigned if the attribute contains the string or regex.

If you want to use a regex, just enclose it in slashes, e.g.

$wgShibboleth_GroupMap = [
        'entitlement' => [
                '/urn:geant:dfn.de:idm.nrw:[^:]+:role:rid=10000001-9:rname=DaSi_Expert/' => 'sysop',
        ],
        'pairwise-id' => [
                'GVKE7A3O4XXCDMKAA4XES5Z7SRMDBDNG@uni-paderborn.de' => 'sysop',
                'gxzcf8mttg6jsd0mprx28l8kmjox489ltgfatn0hjaooqnxn5bgdtot5zpz6uzzv@rwth-aachen.de' => 'sysop',
        ],
];

In this example every person with an entitlement from any university with the role DaSi_Expert gets the sysop role, and also two other explicit people.

You can come up with rather complex mappings that fit your needs.

Hint: 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.

Single Logout (SLO)

[edit]

Shibboleth Single Logout (SLO) URL structure:

$wgShibboleth_Logout_Base_Url . Shibboleth.sso/Logout?return= . $wgShibboleth_Logout_Target_Url
https://wiki.example.org/Shibboleth.sso/Logout?return=https://wiki.example.org/index.php

See also

[edit]