https://github.com/jornane/mwsimplesamlauth
A Mediawiki plugin allowing SAML authentication through simpleSamlPhp
https://github.com/jornane/mwsimplesamlauth
Last synced: 2 months ago
JSON representation
A Mediawiki plugin allowing SAML authentication through simpleSamlPhp
- Host: GitHub
- URL: https://github.com/jornane/mwsimplesamlauth
- Owner: jornane
- License: lgpl-3.0
- Created: 2014-01-23T20:23:40.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2018-03-13T04:17:52.000Z (over 7 years ago)
- Last Synced: 2025-03-27T23:51:11.656Z (3 months ago)
- Language: PHP
- Homepage: https://www.mediawiki.org/wiki/Extension:SimpleSamlAuth
- Size: 117 KB
- Stars: 10
- Watchers: 5
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
README
# SAML plugin for MediaWiki
## Glossary
* **SimpleSamlAuth** This extension, uses *SimpleSAMLphp* to allow SAML login in *MediaWiki*.
* **SimpleSAMLphp** Open source lightweight SAML implementation by UNINETT.
* **MediaWiki** Open source Wiki software.
## Requirements
* [SimpleSAMLphp](https://simplesamlphp.org) (tested on 1.15 and newer)
* [MediaWiki](https://www.mediawiki.org) (tested on 1.15, 1.16 or newer required for some features)
**IMPORTANT** If you run MediaWiki 1.27 or newer, SimpleSAMLphp **MUST** be configured to use an alternative session handler.
If this is not done, SAML authentication succeeds, but MediaWiki still shows that nobody is logged in.
Please refer to [the SimpleSAMLphp website](https://simplesamlphp.org/docs/stable/simplesamlphp-maintenance) on how to configure SimpleSAMLphp for session storage.
## Preparation
* Install SimpleSAMLphp on the same domain as your MediaWiki installation.
* In SimpleSAMLphp, use the *Authentication* -> *Test configured authentication sources* feature to ensure that authentication works.
Also make sure that the attributes make sense.
You may keep the attributes page open for later reference,
for filling out `$wgSamlUsernameAttr`, `$wgSamlRealnameAttr` and `$wgSamlMailAttr`.
If you encounter problems during the preparation, please [look here](https://simplesamlphp.org/support) for support.
*Only* report bugs for SimpleSamlAuth if the **preparation steps** work for you.
## Installation
* Clone this repository into your MediaWikis *extensions* directory, and call it **SimpleSamlAuth**.
```bash
git clone [email protected]:jornane/mwSimpleSamlAuth.git SimpleSamlAuth
```
* Add the following lines to **LocalSettings.php** in your MediaWiki installation:
```php
require_once "$IP/extensions/SimpleSamlAuth/SimpleSamlAuth.php";
// SAML_OPTIONAL // SAML_LOGIN_ONLY // SAML_REQUIRED //
$wgSamlRequirement = SAML_OPTIONAL;
// Should users be created if they don't exist in the database yet?
$wgSamlCreateUser = false;
// SAML attributes
$wgSamlUsernameAttr = 'uid';
$wgSamlRealnameAttr = 'cn';
$wgSamlMailAttr = 'mail';
// SimpleSAMLphp settings
$wgSamlSspRoot = '/usr/share/simplesamlphp';
$wgSamlAuthSource = 'default-sp';
$wgSamlPostLogoutRedirect = NULL;
// Array: [MediaWiki group][SAML attribute name][SAML expected value]
// If the SAML assertion matches, the user is added to the MediaWiki group
$wgSamlGroupMap = array(
'sysop' => array(
'groups' => array('admin'),
),
);
```
## Configuration
Modify the variables starting with *$wgSaml* to configure the extension.
Some important variables:
### $wgSamlRequirement
This variable tells the extension how MediaWiki should behave.
There are three options; `SAML_OPTIONAL` `SAML_LOGIN_ONLY` `SAML_REQUIRED`:
| | optional | loginonly | required |
|-----------------------------------:|:--------:|:---------:|:--------:|
| Allow login through SAML | ✓ | ✓ | ✓ |
| Update user's real name and e-mail | ✓ | ✓ | ✓ |
| Prevent creation of local accounts | | ✓ | ✓ |
| Prevent login with local account | | ✓ | ✓ |
| Prevent anonymous browsing | | | ✓ |
| Redirect to login immediatly | | | ✓ |
You can still use the [MediaWiki methods for preventing access](http://www.mediawiki.org/wiki/Manual:Preventing_access) to block certain actions, even if SimpleSamlAuth won't block them. The only exception is that `$wgSamlCreateUser = true` will have priority over `$wgGroupPermissions['*']['createaccount'] = false`.
### $wgSamlAuthSource
This is the name of the AuthSource you configured in SimpleSAMLphp.
You can easily find it by going to the SimpleSAMLphp installation page and going to *Authentication* -> *Test configured authentication sources*.
The word you have to click there is the name of your AuthSource.
For SAML sessions, the standard preconfigured name in SimpleSAMLphp is `default-sp` and this is also what SimpleSamlAuth will guess if you omit the variable.
### $wgSamlPostLogoutRedirect
This is an URL where users are redirected when they log out from the MediaWiki installation.
Generally, for a `SAML_REQUIRED` setup you want to set this to a landing page (intranet, for example).
For any other setup, you may not want to set this, so users can continue browsing the Wiki anonymously after logging out.
### $wgSamlGroupMap
This is a list of rules used to add users to MediaWiki groups based on their SAML attributes.
It is an array of three layers deep:
* Name of the MediaWiki group (for example `sysop`)
* Name of a SAML attribute (for example `groups`)
* Possible value for the SAML attribute (for example `admin`)
```php
$wgSamlGroupMap = array(
'sysop' => array(
'groups' => array('admin'),
),
);
```
An array as illustrated here will add users to the `sysop` MediaWiki group, if they have a SAML attribute named `groups` with at least a value `admin`.
If you want more fine-grained control, look at the [SimpleSAMLphp role module](https://github.com/jornane/sspmod_role).
### [$wgSessionName](https://www.mediawiki.org/wiki/Manual:$wgSessionName)
The name of the cookie containing the session ID. When using PHP's built-in session management in both PHP and SimpleSAMLphp, this *must* match the session name used by PHP. It should not be necessary to set this.
### [$wgWhitelistRead](https://www.mediawiki.org/wiki/Manual:$wgWhitelistRead)
Array of page names that can be read without being redirected to the IdP. This may be useful on sites where SAML login is required, but some pages are publicly readable. Has no effect in the behaviour of this extension unless `$wgSamlRequirement` is `SAML_REQUIRED`.
## Known Issues
### Weird things happen with sessions / I must click Save twice before the page saves
This has to do with the value of `$wgSessionName`. This value must be set to `ini_get('session.name')` if you use PHP sessions in both SimpleSAMLphp and MediaWiki. From version 0.5, SimpleSamlAuth will take care of this automatically.
### SAML users can edit their e-mail address
Extensions can only disable preferences [since MediaWiki 1.16](http://www.mediawiki.org/wiki/Manual:Hooks/GetPreferences).
Ubuntu 12.04 LTS comes with MediaWiki 1.15.
[WikiMedia recommends against using the Ubuntu-provided version of MediaWiki.](http://www.mediawiki.org/wiki/Manual:Running_MediaWiki_on_Ubuntu)
### E-mail addresses are not automatically confirmed
SimpleSamlAuth will *only* confirm e-mail addresses that it has set itself.
Make sure that you have configured `$wgSamlMailAttr` correctly.
### SAML users overwrite MediaWiki users / SAML users can reset their password and become a local user
There is not really a difference between local accounts and remote accounts in MediaWiki.
[There has been an idea to implement this](http://www.mediawiki.org/wiki/ExternalAuth), but it looks like it's dead now.
If SimpleSAMLphp presents a valid session, SimpleSamlAuth simply finds a local MediaWiki user with a username roughly equal to the value of the username attribute; if it doesn't exist, and if `$wgSamlCreateUser` is set, the user is created.
This newly created user will have no password, but will be able to reset their password if a valid e-mail address has been set.
### Other issue?
Please report it on the project's [GitHub issues page](https://github.com/jornane/mwSimpleSamlAuth/issues).