MediaWiki
 Release status: stable | |
|---|---|
| Implementation | User identity, User rights |
| Description | This allows MediaWiki to authenticate against the RestAuth shared authentication service. |
| Author(s) | Mathias Ertl (Mati talk) |
| Version | 0.9 (2011-03-16) |
| MediaWiki | 1.16.3 or later (earlier with patch) |
| License | GPL v3 or any later version. |
| Download | see Download Documentation Changelog |
| Parameters | $wgRestAuthHost, $wgRestAuthService, $wgRestAuthServicePassword, $wgRestAuthRefresh, $wgRestAuthGlobalOptions, $wgRestAuthIgnoredOptions |
| Example | see Example |
| Hooks used |
UserAddGroup |
The RestAuth MediaWiki extension integrates MediaWiki with the RestAuth project. It uses all features of the RestAuth protocol (authentication, authorization and preferences).
Download
The source code of this extension is managed on git.fsinf.at. You can find the repository at RestAuth/MediaWiki. To get the most recent version of this extension, fetch the current HEAD:
git clone https://www.github.com/RestAuth/MediaWiki.git RestAuth
Older versions are marked as tags, you can view available tags with git tag -l and move back to the current HEAD with git checkout <tag-name>. Versions for older versions of MediaWiki, if available, are managed as branches, use git branch and git checkout <branch> to move to a specific branch. To move back to the newest version, use git checkout master.
Note that Gitorious allows you to download older different commits as tarball if you do not want to install git.
Requirements
You need MediaWiki 1.17.0 or newer to run this extension. If you run MediaWiki 1.16.x, please see the notes on the patch.
This extension of course also requires php-restauth, the PHP-library implementing the RestAuth protocol. The library provides separate installation instructions.
Installation & Configuration
After downloading the extension, you need to include RestAuth.php in your LocalSettings.php file and set a few required settings. If you want to export existing data to the RestAuth service first, please see the migrating Wikis section.
require_once( "$IP/extensions/RestAuth/RestAuth.php" );
# RestAuth service details:
$wgRestAuthHost = 'https://auth.example.com';
$wgRestAuthService = 'example.com';
$wgRestAuthServicePassword = 'random-password';
# Needs to be *after* the settings above:
$wgAuth = new RestAuthPlugin();
# Optional Settings:
# How often do you want to update settings from the shared authentication server:
#$wgRestAuthRefresh = 360;
# You can add MediaWiki settings here so they are saved as global option and may be used by other systems. By default, language, real name, email and email_confirmed are synchronized to global settings:
#$wgRestAuthGlobalOptions['some setting'] = true;
# If you want the plugin to completely ignore some settings, you can add them here. By default, only the watchlist token is ignored.
#$wgRestAuthIgnoredOptions[] = 'ignored setting';
Migrating Wikis
The extension assumes that all relevant information is stored at the RestAuth server. So when a user logs in, the extension checks the password and fetches preferences and groups from the authentication server and stores them in the local database. This means that a user that does not exist for the RestAuth server, is not able to authenticate anymore, any preference or group not present at the RestAuth server is removed upon login (since e.g. the user might have removed the preference in a different wiki).
This means that moving existing Wikis to RestAuth requires you to migrate old user and group data. There is a separate extension that converts the Wikis user-data into the RestAuth import data format, which can be found in the migration repository.
After copying the extension into your extension folder, you have to enable it (as usual) in LocalSettings.php:
# RestAuth export require_once( "$IP/extensions/migration/mediawiki/RestAuthExport.php" );
Note that the export-extension uses many of the settings from the main authentication extension. It is highly recommended to configure the main extension first.
RestAuth downtime
This extension will not cause a MediaWiki go down if the RestAuth server is unavailable. The Wiki still works in general and existing sessions will stay valid. That means, if you already are logged in, you will stay logged in.
The extension will only throw an error when a user tries to login or to update his/her password. Groups and preferences are saved locally but will not be synchronized to the RestAuth server, changes made during RestAuth downtime will be lost once the server comes back up. The migration extension will use any settings you have configured for this extension, the recommended migration procedure thus is:
- Install this extension and the migration extension
- Configure the extension but do not yet add the service to the RestAuth server
- If you need to import old data:
- Export the data using Special:RestAuthExport (you have to have the 'editinterface' right to do this)
- Import the data on the RestAuth server using restauth-import
- Disable the migration extension again
- Add the service according to the information you have provided with $wgRestAuthService and $wgRestAuthServicePassword
Configure RestAuth server
The RestAuth server needs to know about each wiki using it. You can share the servicename and password among several wikis, but in order to improve logging and security, it is recommended to configure individual services for each wiki.
The exact details of the configuration depend on the server implementation, but since there currently only is one, here are instructions on how to add a service. The example below assumes that your wiki runs on wiki.example.com and the RestAuth server will receive the requests from 192.168.0.2:
# add service to authentication server root@auth ~ # restauth-service add wiki.example.com 192.168.0.2 password: <enter password here> confirm: <confirm>
If you do not want to migrate groups directly, you can add them in the RestAuth server:
# add standard groups: root@auth ~ # restauth-groups add --service=wiki.example.com sysop root@auth ~ # restauth-groups add --service=wiki.example.com bureaucrat # every bureaucrat is automatically a sysop: root@auth ~ # restauth-groups add-group --service=wiki.example.com --sub-service=wiki.example.com bureaucrat sysop # jane is a bureaucrat and thus (see above) automatically a sysop: root@auth ~ # restauth-groups add-user --service=wiki.example.com bureaucrat jane # joe is 'only' a sysop: root@auth ~ # restauth-groups add-user --service=wiki.example.com sysop joe
Sharing user groups
You might want to share groups (that grant or deny access) among several wikis. By default, groups are not shared among different services using RestAuth. If you want to share groups, you have to create a meta-group and sub-groups inheriting memberships from that meta-group. The RestAuth server documentation provides additional information on how to use meta-groups.
The migration extension makes exported groups belong to the service you configured with $wgRestAuthService. If you haven't configured that variable, RestAuthExport will ask for a default group. Leave the field empty to export groups not belonging to any service (which makes them global groups).
How synchronization works
Passwords
If the user sets a new password in MediaWiki, the new passwords is sent immediately to the RestAuth server. This means that the change takes immediate effect in all services that use RestAuth (unless the other service uses some sort of cache on its own). This also means that it is impossible to login if the RestAuth server is not available.
Groups & Preferences
Groups and Preferences are refreshed upon login, when viewing Special:Preferences or five minutes after the last refresh. The latter interval can be configured using $wgRestAuthRefresh.
Example
This Wiki is one of the Wikis that uses our own RestAuth server. Feel free to create an account here and then log in at, for example, vowi.fsinf.at.
Try updating preferences in this Wiki (try setting real name, email address or column width). All your preferences and groups are saved on the RestAuth server. The MediaWiki plugin updates preferences every five minutes by default (see $wgRestAuthRefresh above), so it will take a little while for your preferences to become visible in another wiki. If you logout and login again or view the preferences page, all your settings are immediately synchronized.
Changelog
0.9
- first version documented here.
Licence
GPL v3 or any later version.