Extension:PluggableAuth/en

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:


 * - uses SAML
 * - uses OpenID Connect
 * - uses LDAP
 * - uses OAuth
 * - uses Shibboleth
 * - uses Discourse
 * - uses Naylor Association Management Software
 * - uses phpBB
 * - uses JSON Web Tokens
 * - uses Cas protocol with Cas server

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:


 * - uses a list of email addresses and domains
 * - uses LDAP

PluggableAuth must be used with one or more authentication plugins and zero or more authorization plugins. If more than one authentication plugin is used, a button for each authentication plugin will be added to the  page. If a single authentication plugin is used and local login is disabled, the  page will be bypassed. If no authorization plugins are used, all authenticated users will be authorized to use the wiki.

PluggableAuth defines two important hooks:


 * - enables authorization plugins to provide code to make an authorization decision
 * - used to augment MediaWiki's group information with that from an external provider

Group Synchronization
In version 7.0.0 and later when you are using an authentication plugin that supports retrieval of attributes from the identity provider (currently OpenID Connect, SimpleSAMLphp, WSOAuth, and JWTAuth), it is possible to synchronize groups from the identity provider to MediaWiki groups. There are two built-in group synchronization algorithms, syncall and mapped, described below. It is also possible for an extension to provide additional custom group synchronization algorithms.

To configure group synchronization, add a  array to the   array. That array must contain one or more arrays that specify a group sync to be applied to the attributes retrieved from the identity provider. All group syncs must define a  element, which will have the value ,  , or the name of a custom group sync. Group syncs may also specify a  that can be used to explode multi-valued attributes.

The  group sync will synchronize all groups in the relevant attributes sent from the identity provider to MediaWiki groups. It supports the following additional configuration elements:
 * (default: ): The name of the attribute that contains the groups identified for the user by the identity provider. This can be a single string value or can be an array. If it is an array, it must contain an element, , that is an array of strings that form a path through the attributes to the group values. It may also contain an element,  , that is a string to prepend to the name of each group found in that path.
 * (default: ): An array of strings that are the names of groups that will be managed by MediaWiki rather than the identity provider, so they should not be removed if they are not in the array of groups sent by the identity provider.
 * (default: ): A prefix to prepend to all groups found by this group sync. If provided, only groups already assigned to the user in MediaWiki that begin with this prefix will be removed and replaced with the groups sent by the identity provider; if it is not provided, all groups except those in the   array will be removed and replaced by those sent by the identity provider.
 * (default: ): Only add groups that are already known to MediaWiki.
 * (optional): A callback that will be applied to each group name.

Example:

mapped
The  groupsync is used when only a subset of groups sent from the identity provider should be synchronized with the wiki. Only groups that are mentioned in the mapping are affected by the mapping. It supports the following additional configuration elements:
 * : An array containing the mapping to MediaWiki groups from identity provider attributes. Each top level array index is the name of a MediaWiki group. The array elements corresponding to those indices contain an array of elements each with an attribute name as the array index and a string value or an array of string values as the value, indicating the attribute values that will map to that group.
 * (default: ): An array of MediaWiki groups that should only be added to the user if they appear in the attributes sent from the identity provider, not removed if they do not appear.

Example:

Creating an authentication plugin
Version 6.0 and later:
 * Authentication plugins subclass the abstract  class provided by PluggableAuth.
 * In version 6.0 and later, an authentication plugin must specify at  section in  . For example:

Version 5.7 and earlier:
 * Authentication plugins subclass the abstract  class provided by PluggableAuth.
 * An authentication plugin must set to the name of this subclass.

The authentication plugin subclass must implement the following methods:


 * 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.  is an integer and the remaining parameters are all strings. If the user cannot be authenticated and no value is set for , a default error message is displayed.
 * must be set to  if the user is new, in which case   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:


 * 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.


 * 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
The  page will only be displayed to the user during authentication if user interaction is required.

That is, if there is only a single configured authentication provider, its authentication plugin does not add extra fields to the  form using the  static function (or  in version 5.7 or earlier), and local login (which enables the username and password fields on the   form) is not enabled by a site administrator using, the   page will not be displayed.

Even if  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  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  form using the  static function (or  in version 5.7 or earlier), the fields can be accessed in the   function in an authentication plugin as follows:

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

Creating an authorization plugin
Authorization hooks use the hook to register an implementation of the following function:


 * is the UserIdentity object for the user requesting authorization
 * must be set to true if the user is authorized and false otherwise.

Release notes

 * Version 7.0.0
 * Add group population framework (migrated from SimpleSAMLphp functionality)
 * Made config case insensitive
 * Converted group population from a hook to a function
 * Code improvements
 * Bug fixes:
 * T333415: LDAP login does not work when local login is enabled
 * T334083: Problem with auto-creation of LDAP user in the wiki in case of the first login
 * T334950: Username missing in "onPluggableAuthUserAuthorization" hook
 * T305031: Error when logging out via API
 * T322828: Don't store return to URL as an auth/session secret
 * Version 6.3
 * Fixed MW 1.35 incompatibility in deauthenticate
 * Version 6.2
 * added compatibility with MW 1.39
 * Switch from deprecated PersonalUrls hook to SkinTemplateNavigation::Universal
 * Only set real name if it is not null
 * Use setter and getter for user's real name
 * Version 6.1
 * restored backward compatibility with MW 1.35 (T308865)
 * Version 6.0
 * Support multiple authentication plugins using
 * Requires MediaWiki 1.35+
 * Drop support for the following configuration variables:
 * (use the  field in the corresponding  entry)
 * (use the index of the corresponding entry)
 * (use static function in  class)
 * (now specified by an attribute in the authentication plugin's extension.json and referred to by the   field in the corresponding  entry)
 * 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  hook.


 * Version 5.4
 * Added and.
 * Coding style fixes.


 * Version 5.3
 * Added.


 * Version 5.2
 * Converted auto login to PHP from JavaScript.


 * Version 5.1
 * Added  hook. Thank you to Poikilotherm for contributing this functionality.


 * Version 5.0
 * Added 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


 * 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
 * removed
 * renamed to
 * 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  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