Erweiterung:PluggableAuth

**MediaWiki-Erweiterungen**
PluggableAuth Freigabestatus: stabil

Einbindung	Benutzeridentität , Benutzerrechte , Hook
Beschreibung	Stellt ein Framework für Erweiterungen für Authentifizierung und Autorisierung.
Autor(en)	Cindy Cicalese (cindy.cicalese^Diskussion)
Letzte Version	7.1.0 (2024-02-23)
Kompatibilitätspolitik	Snapshots werden zusammen mit MediaWiki veröffentlicht. Der Master ist nicht abwärtskompatibel.
Composer	mediawiki/pluggable-auth
Lizenz	MIT-Lizenz
Herunterladen	Erweiterung herunterladen Git ^[?]: Git master herunterladen Repository durchsuchen (Phabricator · GitHub) Ergänzungen und Änderungen Repository-Mitwirkende (GitHub) Code-Review
Parameter $wgPluggableAuth_EnableFastLogout $wgPluggableAuth_EnableLocalLogin $wgPluggableAuth_EnableLocalProperties $wgPluggableAuth_EnableAutoLogin $wgPluggableAuth_Config
Verwendete Hooks AuthChangeFormFields BeforeInitialize LocalUserCreated SkinTemplateNavigation::Universal SpecialPage_initList TitleReadWhitelist UserLogoutComplete
Bereitgestellte Hooks PluggableAuthPopulateGroups PluggableAuthUserAuthorization
Quarterly downloads	861 (Ranked 2^nd)
Übersetze die PluggableAuth-Erweiterung, wenn sie auf translatewiki.net verfügbar ist
Probleme	Offene Aufgaben · Einen Fehler melden

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 are the main authentication extensions that can be used with PluggableAuth:

AuthRemoteUser - delegates authentication to webserver via REMOTE_USER, i.e. MIT Kerberos
Cas - uses Cas protocol with Cas server
JWTAuth - uses JSON Web Tokens
LDAPAuthentication2 - verwendet LDAP
OpenID Connect - verwendet OpenID Connect
PHPBB Auth - verwendet phpBB
Shibboleth - Verwendet Shibboleth
SimpleSAMLphp - verwendet SAML
WSOAuth - verwendet OAuth

The following authentication extensions also exist, but can only be used with older versions of PluggableAuth:

DiscourseSsoConsumer - verwendet Discourse
NaylorAMS - verwendet Naylor Association Management Software

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:

Email Authorization - uses a list of email addresses and domains
LDAP Authorization - verwendet 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 Special:UserLogin page. If a single authentication plugin is used and local login is disabled, the Special:UserLogin page will be bypassed. If no authorization plugins are used, all authenticated users will be authorized to use the wiki.

PluggableAuth defines one important hook: PluggableAuthUserAuthorization . This hook enables authorization plugins to provide code to make an authorization decision. Previously, it also defined the hook PluggableAuthPopulateGroups . This hook was used to augment MediaWiki's group information with that from an external provider, but in version 7.0.0 it was removed and replaced with a function.

Installation

Die Erweiterung herunterladen und die Datei(en) in ein Verzeichnis namens PluggableAuth im Ordner extensions/ ablegen.
Entwickler und Code-Beitragende sollten stattdessen die Erweiterung von Git installieren, mit:cd extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PluggableAuth
Folgenden Code am Ende deiner LocalSettings.php -Datei einfügen:
```
wfLoadExtension( 'PluggableAuth' );
```
The createaccount or autocreateaccount user rights must be granted to all users. See User rights.
Konfiguriere nach Bedarf
Erledigt – Navigiere zu Special:Version in deinem Wiki, um zu überprüfen, ob die Erweiterung erfolgreich installiert wurde.

One or more authentication plugins and zero or more authorization plugins must be installed as well.

Versions 6.0 and 7.0.0 of PluggableAuth are significant upgrades. The configuration variable $wgPluggableAuth_Config is required in version 6.0 and later. The plugins must be compatible with the version of PluggableAuth installed.

Compatibility matrix
Plugin	PluggableAuth version 7.0.0 or later	PluggableAuth version 6.x	PluggableAuth version 5.7 or earlier
AuthRemoteUser	1.0.0	-	-
Cas	1.0	-	-
DiscourseSsoConsumer	-	4.0.0	3.0.0
JWTAuth	2.0.0	-	-
LDAPAuthentication2	2.0.0	-	1.0.1
NaylorAMS	0.2.0	-	0.1.0
OpenID Connect	7.0.0	6.0.0	5.4.0
PHPBB Auth	4.1.0	4.1.0	4.0.0
Shibboleth	2.0.0	-	v1.0.0-rc.1
SimpleSAMLphp	7.0.0	5.0.0	4.5.2
WSOAuth	9.0.0	6.0.0	5.0.0
EmailAuthorization	3.0.0	3.0.0	2.0.0
LDAPAuthorization	2.0.0	-	1.0.0

Konfiguration

All versions

