Extension:OATHAuth

本页面的主题不是Extension:OAuth。

MediaWiki扩展手册

OATHAuth 发行状态： 稳定版
实现	用户权限 , 特殊页面 , 页面操作
描述	为登录提供双因素身份验证
作者	Ryan Lane
最新版本	持续更新
兼容性政策	快照跟随MediaWiki发布。 master分支不向后兼容。
数据库更改	是
虚拟域	virtual-oathauth
表 oathauth_types oathauth_devices oathauth_users
参数 $wgOATHRequiredForGroups $wgWebAuthnNewCredsDisabled $wgWebAuthnRelyingPartyName $wgOATH2FARequiredGroupRemovalPages $wgOATHMaxKeysPerUser $wgWebAuthnRelyingPartyID $wgOATHAuthWindowRadius $wgOATHRecoveryCodesCount $wgOATHAuthAccountPrefix $wgOATHSecretKey $wgOATHPasswordlessLogin $wgOATHExclusiveRights $wgOATHPrioritizedModules
添加权限 oathauth-enable oathauth-api-all oathauth-disable-for-user oathauth-view-log oathauth-verify-user
使用的函数钩 AuthChangeFormFields BeforePageDisplay GetPreferences LoadExtensionSchemaUpdates ReadPrivateUserRequirementsCondition UnitTestsAfterDatabaseSetup UnitTestsBeforeDatabaseTeardown UserEffectiveGroups UserGetRights UserRequirementsCondition getUserPermissionsErrors
许可协议 GNU General Public License 2.0 or later GNU General Public License 3.0 or later
下載	下載扩展 Git [?]: 浏览存储库 (Phabricator · GitHub) Gerrit代码复核 Git提交日誌 下載原始碼（tarball壓縮）
前往translatewiki.net翻譯OATHAuth扩展
問題	开启的任务 · 报告错误

OATHAuth扩展提供了双因素身份验证(2FA)的支援。 此功能讓MediaWiki使用者能透過驗證碼、安全金鑰或通行密鑰，配合其常規密碼，以更安全的方式登入系統。 它採用了OATH（開放認證倡議）和WebAuthn標準。

OATHAuth 支援以下兩種雙重驗證方式：

• 密碼管理器與驗證器應用程式
• 通行密鑰
• 安全金鑰
• 復原碼

OATHAuth 亦包含對無密碼登入的實驗性支援，並提供可供其他擴充功能接入的雙重驗證框架。

• 此扩展与OAuth无关，它是一個不同的协议。
• 原先的 WebAuthn 擴充功能已併入此擴充功能之中。

用法

双因素身份验证上的帮助页面为终端用户提供了有关如何使用此扩展的信息。

某些說明於雙重驗證的政策僅適用於維基媒體專案。 然而，任何使用 Extension:OATHAuth 的維基在啟用雙重驗證時，其基本操作步驟皆相同。

此Special:AccountSecurity頁面會引導使用者去新增與管理雙重驗證的方法與復原碼。

安裝

此扩展随附于MediaWiki 1.31及更新版本，因此您無需下載它。 但其余的配置的指示仍须依循執行。

警告：	There is a bug with this extension where it does not update properly from the web (mw-config) updater and must instead use the update.php command line update script (phab:T371849)

在安裝 OATHAuth 之前，請先安裝 GMP php 或 BCMath php 擴充功能。 WebAuthn 功能需要上述兩種擴充功能的其中之一。

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

  cd extensions/
  git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/OATHAuth
  

• 只有是從Git安裝的才需运行Composer来安装PHP依赖，通过发行composer install --no-dev至扩展的目录。 （参见T173141了解潜在问题。）
• 請新增下列代码到您的LocalSettings.php 文件的底部：

  wfLoadExtension( 'OATHAuth' );
  

• 請运行更新脚本，它将自动创建此扩展所必须的数据库表。
• 按需求配置。
• 强烈建议在使用OATHAuth时设置缓存 。 如果使用OATHAuth，这不仅能提高性能，还能提高维基的安全性。 如果只运行一个应用程序或网络服务器并安装好了php-apcu，且未配置特定缓存，MediaWiki 很可能会退回到使用APCu。 如果您使用多个应用程序/网络服务器，建议设置对象缓存 缓存，供所有主机使用。 例子包括Memcached 。
• 完成 – 請导航至您的wiki上的Special:Version，以验证此扩展已成功安装。

配置

参数

