Extension:OATHAuth

混同しないでください: Extension:OAuth。

MediaWiki 拡張機能マニュアル

OATHAuth リリースの状態: 安定
実装	利用者権限 , 特別ページ , ページの操作
説明	ログイン時における二要素認証を提供します。
作者	Ryan Lane
最新バージョン	アップデートが継続中
互換性の方針	スナップショットが MediaWiki とともにリリースされます。 master には後方互換性がありません。
データベースの変更	はい
仮想ドメイン	virtual-oathauth
テーブル oathauth_types oathauth_devices oathauth_users
パラメーター $wgOATHMaxRecoveryCodesCount $wgOATHAuth2FAForAllWarnings $wgOATHInitialRecoveryCodesValidityDays $wgOATHAuthEnforce2FAForAll $wgOATHAdditionalRecoveryCodesValidityDays $wgOATH2FARequiredGroupRemovalPages $wgOATHMaxKeysPerUser $wgWebAuthnRelyingPartyID $wgWebAuthnNewCredsDisabled $wgWebAuthnRelyingPartyName $wgOATHAuthWindowRadius $wgOATHSecretKey $wgOATHPasswordlessLogin $wgOATHAuthAccountPrefix $wgOATHRecoveryCodesCount
追加する権限 oathauth-enable oathauth-api-all oathauth-disable-for-user oathauth-view-log oathauth-verify-user
使用するフック AuthChangeFormFields BeforePageDisplay GetPreferences LoadExtensionSchemaUpdates ReadPrivateUserRequirementsCondition SiteNoticeAfter UnitTestsAfterDatabaseSetup UnitTestsBeforeDatabaseTeardown UserModifyCreateAccountEmail UserRequirementsCondition
ライセンス GNU 一般公衆利用許諾書 2.0 以降 GNU 一般公衆利用許諾書 3.0 以降
ダウンロード	拡張機能をダウンロード Git [?]: リポジトリを参照 (Phabricator · GitHub) Gerrit コード レビュー Git コミット ログ Download source tarball
translatewiki.net で翻訳を利用できる場合は、OATHAuth 拡張機能の翻訳にご協力ください
問題点	未解決のタスク · バグを報告

OATHAuth 拡張機能は、二要素認証 (2FA) 機能を提供します。 MediaWikiの利用者は、通常のパスワードと共に認証アプリ・セキュリティキー・パスキーを使用することで、より安全にログインできるようになります。 OATH（Initiative for Open Authentication）とWebAuthnの標準仕様を採用しています。

OATHAuth拡張機能では、以下の二要素認証手段が利用できます。

• パスワードマネージャーや認証アプリ
• パスキー
• セキュリティキー
• 回復コード

OATHAuth拡張機能には、パスワードログインの試験実装も含まれており、さらに他の拡張機能と連携可能な二要素認証フレームワークも提供します。

• この拡張機能は OAuth とは無関係であり、これは別のプロトコルです。
• 以前のWebAuthn 拡張機能は、本拡張機能に統合されました。

使用法

meta:Help:Two-factor authentication上のヘルプページは、利用者向けにこの拡張機能の使い方に関する情報を提供します。

meta:Help:Two-factor authenticationにて説明されている方針の一部は、ウィキメディアプロジェクトにのみ適用されます。 ただし、二要素認証機能の基本的な取り扱いについては、Extension:OATHAuthを使用するすべてのウィキと同一です。

Special:AccountSecurityは、二要素認証手段や回復コードを追加・管理する方法を、利用者に分かりやすく説明します。

インストール

この拡張機能は MediaWiki 1.31 以降に同梱されているため、ダウンロードする必要はありません。 残りの設定手順は必ず従ってください。

警告:	本拡張機能にはWeb（mw-config）アップデータでは正常にアップデートできないというバグが存在し、代わりにupdate.php によるコマンドラインアップデートスクリプトを使用する必要があります。 (phab:T371849)

OATHAuth拡張機能をインストールする前に、まずGMPphpまたはBCMathphpのどちらかをインストールしてください。 WebAuthn機能には、2つのうちどちらかは必須です。

• ダウンロードして、ファイルをextensions/フォルダー内のOATHAuthという名前のディレクトリ内に配置します。
  開発者とコード寄稿者は、上記の代わりに以下を使用してGitからインストールします:

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