Flag	Standard	Beschreibung
`$wgPluggableAuth_EnableAutoLogin`	`false`	Should login occur automatically when a user visits the wiki? true will prevent anonymous read! since every view will get redirected to the login page.
`$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.

Version 7.0.0 or later

Flag	Default	Description
`$wgPluggableAuth_EnableFastLogout`	`false`	Allow logout without an extra button click to confirm if bypassing the XHR POST logout. Since MediaWiki 1.35 by default (Skin "Vector") the logout is no longer performed by navigating to "Special:UserLogout", but is instead done by an XHR POST request. This is incompatible with the logout process of many external identity providers if performing single logout, so a mechanism was added to allow the old approach, but by default that requires an additional button click to confirm logout. Setting this flag to `true` will avoid that additional button click.

Version 6.0 or later

Flag	Standard	Beschreibung
`$wgPluggableAuth_Config`	kein Standardwert	An array of arrays containing configuration for the authentication plugins. The keys to the outer array are used as the button labels on `Special:UserLogin` if no button message is provided in the respective inner array. The valid keys to the inner arrays are: `plugin` (required) — The name of the authentication plugin `buttonLabelMessage` (optional) — The system message key, e.g., SSOButtonLabel that lets you add the label at MediaWiki:SSOButtonLabel to be used for the button on `Special:UserLogin` Note that the message added must be in the instance language since it cannot be localized on wiki. `weight` — (version 7.1.0 and later) The weight to use to control the placement of the fields, if any, on Special:UserLogin. Sorting is handled by `AuthManagerSpecialPage::sortFormDescriptorFields()`. `data` — A configuration array to be passed to the authentication plugin. The contents depend upon the authentication plugin. Depending upon the authentication plugin, this may be optional or required. `groupsyncs` — (version 7.0.0 and later) Configuration array for group syncronization. See details at Group Synchronization below.

Version 5.7 or earlier

Flag	Standard	Beschreibung
`$wgPluggableAuth_ButtonLabelMessage`	kein Standardwert	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. If not set and if no value is set for `$wgPluggableAuth_ButtonLabelMessage`, the value of the `pluggableauth-loginbutton-label` message, which has a default value of "Log in with PluggableAuth" will be used. To override this value you can edit the page `MediaWiki:Pluggableauth-loginbutton-label` and its language variants. This configuration variable is usually set, if at all, by authentication plugins and not by wiki site administrators. If set by a wiki site administrator, the relevant message pages in the MediaWiki namespace will need to be created with the localized message values.
`$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 the documentation for AuthenticationRequest:getFieldInfo() for the format of the array. This configuration variable may be set by authentication plugins and should not be set by wiki site administrators.
`$wgPluggableAuth_Class`	kein Standardwert	The name of a class that extends the abstract `PluggableAuth` class to provide authentication. This configuration variable must be set by authentication plugins and should not be set by wiki site administrators.

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 groupsyncs array to the $wgPluggableAuth_Config 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 type element, which will have the value syncall, mapped, or the name of a custom group sync. Group syncs may also specify a groupAttributeDelimiter that can be used to explode multi-valued attributes.

`syncall`group sync

The syncall 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:

groupAttributeName (default: "groups"): 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, path, that is an array of strings that form a path through the attributes to the group values.

It may also contain an element, prefix, that is a string to prepend to the name of each group found in that path.

