Extension:Shibboleth Authentication

From mediawiki.org
MediaWiki extensions manual
Shibboleth Authentication
Release status: unmaintained
Implementation User identity
Description Allows integration of mediawiki with the Shibboleth Single Sign-on project from Internet2.
Author(s) D.J. Capelis, Steven Langenaken, Andrea Biancini
Latest version 1.2.7 (2016-04-11)
MediaWiki 1.7+
License GPL
Download

Overview[edit]

Shibboleth is a Single Sign On identity management solution that's a project of Internet2. It's in use not only in many universities through the US and elsewhere but also on sites such as openidp to provide authentication to a range of applications. This extension allows MediaWiki to use Shibboleth as an external authentication source.

Current Version: 1.2.7

Installation Instructions[edit]

Compatibility[edit]

This extension is designed for MediaWiki 1.7 and up (latest version tested is 1.26.2), for newer MediaWiki version please have a look on the GitHub page. If you want to use this extension with the 1.6 branch or earlier look at bugs 5819 and 6006 and apply the SVN changes that took place.

Shibboleth Configuration[edit]

The extension requires that Shibboleth Service Provider (tested on v2.5.2) be configured and set up on the web server the wiki is hosted on. Once Shibboleth SP is running on the web server make sure your configuration file is correctly set-up. Your IdP should be able to help you with this. The extension uses lazy sessions and a WAYF URL so you'll want to verify these are setup as well. (You can actually use full sessions if you want, but the extension is designed to use lazy sessions to allow for the standard wiki auth to co-exist alongside.) You'll need to tell the extension which EDS(Shibboleth Embedded Discovery Service) url to use.

The part of the configuration file (shibboleth2.xml) where a EDS URL will be present is here:

...
<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
          checkAddress="true" handlerSSL="false" idpHistory="true" idpHistoryDays="7">

     <SSO discoveryProtocol="SAMLDS" discoveryURL="https://wiki.example.org/shibboleth-ds/index.html" isDefault="true">
          SAML2
     </SSO>

     <!-- SAML2 and local-only logout. -->
     <Logout>SAML2 Local</Logout>
...

The part of the configuration file (not present by default on 2.5 Shib SP) that allows lazy sessions is here: (False is for lazy sessions, true for mandatory sessions.)

<Sessions>
...
<RequestMap applicationId="default">
     <Host name="host.example.org">
          <Path name="wikipath" authType="shibboleth" requireSession="false"/>
     </Host>
</RequestMap>

For lazy sessions in Apache, the following lines in your Apache configuration files will do:

...
<Location /pathname>
        AuthType shibboleth
        Require shibboleth
</Location>

If you don't want lazy sessions but instead would rather require shibboleth authentication, then use:

  • Apache2 < 2.4
...
<Location /pathname>
        AuthType shibboleth
        ShibRequireSession On
        Require valid-user
</Location>
  • Apache2 >= 2.4
...
<Location /pathname>
        AuthType shibboleth
        ShibRequestSetting requireSession true
        Require valid-user
</Location>

Download the Extension[edit]

The code for the extension is on GitHub: https://github.com/ConsortiumGARR/mediawiki-shibboleth-authentication. To install the extension clone the GitHub repo in the extension folder.

Extension Configuration[edit]

Now it's time to configure and load the extension. To do that, just add the following lines to LocalSettings.php in the root of the MediaWiki directory.

Most of the configuration directives are of the form:

$shib_SOMELETTERS = data_manipulation_functions($_SERVER['HEADER_FOR_SHIB_DATA']);

This allows you to map whatever shibboleth identifiers you chose to a variety of fields for each user as well as use the standard PHP functions to massage the data as it enters. All the Shibboleth data has been placed in the $_SERVER superglobal by the Shibboleth module and should be available. You may need to run a script like the following to determine exactly what data is available:

<?php
//Drop this into a directory where sessions are required
//or where you are already authenticated and then simply
//access it to see the mapping.
while(list($index, $data) = each($_SERVER))
{
	echo "$index -> $data<br><br>";
}
?>

At the very minimum you'll need to make the following changes:

  1. Place the following code into the LocalSettings.php file.
  2. Set the WAYF URL.
  3. Map a valid piece of Shib data for the username.
  4. If one attribute of the Shib session contains groups the user belongs to, map this attribute to the shib_groups variable.
  5. Look over the rest of the variables and ensure that you don't want to make any more changes.
## Shibboleth Authentication Stuff
## Load ShibAuthPlugin
require_once('extensions/ShibAuthPlugin.php');

## Last portion of the shibboleth WAYF url for lazy sessions.
## This value is found in your shibboleth.xml file on the setup for your SP
## WAYF url will look something like: /Shibboleth.sso/WAYF/$shib_WAYF
$shib_WAYF = "Login";

##Are you using an old style WAYF (Shib 1.3) or new style Discover Service (Shib 2.x)?
##Values are WAYF or DS, defaults to WAYF
$shib_WAYFStyle = "Login";

## Is the assertion consumer service located at an https address (highly recommended)
## Default for compatibility with previous version: false
$shib_Https = true;