• Gitでのインストールの場合のみ、PHPの依存関係をインストールするためComposerを実行します。 (合併症の可能性についてはT173141を参照。)
• 以下のコードを LocalSettings.php ファイルの末尾に追加します:

  wfLoadExtension( 'OATHAuth' );
  

• 更新スクリプトを実行します。このスクリプトは、この拡張機能が必要とするデータベーステーブルを自動的に作成します。
• 必要に応じて設定します。
• OATHAuthを運用する場合、キャッシュ も併せてセットアップすることが強く推奨されます。 パフォーマンスが改善するだけでなく、OATHAuthを利用している場合はセキュリティも向上します。 もし単一のアプリケーション/Webサーバーのみを実行中で、かつphp-apcuをインストールしており、さらに固有のキャッシュが設定されていない場合、MediaWikiはAPCuの使用を拒絶する可能性があります。 もし複数のアプリケーション/Webサーバーを使用している場合は、利用可能なすべてのホストでローカルクラスタ キャッシュをセットアップすることが推奨されます。 Memcached もその例に含まれます。
• 完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

設定の構成

パラメーター

構成フラグ	既定値	説明
$wgOATHAuthWindowRadius	4	有効であるべき各方向のトークン・ウィンドウの数。 実質的に((1 + 2 * $wgOATHAuthWindowRadius) * 30)秒の範囲でトークンを受け入れるよう、OATHに指示します。 有効なウィンドウの範囲は、現在時刻を中心にしています。 この変数は、利用者の時間とサーバーの時間の違いを考慮することを目的としています。 ただし、できるだけ少なくすることをおすすめします。
$wgOATHAuthAccountPrefix	false	OATHAuthのアカウント名に使用される接頭辞と、アカウントに適用される発行者。 falseの場合、$wgSitenameを使用します。
$wgOATHExclusiveRights	[]	(1.46 で除去) Set of permissions that are revoked from users who did not login using two-factor authentication.
$wgOATHRequiredForGroups	[]	(1.46 で廃止予定) Sets a list of user groups that are required to have two-factor authentication enabled. Use 'user' if you want all logged-in users required to enable two-factor authentication. This was deprecated in MediaWiki 1.46, and should be replaced by $wgRestrictedGroups ; see the example.
$wgOATHSecretKey	false	(1.45 で導入) Update to 1.45 (or later) and run the update script before enabling this feature and running its own maintenance script! A secret key value for encrypting OATH-related data which should be SODIUM_CRYPTO_SECRETBOX_KEYBYTES hexadecimal bytes (64 chars) in length. This variable is currently considered immutable. Do not publicly set this value. There are a few ways to create a cryptographically-secure, random key value, such as the unix command: $ hexdump -vn32 -e'8/8 "%08X" "\n"' /dev/urandom. Run maintenance/UpdateTOTPSecretsToEncryptedFormat.php after setting this value to encrypt existing database rows. Note that it is not currently possible to change this value once it is set, and be able to update existing encrypted codes. 詳細情報は T403180 を参照してください。
$wgOATHRecoveryCodesCount	10	(1.45 で導入) The default amount of recovery codes to generate for a given user.
$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 で導入) Maximum amount of keys allowed per user.
$wgWebAuthnRelyingPartyID	null	Configures relying party ID. If not defined, this defaults to your domain .
$wgWebAuthnRelyingPartyName	null	Configures relying party name. If not defined, this defaults to your sitename .
$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 で除去) データベースのドメイン。 複数のデータベースでのみ使用されます。 After MediaWiki 1.42, you should use $wgVirtualDomainsMapping['virtual-oathauth'] instead of this option.
$wgOATH2FARequiredGroupRemovalPages	[]	(1.46 で導入) An array of page names, where user can ask to have themselves removed from groups that require 2FA (keyed by the group name). The pages will be linked in the notice about 2FA being required for user. If there's no entry for the relevant group, key * will be used.
$wgOATHPasswordlessLogin	false	(1.46 で導入) Allow passwordless login with passkeys.

OATHAuth also adds a key to the $wgRateLimits array to define rate limits for authentication attempts:

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

user-globalキーはバージョン1.35からでしか使えないことに注意してください。 Earlier versions have to rely on user and perhaps 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>

‎<user>は、二要素認証が無効化された利用者の名前です。

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 Extension: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.

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

関連項目

• 製品安全と整合性/アカウントのセキュリティ
• 二段階認証試験者
• Initiative for Open Authentication (OATH)