扩展:PluggableAuth

PluggableAuth的扩展提供了一个创建身份验证授权扩展的框架。

身份验证是证明用户身份的过程。 例如,可以通过提供用户名和密码、某种令牌或生物识别信息来完成这一过程。

以下是可与PluggableAuth一起使用的主要身份验证扩展:

• AuthRemoteUser – delegates authentication to webserver via REMOTE_USER, i.e. MIT Kerberos
• Cas – 使用CAS协议与CAS服务器
• JWTAuth – 使用JSON Web令牌
• LDAPAuthentication2 – 使用LDAP(轻量目录访问协议)
• NaylorAMS – 使用 Naylor Association Management Software(Naylor 协会管理软件)
• OpenID Connect – 使用OpenID
• PHPBB Auth – 使用phpBB
• Shibboleth – 使用Shibboleth
• SimpleSAMLphp – 使用 SAML
• WSOAuth – 使用 OAuth

还存在以下身份验证扩展,但只能与旧版本的PluggableAuth一起使用:

• DiscourseSsoConsumer – 使用Discourse

授权是验证用户是否应该访问特定资源的过程。 例如,可以通过检查授权电子邮件地址列表或检查身份服务器提供的用户属性值来实现。

在PluggableAuth之下,授权类扩展确定经过身份验证的用户是否可以继续登录到wiki。 然而,身份验证扩展(而非授权扩展)负责根据身份提供商(IdP)传递的属性来确定用户应被授权访问哪些用户组。

以下授权扩展可与PluggableAuth一起使用:

• Email Authorization – 使用电子邮件地址和域名列表
• LDAP Authorization – 使用LDAP

PluggableAuth必须与一个或多个身份验证插件以及零个或多个授权插件一起使用。 如果使用了多个身份验证插件,则会在Special:UserLogin页面上为每个身份验证插件添加一个按钮。 如果使用单个身份验证插件且禁用了本地登录,则Special:UserLogin页面将被绕过。 如果没有使用任何授权插件,则所有已认证用户都将获准使用该维基。

PluggableAuth 定义了一个重要的钩子:PluggableAuthUserAuthorization 。 此钩子使授权插件能够提供代码以做出授权决策。 此前,它还定义了钩子PluggableAuthPopulateGroups 。 此钩子曾用于利用外部提供者的信息来增强MediaWiki的用户组信息,但在7.0.0版本中它被移除,并替换为一个功能。

• 下载文件,并解压PluggableAuth文件夹到extensions/目录中。
  开发者和代码贡献人员应改从Git安装此扩展,输入:

  cdextensions/
  gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/PluggableAuth
  

• 請新增下列代码到您的LocalSettings.php 文件的底部:

  wfLoadExtension( 'PluggableAuth' );
  

• 必须授予所有用户createaccount或autocreateaccount用户权限。 参见User rights。
• 根据需要配置
• Yes 完成 – 請导航至您的wiki上的Special:Version,以验证此扩展已成功安装。

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.

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.

$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 );
 }
 ]
 ]
 ]
];

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.

$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' ]
 ]
 ]
 ]
 ]
];

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;

• 调用以验证用户。
• 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.

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.

...
$authManager = MediaWikiServices::getInstance()->getAuthManager();
$extraLoginFields = $authManager->getAuthenticationSessionData(
 PluggableAuthLogin::EXTRALOGINFIELDS_SESSION_KEY
);

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.

In LocalSettings.php add:

# https://www.mediawiki.org/w/index.php?title=Project%3ASupport%20desk/Flow/2024/01#h-%5BDeveloper_question%5D_How_to_modify_the_css_of_buttons_on_Special%3ALogin_to_show_e-20240114040600
# 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;
};

Version 7.5.0

• Allow autologin from img_auth.php entrypoint (T388862)
• Fix weight assignment in moveLoginButton (T389163)
• Use new class names for RawMessage, Message, ExtensionRegistry, etc. (T388624)

Version 7.4.0

• Add optional support for backchannel logout in plugins (T327147)

Version 7.3.0

• Requires MediaWiki 1.40+ (T395463) despite the "exension.json" file still indicating 1.35+
• Redirect to login page with an error message if no returnToUrl is found (T373409)

Version 7.2.0

• Use real name and email address from DB if not provided by plugin (T383520)

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
• 需要1.35或更高版本的MediaWiki
• 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

• 增加了$wgPluggableAuth_ButtonLabelMessage和$wgPluggableAuth_ButtonLabel。
• Coding style fixes.

Version 5.3

• 加入了$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

• Stable extensions/zh
• User identity extensions/zh
• User rights extensions/zh
• Hook extensions/zh
• Extensions supporting Composer/zh
• AuthChangeFormFields extensions/zh
• AuthPreserveQueryParams extensions/zh
• BeforeInitialize extensions/zh
• ImgAuthBeforeStream extensions/zh
• LocalUserCreated extensions/zh
• LoginFormValidErrorMessages extensions/zh
• PostLoginRedirect extensions/zh
• SkinTemplateNavigation::Universal extensions/zh
• SpecialPage initList extensions/zh
• TitleReadWhitelist extensions/zh
• UserLogoutComplete extensions/zh
• MIT licensed extensions/zh
• Extensions in Wikimedia version control/zh
• All extensions/zh
• Extensions included in BlueSpice/zh
• Extensions included in Canasta/zh
• Extensions included in ProWiki/zh
• Extensions included in semantic::core/zh
• Login extensions/zh
• Extensions by MITRE/zh