## Prompt for user to login
$shib_LoginHint = "Login via Single Sign-on";

## Where is the assertion consumer service located on the website?
## Default: "/Shibboleth.sso"
$shib_AssertionConsumerServiceURL = "";

## Map Real Name to what Shibboleth variable(s)?
# $shib_RN = ucfirst(strtolower($_SERVER['HTTP_FIRST_NAME'])) . ' '
#	 . ucfirst(strtolower($_SERVER['HTTP_LAST_NAME']));
if (array_key_exists("cn", $_SERVER)) {
   $shib_RN = $_SERVER['cn'];
} else if (array_key_exists("givenName", $_SERVER) && array_key_exists("sn", $_SERVER)) {
   $shib_RN = ucfirst(strtolower($_SERVER['givenName'])) . ' '
            . ucfirst(strtolower($_SERVER['sn']));
}

## Map e-mail to what Shibboleth variable?
# $shib_email = $_SERVER['HTTP_EMAIL'];
$shib_email = isset($_SERVER['mail']) ?  $_SERVER['mail'] : null;

## Field containing groups for the user and field containing the prefix to be searched (and stripped) from wiki groups
# $shib_groups = $_SERVER['isMemberOf'];
# $shib_group_prefix = "wiki";
$shib_groups = isset($_SERVER['isMemberOf']) ? $_SERVER['isMemberOf'] : null;
$shib_group_prefix = "wiki";

# Should pre-existing groups be deleted?
# If groups are fetched only from Shibboleth it should be true
# if memberships are granted from mediawiki User rights management
# page, it should be false
# PLEASE NOTE: with $shib_group_delete = false, in order to revoke
# a membership it should be deleted both from Shibboleth and
# User rights management page!
#$shib_group_delete = false;

# The ShibUpdateUser hook is executed on login.
# It has two arguments:
# - $existing: True if this is an existing user, false if it is a new user being added
# - &$user: A reference to the user object.
#           $user->updateUser() is called after the function finishes.
# In the event handler you can change the user object, for instance set the email address or the real name
# The example function shown here should match behavior from previous versions of the extension:

$wgHooks['ShibUpdateUser'][] = 'ShibUpdateTheUser';

function ShibUpdateTheUser($existing, &$user) {
        global $shib_email;
        global $shib_RN;
        if (! $existing) {
                if($shib_email != null)
                        echo "SHIB_EMAIL: ".$shib_email;
                        $user->setEmail($shib_email);
                if($shib_RN != null)
                        $user->setRealName($shib_RN);
        }
        return true;
}

## This is required to map to something
## You should beware of possible namespace collisions, it is best to chose
## something that will not violate MW's usual restrictions on characters
## Map Username to what Shibboleth variable?
#$shib_UN = strtolower($_SERVER['HTTP_EMAIL']);
$shib_UN = isset($_SERVER['eppn']) ? ucfirst(strtolower($_SERVER['eppn'])) : null;

# hide "IP login" and default login link
$wgShowIPinHeader = false;
function NoLoginLinkOnMainPage( &$personal_urls ){
    unset( $personal_urls['login'] );
    unset( $personal_urls['anonlogin'] );
    return true;
}
$wgHooks['PersonalUrls'][]='NoLoginLinkOnMainPage';

# to disable factory user login
function disableUserLoginSpecialPage(&$list) {
        unset($list['Userlogin']);
        return true;
}
$wgHooks['SpecialPage_initList'][]='disableUserLoginSpecialPage';

# Shibboleth doesn't really support logging out very well.  To take care of
# this we simply get rid of the logout link when a user is logged in through
# Shib.  Alternatively, you can uncomment and set the variable below to a link
# that will either clear the user's cookies or log the user out of the Idp and
# instead of deleting the logout link, the extension will change it instead.
$shib_logout = "/Shibboleth.sso/Logout";

# Add to permit the management of the User rights
$wgUserrightsInterwikiDelimiter = '#';

## Activate Shibboleth Plugin
SetupShibAuth();

Using the Extension[edit]

The extension is designed to be fairly simple to use. Once everything is configured and Shibboleth is running a link will appear at the top right hand corner of the screen next to the normal mediawiki login link that says "login via single sign-on." Clicking this link will bounce the user to the WAYF URL which will pass them to the IdP for authentication. When they come back they'll be logged in.

Tips, Tricks and Known Bugs[edit]

Adding more Metadata[edit]

If you wish to add more mappings from MediaWiki data to Shibboleth data than is available, you can simply add them in the configuration file. You just have to add the code changes in the event handler or add an extra event handler (ShibUpdateTheUser in the example).

Logout Functionality[edit]

Shibboleth currently has no good way to log people out. By default logout is disabled once people sign in through Shibboleth. Alternatively you may point logout to a url provided by your local IdP which will allow logout. If your local IdP doesn't support this and you really would like to log people out, simply create a small php script to unset the Shibboleth cookies and point people towards that, then redirect them to the standard MediaWiki logout script.

Username Munging[edit]

