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.7 (2018-11-26)|
|Compatibility policy||Master maintains backward compatibility.|
|Translate the PluggableAuth extension if it is available at translatewiki.net|
|Issues||Open tasks · Report a bug|
The PluggableAuth extension provides a framework for creating authentication and authorization extensions.
Authentication is the process of proving that a user is who they say they are. This may be done, for example, by providing a username and password or some token or biometric.
The following authentication extensions can be used with PluggableAuth:
- LDAPAuthentication2 - uses LDAP
- NaylorAMS - uses Naylor Association Management Software
- OpenID Connect - uses OpenID Connect
- Shibboleth - uses Shibboleth
- SimpleSAMLphp - uses SAML
- SteamAuth - uses Steam authentication
- WSOAuth - uses OAuth
Authorization is the process of determining whether a particular authenticated user should have access to a particular resource. This may be done, for example, by checking a list of authorized email addresses or checking values of user attributes provided by an identity server.
In PluggableAuth's case, authorization extensions determine if an authenticated user may proceed with logging in to a wiki. However, the authentication extensions (rather than the authorization extensions) take care of which user groups a user should be authorized for, based on the attributes passed from the identity provider (IdP).
The following authorization extensions can be used with PluggableAuth:
This extension must be used with exactly one authentication plugin and zero or more authorization plugins. If no authorization plugins are used, all authenticated users will be authorized to use the wiki.
PluggableAuth defines two important hooks:
- PluggableAuthUserAuthorization - enables authorization plugins to provide code to make an authorization decision
- PluggableAuthPopulateGroups - used to augment MediaWiki's group information with that from an external provider
- Download and place the file(s) in a directory called
- 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
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
||Should login occur automatically when a user visits the wiki?|
||Should user also be presented with username/password fields on the login page to allow local password-based login to the wiki?|
||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
||no default value||If set, the name of a message that will be used for the label of the login button on the |
||An array of extra fields to be added to the login form at |
||no default value||The name of a class that extends the abstract |
Creating an authentication plugin
Authentication plugins subclass the abstract
PluggableAuth class provided by PluggableAuth.
An authentication plugin must set
$PluggableAuth_Class to the name of this subclass and 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.
$idis 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.
$idmust be set to
nullif the user is new, in which case
PluggableAuthwill 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( PluggableAuthLogin::RETURNTOURL_SESSION_KEY ); $returnToPage = $authManager->getAuthenticationSessionData( PluggableAuthLogin::RETURNTOPAGE_SESSION_KEY ); $returnToQuery = $authManager->getAuthenticationSessionData( PluggableAuthLogin::RETURNTOQUERY_SESSION_KEY );
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.
Special:UserLogin and extra login fields
Special:UserLogin page will only be displayed to the user during authentication if there are fields on that form that the user must fill in.
That is, if an authentication plugin does not add extra fields to the
Special:UserLogin form using
$wgPluggableAuth_ExtraLoginFields and if local login (which enables the username and password fields on the
Special:UserLogin form) is not enabled by a site administrator using
Special:UserLogin page will not be displayed.
Special:UserLogin is not displayed, it may be necessary for an authentication plugin to gather user input using a web page provided by an enterprise authentication system.
This would be accomplished by a redirect, often from within the authentication library used by the authentication plugin.
If no such library exists and you need to implement the authentication mechanism from scratch, the redirect should not go to
Instead, it should go to a custom, unlisted special page based on
Finally, if there is no user input required by the user as part of authentication from either
Special:UserLogin or the remote authentication system, clicking on the Log in link will simply re-render the current page in a logged in state.
If an authentication plugin adds extra fields to the
Special:UserLogin 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( PluggableAuthLogin::EXTRALOGINFIELDS_SESSION_KEY );
This will return an array of field values indexed by the name of the field from the field descriptor array.
Authorization hooks use the PluggableAuthUserAuthorization hook to register an implementation of the following function:
function authorize( User $user, &$authorized )
$useris the User object for the user requesting authorization
$authorizedmust 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.
- Version 5.7
- Added error message when there is a rare fatal session error
- Version 5.6
- Fixed autologin so it returns to the correct page after authentication.
- Version 5.5
- Fixed issue with
- Version 5.4
- Coding style fixes.
- Version 5.3
- Version 5.2
- Version 5.1
PluggableAuthPopulateGroupshook. Thank you to Poikilotherm for contributing this functionality.
- Version 5.0
$wgPluggableAuth_EnableLocalPropertiesand 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
- Version 4.0
- Added optional error message to
- 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
$wgPluggableAuth_EnableLocalLoginadded 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
- 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