配置旗标	默认值	描述
$wgOATHAuthWindowRadius	4	每个方向上应该有效的令牌窗口数。 这告诉OATH接受令牌的有效范围为((1 + 2 * $wgOATHAuthWindowRadius) * 30)秒。 此有效窗口的范围以当前时间为中央。 此配置变量的目的是考虑到用户时钟和服务器时钟之间的差异。 然而，建议尽可能讓它低。
$wgOATHAuthAccountPrefix	false	此前缀用于OATHAuth用户帐户名称和该帐户的发佈者。 該值若是false，则使用$wgSitename的值。
$wgOATHExclusiveRights	[]	（在版本1.46移除） 針對未使用雙重驗證登入的使用者所撤回的權限組合。
$wgOATHRequiredForGroups	[]	（在1.46版本中已弃用） 設定一組必須啟用雙重驗證的使用者群組清單。若要要求所有已登入使用者皆須啟用雙重驗證，請使用 『user』。 This was deprecated in MediaWiki 1.46, and should be replaced by 手册:$wgRestrictedGroups ; see the example at 手册:$wgRestrictedGroups .
$wgOATHSecretKey	false	（在版本1.45引入） 請先更新至 1.45（或更高版本）然後執行 更新腳本 ，再啟用此功能並執行其專屬維護腳本！ 用於加密OATH相關資料的私密金鑰值，其長度應為SODIUM_CRYPTO_SECRETBOX_KEYBYTES個十六進位制位元組（64 個字元）。 此變數目前被視為不可變的。 請勿公開設定此值。 建立一個具有加密安全性的隨機金鑰值有幾種方法，例如使用Unix指令：$ hexdump -vn32 -e'8/8 "%08X" "\n"' /dev/urandom。 設定此值後執行 maintenance/UpdateTOTPSecretsToEncryptedFormat.php 即可加密現有資料庫資料列。 請注意，此值一旦設定後，目前尚無法變更、亦無法更新現有的加密碼。 参见T403180以获取更多信息。
$wgOATHRecoveryCodesCount	10	（在版本1.45引入） 為指定使用者預設生成的復原碼的數量。
$wgOATHMaxRecoveryCodesCount	100	（在版本1.46引入） The maximum number of recovery codes that a user can have. Both permanent and temporary codes are counted for this limit.
$wgOATHAdditionalRecoveryCodesValidityDays	7	（在版本1.46引入） Number of days for which codes generated on Special:Recover2FAForUser will be valid.
$wgOATHMaxKeysPerUser	100	（在版本1.46引入） 每位使用者允許擁有的最大的金鑰數量。
$wgWebAuthnRelyingPartyID	null	設定依賴方的識別碼。若未定義，則預設為您的網域 。
$wgWebAuthnRelyingPartyName	null	設定依賴方的名稱。若未定義，則預設為您的網站名稱 。
$wgWebAuthnNewCredsDisabled	false	（在版本1.43引入） If true, new WebAuthn credentials (security keys and passkeys) cannot be added. See T354701 and git #1187476.
$wgOATHAuthDatabase	false	（在版本1.44移除） 数据库域。 仅用于某個多数据库环境。 在MediaWiki 1.42之後，您應使用 $wgVirtualDomainsMapping['virtual-oathauth'] 取代此選項。
$wgOATH2FARequiredGroupRemovalPages	[]	（在版本1.46引入） 一組頁面名稱的陣列，使用者可透過此處申請從需要雙重驗證（2FA）的群組中移除自身（以群組名稱為索引）。 頁面將連結至關於使用者需啟用雙重驗證（2FA）的通知。 若無相關群組的對應條目，則將採用*鍵。
$wgOATHPasswordlessLogin	false	（在版本1.46引入） Allow passwordless login with passkeys.

OATHAuth 同時在 $wgRateLimits 陣列中新增一項鍵值，用以定義驗證嘗試的速率限制：

		'badoath' => [
			'&can-bypass' => false,
			'user' => [ 10, 60 ],
			'user-global' => [ 10, 60 ],
		]

請注意，user-global 鍵僅在 1.35 版本之後才可用。 早期版本必須依賴 user，或許還需要 ip-all。 詳情請參閱 $wgRateLimits 的文檔說明。

用户許可