While the extension will enforce the rule that all usernames must begin with a capital letter, it will not enforce any of the rest of MediaWiki's usual rules for usernames. If your Shibboleth data will break other MediaWiki username rules you should filter that out at the configuration level when $shib_UN gets set. In addition, if your shibboleth data includes sets of usernames that may only be separated by difference of upper and lower-case initial letters (Like "Nick@example.org" and "nick@example.org") then the plugin will treat these two as if they were not distinct. Again the solution is to provide additional filtering in LocalSettings.php. By default we simply use the user's e-mail addresses converting any letters to lowercase and then pass those in. (Again, the extension takes care of converting the initial letter to uppercase.)

Changelog[edit]

For all new changes go check the GitHub repo:[edit]

https://github.com/ConsortiumGARR/mediawiki-shibboleth-authentication

Differences between 1.2.6 and 1.2.5[edit]

  • Fixed code to use the proper getShibAssertionConsumerServiceURL() function instead of a variable directly

Differences between 1.2.5 and 1.2.4[edit]

  • Implemented the management of the attribute containing user groups (usually isMemberOf) obtained from Shibboleth session.

Differences between 1.2.4 and 1.2.3[edit]

  • updated for MW 1.20

Differences between 1.2.3 and 1.2.2[edit]

  • function ShibAuthAuthenticate was full of typos
  • setup_session error (thanks to Dhess)
  • Support for Shib 2.x (thanks to Barry Johnson, Clemson University)

Differences between 1.2.2 and 1.2.1[edit]

  • Compatibility fix for MW 1.13: Automatic user creation didn't work any more

Differences between 1.2.1 and 1.2.0[edit]

  • Functions renamed so they start with Shib (to prevent naming conflicts)
  • Compatibility fix for MW 1.13: the AutoAuthenticate hook has been replaced by the UserLoadFromSession hook. The extension checks the version and registers the appropriate hook.

Differences between 1.2.0 and 1.1.8[edit]

  • The configuration for this version is not backwards compatible with the previous version if $shib_map_info was set to true (search for ShibUpdateUser on this page).

What's new in this version:

  • $shib_map_info is no longer used, nor are $shib_RN and $shib_email (directly).
  • Mapping information from shibboleth to mediawiki now happens in event handlers for the ShibUpdateUser-hook instead of the updateUser-function itself.
  • A security bug was fixed that caused users to remain logged in even after closing their browser when lazy authentication is used
  • $wgCookieExpiration is made negative so when the user comes back after closing the browser, the homepage doesn't come from the per-user-cache but from the anonymous-user cache.
  • Added extensionCredits to show the plugin on the Special:Version page

Differences between 1.1.8 and 1.1.7[edit]

  • another forgotten Compatibility fix or MW 1.12

Differences between 1.1.7 and 1.1.6[edit]

  • Compatibility fixes for MW 1.12 release: Hooks return true to continue other hook processing

Differences between 1.1.6 and 1.1.5[edit]

  • Compatibility fixes for upcoming MW 1.10.0 release. (They broke the plugin again :-\)
  • Fix error in some versions of php and MW that caused the plugin to fail
  • Fix PHP notice about an undefined variable
  • When $shib_RN is not null and $shib_map_info is set to true the plugin will now display the user's name in their URLs instead of their username. This looks pretty slick, but may need to be more configurable in the future.

Differences between 1.1.5 and 1.1.4[edit]

  • Some of the cleanups in 1.1.4 blocked an untested codepath and prevented the plugin from working

Differences between 1.1.4 and 1.1.3[edit]

  • Security Fix: Namespace collisions are now handled by clobbering the old user
  • Cleanup for setting passwords, more compatible with new changes, less kludgy code as well
  • Fixed longstanding warning caused by a typo in an earlier version of the code (oops)

Differences between 1.1.3 and 1.1.2[edit]

  • Extra error handling plus compatibility fixes for MediaWiki version 1.6.8 (hook patches added)

Differences between 1.1.2 and 1.1.1[edit]

  • Compatibility fixes for 1.9

Differences between 1.1.1 and 1.1[edit]

  • Preserve compatibility with 1.0 configuration files for $shib_LoginHint

Differences between 1.1 and 1.0[edit]

  • Extra configuration options
    • shib_Https (whether the AssertionConsumerService url is at https, default is false)
    • shib_AssertionConsumerServiceURL (defaults to /Shibboleth.sso)
    • Sites that are accessed via https are redirected there after logging in using lazy authentication
  • Login Form Cleanup
  • New Contributor: Steven Langenaken

Acknowledgements[edit]

These folks have helped out by reporting issues and breakages or testing early code releases to help eliminate issues and breakages. Without them this software would have more bugs.

Bug and other-thing Reporters[edit]

  • Martin Kos - Reported breakage in 1.1.4
  • Eric Jiang - Reported breakage in 1.1.1
  • Bajnokk - Reported breakage in 1.2.1
  • Dhess - Provided fix for setup_session error in 1.2.2
  • Barry Johnson - Provided details for shib 2.0

Testers[edit]

  • Joe Pomianek - UCSD