locallyManaged (default: [ "sysop" ]): 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.
filterPrefix (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 locallyManaged array will be removed and replaced by those sent by the identity provider.
onlySyncExisting (default: false): Only add groups that are already known to MediaWiki.
groupNameModificationCallback (optional): A callback that will be applied to each group name.

Example

$wgPluggableAuth_Config = [
  "My Login" => [
    'plugin' => '...',
    'data' => [
      ...
    ],
    'groupsyncs' => [
      [
        'type' => 'syncall',
        'locallyManaged' => [ 'sysop', 'bureaucrat' ],
        'filterPrefix' => 'oidc_',
        'groupAttributeName' => [
          [
            'path' => ['realm_access', 'roles'],
            'prefix' => 'global_',
          ],
          [
            'path' => ['resource_access', 'account', 'roles'],
          ]
        ],
        'groupNameModificationCallback' => static function ( $origGroupName ) {
          return str_replace( 'globex', 'acme', $origGroupName );
        }
      ]
    ]
  ]
];

`mapped`group sync

The mapped 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:

map: 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.
addOnlyGroups (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

$wgPluggableAuth_Config = [
  "My Login" => [
    'plugin' => '...',
    'data' => [
      ...
    ],
    'groupsyncs' => [
      [
        'type' => 'mapped',
        'map' => [
          'industry' => [ 'groups' => 'Professional Member' ],
          'student' => [ 'groups' => 'Student Member' ],
          'member' => [ 'groups' => [ 'Professional Member', 'Student Member'  ] ],
          'staff' => [ 'groups' => 'Staff' ]
        ]
      ]
    ]
  ]
];

Developer notes

Creating an authentication plugin

Version 6.0 and later:

Authentication plugins subclass the abstract MediaWiki\Extension\PluggableAuth\PluggableAuth class provided by PluggableAuth.
In version 6.0 and later, an authentication plugin must specify at attributes section in extension.json. For example:

"attributes": {
   "PluggableAuth": {
      "OpenIDConnect": {
         "class": "MediaWiki\\Extension\\OpenIDConnect\\OpenIDConnect",
         "services": [
            "MainConfig",
            "AuthManager",
            "OpenIDConnectStore"
         ]
      }
   }
},

Version 5.7 and earlier:

Authentication plugins subclass the abstract PluggableAuth class provided by PluggableAuth.
An authentication plugin must set $PluggableAuth_Class to the name of this subclass.

The authentication plugin subclass must implement the following methods:

public function authenticate( ?int &$id, ?string &$username, ?string &$realname, ?string &$email, ?string &$errorMessage ): bool;

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:

$returnToUrl = $this->authManager->getAuthenticationSessionData(
    PluggableAuthLogin::RETURNTOURL_SESSION_KEY
);
$returnToPage = $this->authManager->getAuthenticationSessionData(
    PluggableAuthLogin::RETURNTOPAGE_SESSION_KEY
);
$returnToQuery = $this->authManager->getAuthenticationSessionData(
    PluggableAuthLogin::RETURNTOQUERY_SESSION_KEY
);

public function saveExtraAttributes( int $id ): void

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( UserIdentity &$user ): void

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 Special:UserLogin 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 Special:UserLogin form using the PluggableAuth::getExtraLoginFields() static function (or $wgPluggableAuth_ExtraLoginFields in version 5.7 or earlier), and local login (which enables the username and password fields on the Special:UserLogin form) is not enabled by a site administrator using $wgPluggablAuth_EnableLocalLogin, the Special:UserLogin page will not be displayed.

Even if 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 Special:UserLogin. Instead, it should go to a custom, unlisted special page based on PluggableAuthLogin.php. 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 the PluggableAuth::getExtraLoginFields() static function (or $wgPluggableAuth_ExtraLoginFields in version 5.7 or earlier), the fields can be accessed in the authenticate() function in an authentication plugin as follows:

...
$authManager = MediaWikiServices::getInstance()->getAuthManager();
$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.

Creating an authorization plugin

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

function authorize( UserIdentity $user, bool &$authorized ): void

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

Enlarge the login buttons to fit longer button texts

The patch enlarges the login buttons (the standard Login button and the Extension:OpenIDConnect's Login button) to display the complete texts on the buttons, even if your texts are longer than usual.

In LocalSettings.php add:

# https://www.mediawiki.org/w/index.php?title=Topic:Xx8ol75kyh1qejp8
# How to modify the Login-Page
$GLOBALS['wgHooks']['BeforePageDisplay'][] = function( OutputPage &$out, Skin &$skin ) {
        $style = <<<EOT
            <style type="text/css">
                    button#wpLoginAttempt {
                            white-space: normal;
                            word-wrap: break-word;
                            height: auto !important;
                    }

                    button#mw-input-pluggableauthlogin0 {
                            background-color: salmon !important;
                            border-color: salmon !important;
                            white-space: normal;
                            word-wrap: break-word;
                            height: auto !important;
                    }
            </style>
EOT;

        $out->addHeadItem( 'change-login-button', $style );
        return true;
};

Veröffentlichungshinweise

Version 7.1.0

Add weight parameter to config to control the placement of fields on Special:UserLogin

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 $wgPluggableAuth_Config
Benötigt MediaWiki 1.35+
Drop support for the following configuration variables:
- $wgPluggableAuth_ButtonLabelMessage (use the buttonLabelMessage field in the corresponding $wgPluggableAuth_Config entry)
- $wgPluggableAuth_ButtonLabel (use the index of the corresponding $wgPluggableAuth_Config entry)
- $wgPluggableAuth_ExtraLoginFields (use static function in PluggableAuth class)
- $wgPluggableAuth_Class (now specified by an attribute in the authentication plugin's extension.json and referred to by the plugin field in the corresponding $wgPluggableAuth_Config 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 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 entfernt
$PluggableAuth_AutoLogin umbenannt in $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

Diese Erweiterung ist in den folgenden Softwarepaketen enthalten und/oder wird von den folgenden Wiki-Farmen, bzw. Wiki-Hostern verwendet:

Dies ist keine maßgebliche Liste. Softwarepakete und/oder Wiki-Farmen, bzw. Wiki-Hoster nutzen diese Erweiterung ggf., obwohl sie nicht in dieser Liste enthalten sind. Prüfe daher stets die Nutzung im verwendeten Softwarepaket und/oder bei der Wiki-Farm, bzw. dem Wiki-Hoster.

Erweiterung:PluggableAuth

Installation

Konfiguration

All versions

Version 7.0.0 or later

Version 6.0 or later

Version 5.7 or earlier

Group Synchronization

syncallgroup sync

Example

mappedgroup sync

Example

Developer notes

Creating an authentication plugin

Special:UserLogin and extra login fields

Creating an authorization plugin

Enlarge the login buttons to fit longer button texts

Veröffentlichungshinweise

`syncall`group sync

`mapped`group sync