用户权限	描述	預設授予
oathauth-enable	允許使用者們為其帳戶啟用雙因素認證，透過使用Special:AccountSecurity。	user
oathauth-disable-for-user	允許受信任人士為其他使用者帳戶移除雙重驗證功能，透過使用Special:DisableOATHForUser。	sysop
oathauth-recover-for-user	（在版本1.46引入） 擁有此權限的使用者可(使用Special:Recover2FAForUser)為其他使用者生成額外的復原碼，以協助他們在遺失所有雙重驗證方式時恢復帳戶的存取權限。	sysop
oathauth-verify-user	允許某些使用者可以查驗另一使用者是否已在其帳戶上啟用雙重認證，透過使用Special:VerifyOATHForUser。	sysop
oathauth-view-log	授予存取至Special:Log/oath的權限，該處記錄所有與雙重驗證相關的行政操作。	sysop

管理

重置用户令牌

在用户遺失了令牌生成器“和”恢复令牌這樣的事件中，双因素身份验证可通过运行disableOATHAuthForUser维护脚本而从用户身上移除：

MediaWiki版本：

1.40

$ ./maintenance/run OATHAuth:disableOATHAuthForUser <user>

MediaWiki版本：

≤ 1.39

$ php ./extensions/OATHAuth/maintenance/disableOATHAuthForUser.php <user>

Where ‎<user> is the name of the user to have 2FA disabled.

Local development

To be able to create WebAuthn keys and log in with them, the wiki must be accessed over HTTPS, even if it lives on localhost. This means that a typical setup where the wiki's URL is http://localhost:8080 will not work, and you will need to set up an HTTPS proxy. If you're using MediaWiki-Docker, follow the HTTPS recipe, then use https://localhost:8443 to visit your wiki. If you're not using MediaWiki-Docker, install Caddy, and put the following in /etc/caddy/Caddyfile:

localhost:8443 {
    reverse_proxy 127.0.0.1:8080
    tls internal
}

This will proxy https://localhost:8443 to http://localhost:8080. If needed, change 8080 to the port MediaWiki normally runs on.

Shared database tables

警告：	Due to limitations in the WebAuthn API, multi-wiki setups require special handling. See the "Cross-wiki support" section below.

Some Wikis may want to share the 2FA data amongst multiple Wikis. Shared database tables , the previous method for doing so is deprecated in MediaWiki 1.42 and later. For new wiki-farm installations where you want users to share their 2FA token amongst multiple wikis, please use $wgVirtualDomainsMapping and the extensions will automatically make its tables use the specified database name.

$wgVirtualDomainsMapping['virtual-oathauth'] = [ 'db' => 'sharedbname' ]

When using shared database tables, i.e., the same set of users for different wikis, add oathauth_devices and oathauth_types to $wgSharedTables.

$wgSharedTables[] = 'oathauth_devices';
$wgSharedTables[] = 'oathauth_types';

Cross-wiki support

By default, users may only use their security key to log in to the wiki where they initially registered the key. Attempting to log in on another wiki within the wiki family results in an error about an unrecognized key and restricts where the user can log in to only the wiki where they registered their key. Limited support exists for wiki families (those with $wgVirtualDomainsMapping['virtual-oathauth'] configured) sharing the same root domain. System administrators must first configure support for this by defining both $wgWebAuthnRelyingPartyID and $wgWebAuthnRelyingPartyName. The Relying Party ID must be set to your root domain.

• For example, if you have wikis at a.example.org, b.example.org, and c.example.org, the root domain is example.org and must be set as the ID. The Relying Party name can be anything, but ideally, it should be the name of your wiki family.

Wiki families that cross different domains are supported through the "shared domain" feature in CentralAuth . This is how the Wikimedia wiki family is set up, but this feature is not well documented for third-party reuse at this time.

WebAuthn browser support

A list of all WebAuthn supported web browsers can be found on Mozilla Developer Network. There are some known issues with Firefox on Linux (T415089).

Historical information

The OATHAuth extension originally provided support for TOTP, which started as a protocol for generating 6-digit, one-time verification codes, but became more generic over time. The messages in the OATHAuth user interface prefer the generic, more commonly-used terms: "authenticator app" instead of "TOTP", and "passkey" or "security key" instead of "WebAuthn key". However, the extension's code still uses "TOTP" and "WebAuthn" in module names.

The WebAuthn extension was previously a separate module, but it was combined into the OATHAuth extension in late 2025 as part of MediaWiki 1.46.

參見

• 产品安全性和完整性/帐户安全
• 双因素身份验证(TFA)
• 開放認證倡議(OATH)