From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
Crystal Clear action run.svg
Release status: stable
Implementation User identity, User rights, Hook
Description Provides framework for authentication and authorization extensions.
Author(s) Cindy Cicalese (cindy.cicalesetalk)
Latest version 5.6 (2018-10-09)
Compatibility policy master
MediaWiki 1.27+
License MIT License
  • $wgPluggableAuth_EnableAutoLogin
  • $wgPluggableAuth_EnableLocalLogin
  • $wgPluggableAuth_EnableLocalProperties
  • $wgPluggableAuth_ButtonLabelMessage
  • $wgPluggableAuth_ButtonLabel
  • $wgPluggableAuth_ExtraLoginFields
  • $wgPluggableAuth_Class
Hooks used
Translate the PluggableAuth extension if it is available at translatewiki.net
Check usage and version matrix.
Issues Open tasks · Report a bug

The PluggableAuth extension provides a framework for creating authentication and authorization extensions. PluggableAuth provides the shared code necessary to implement these extensions. PluggableAuth is especially useful for use with enterprise authentication servers accessed through layered mechanisms such as OpenID Connect or SimpleSAMLphp. Authentication extensions subclass the abstract PluggableAuth class. Because wiki sysops may wish to limit access to a subset of all authenticated users, PluggableAuth provides an authorization hook, PluggableAuthUserAuthorization. In addition, in order to augment MediaWiki's group information with that from an external provider, PluggableAuth provides the PluggableAuthPopulateGroups hook.

Installation[edit source]

  • Download and place the file(s) in a directory called PluggableAuth in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'PluggableAuth' );
  • The createaccount or autocreateaccount user rights must be granted to all users. See User rights.
  • Configure as required
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration[edit source]

Flag Default Description
$wgPluggableAuth_EnableAutoLogin false Should login occur automatically when a user visits the wiki?
$wgPluggableAuth_EnableLocalLogin false Should user also be presented with username/password fields on the login page to allow local password-based login to the wiki?
$wgPluggableAuth_EnableLocalProperties false If true, users can edit their email address and real name on the wiki. If false, the default, they cannot do so. Note that, if you rely on email address and/or real name returned from the authentication provider in any way, you should leave this setting at its default value.

After the call to authenticate() , PluggableAuth checks to see if the real name or email address returned are different from those saved in the wiki database. If either is different, it checks to see if this setting is true. If so, this is understood by PluggableAuth to indicate that the real name and email address are managed in the wiki on the Special:Preferences page, Otherwise, the real name and email address are managed by the authentication provider, so the new real name and email address values are saved to the wiki database. That is, if this setting is false, any changes to the real name or email address at the remote authentication provider will overwrite the local values when the user logs in.

$wgPluggableAuth_ButtonLabelMessage no default value If set, the name of a Message that will be used for the label of the login button on the Special:UserLogin form. This is useful if an authentication plugin will be showing the Special:UserLogin form to the user and needs to customize the button label with a localizable Message.
$wgPluggableAuth_ButtonLabel null If $wgPluggableAuth_ButtonLabelMessage is not set and $wgPluggableAuth_ButtonLabel is set to a string value, this string value will be used as the label of the login button on the Special:UserLogin form. This allows a wiki site administrator to set the label if a localizable Message is not provided by an authentication plugin. Note that this string is NOT localizable.
$wgPluggableAuth_ExtraLoginFields [] An array of extra fields to be added to the login form at Special:UserLogin. See HTMLForm for the format of the field descriptor array.
$wgPluggableAuth_Class no default value The manadatory name of a class that extends the abstract PluggableAuth class to provide authentication.

To change the text on the Log in button on the Special:Userlogin form from the text "Log In With PluggableAuth", you can edit the page MediaWiki:Pluggableauth-loginbutton-label.

The class specified by $PluggableAuth_Class must implement the following functions:

public function authenticate( &$id, &$username, &$realname, &$email, &$errorMessage )

  • Called to authenticate the user.
  • The parameters are used to return the user id, username, real name, and email address of the authenticated user and, if the user cannot be authenticated, an optional error message. $id is an integer and the remaining parameters are all strings. If the user cannot be authenticated and no value is set for $errorMessage, a default error message is displayed.
  • $id must be set to null if the user is new, in which case PluggableAuth will add the user to the database.
  • Must return true if the user has been authenticated and false otherwise.
  • If the return to URL, the name of the page, or the query parameters from the page that login was initiated from are necessary in the authenticate() function, they may be accessed as follows:
use \MediaWiki\Auth\AuthManager;


$authManager = AuthManager::singleton();
$returnToUrl = $authManager->getAuthenticationSessionData(
$returnToPage = $authManager->getAuthenticationSessionData(
$returnToQuery = $authManager->getAuthenticationSessionData(

public function saveExtraAttributes( $id )

  • Called after a new user has been authenticated and added to the database to add any additional information to the database required by the authentication mechanism.

public function deauthenticate( User &$user )

  • Called when the user logs out to notify the identity provider, if necessary, that cleanup such as removing the user's session should be done.

Authorization hooks use the PluggableAuthUserAuthorization hook to register an implementation of the following function:

function authorize( User $user, &$authorized )

  • $user is the User object for the user requesting authorization
  • $authorized must be set to true if the user is authorized and false otherwise.
  • Return true to call other authorization hook implementations and false to skip them.

Accessing Extra Login Fields[edit source]

If you specify extra fields for the login form using $wgPluggableAuth_ExtraLoginFields, the fields can be accessed in the authenticate() function in an authentication plugin as follows:

use MediaWiki\Auth\AuthManager;
$authManager = AuthManager::singleton();
$extraLoginFields = $authManager->getAuthenticationSessionData(

This will return an array of field values indexed by the name of the field from the field descriptor array.

Release Notes[edit source]

Version 5.6
  • Fixed autologin so it returns to the correct page after authentication.
Version 5.5
  • Fixed issue with PluggableAuthPopulateGroups hook.
Version 5.4
  • Added $wgPluggableAuth_ButtonLabelMessage and $wgPluggableAuth_ButtonLabel.
  • Coding style fixes.
Version 5.3
  • Added $wgPluggableAuth_ExtraLoginFields.
Version 5.2
  • Converted auto login to PHP from JavaScript.
Version 5.1
  • Added PluggableAuthPopulateGroups hook. Thank you to Poikilotherm for contributing this functionality.
Version 5.0
  • Added $wgPluggableAuth_EnableLocalProperties and removed use of editmyprivateinfo
  • Added debug statement when returntourl is not set
Version 4.2
  • Fixed exception when returntoquery is undefined.
Version 4.1
  • Added session variables to hold the name of the page and the query parameters of the page from which login was initiated for use in authenticate()
Version 4.0
  • Added optional error message to authenticate()
  • Bumped version number to synchronize with SimpleSAMLphp and OpenIDConnect extensions
Version 2.2
  • Confirm email addresses coming from external authentication sources
Version 2.1
  • Update file naming conventions
Version 2.0
  • Almost completely rewritten to support the new MediaWiki 1.27 authentication and session management framework
  • Switched to new extension registration
  • Configuration variable names changed to add $wg prefix
  • $PluggableAuth_Timeout removed
  • $PluggableAuth_AutoLogin renamed to $wgPluggableAuth_EnableAutoLogin
  • $wgPluggableAuth_EnableLocalLogin added to support local password-based login to the wiki in addition to PluggableAuth
Version 1.2
  • Moved the addition of a new user to the wiki database to after successful authorization of the user
  • Added editmyprivateinfo check
Version 1.1
  • Added call to logout when session times out to ensure that the deauthenticate function in implementing classes gets called
Version 1.0
  • Initial version

See also[edit source]