Extension:OATHAuth/ko

혼동하지 마세요: Extension:OAuth.

미디어위키 확장 기능 설명서

OATHAuth 출시 상태: 안정
구현	사용자 권한 , 특수 문서 , 문서 활동
설명	Provides two-factor authentication for logging in
만든 이	Ryan Lane
최신 버전	Continuous updates
호환성 정책	스냅샷은 미디어위키와 함께 릴리스됩니다. Master is not backward compatible.
데이터베이스 변경	예
가상 도메인	virtual-oathauth
테이블 oathauth_types oathauth_devices oathauth_users
변수 $wgOATHMaxRecoveryCodesCount $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 UnitTestsAfterDatabaseSetup UnitTestsBeforeDatabaseTeardown UserModifyCreateAccountEmail UserRequirementsCondition
라이선스 GNU General Public License 2.0 or later GNU General Public License 3.0 or later
다운로드	확장 기능 다운로드 Git [?]: 저장소 보기 (Phabricator · GitHub) Gerrit 코드 리뷰 Git 커밋 기록 Download source tarball
OATHAuth 확장 기능 번역 (translatewiki.net에서 가능한 경우)
이슈	미해결 작업 · 버그 보고

The OATHAuth extension provides two-factor authentication (2FA) support. It enables MediaWiki users to log in more securely, using authentication codes, security keys, or passkeys, along with their regular password. It uses the OATH (Initiative for Open Authentication) and WebAuthn standards.

OATHAuth supports the following methods of two-factor authentication:

• Password managers and authenticator apps
• Passkeys
• Security keys
• Recovery codes

OATHAuth also includes experimental support for passwordless login, and provides a 2FA framework that other extensions can plug into.

• This extension is unrelated to OAuth, which is a different protocol.
• The former WebAuthn extension has been merged into this extension.

Usage

The help page on Two-factor authentication provides information for end users on how to use this extension.

Some policies explained on Two-factor authentication only apply to Wikimedia projects. However, the basic instructions for using 2FA are the same for any wiki that uses Extension:OATHAuth.

The Special:AccountSecurity page guides users through adding and managing their two-factor authentication methods and recovery codes.

설치

이 확장 기능은 미디어위키 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)

Before you install OATHAuth, first install either the GMP php or BCMath php extension. WebAuthn functionality requires one of those two extensions.

• 파일을 다운로드하고 OATHAuth 폴더를 extensions/ 디렉토리에 넣어 주세요.
  개발자와 코딩 기여자는 Git을 이용해 확장기능을 다운받는 것이 좋습니다.

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

• Git에서 설치할 경우, PHP 의존 기능을 설치하려면 Composer를 실행하여 확장 기능 디렉터리에 composer install --no-dev를 발행하십시오. (잠재적인 문제에 대해서는 T173141 을 참고하십시오.)
• 아래의 코드를 LocalSettings.php 코드의 마지막에 추가합니다.

  wfLoadExtension( 'OATHAuth' );
  

• 갱신 스크립트를 실행합니다. 이 스크립트는 이 확장기능을 필요로 하는 데이터 베이스 테이블을 자동적으로 작성합니다.
• Configure as required.
• It is strongly recommended to setup caching when using OATHAuth. This will improve performance, but also the security of your wiki if you're using OATHAuth. If you are only running one application/web server and have php-apcu installed, and no specific cache configured, MediaWiki will likely fallback to using APCu. If you are using multiple application/web server it is advised to set up local cluster caching that all hosts can use. Examples include Memcached .
• 완료 – 위키의 ‘Special:Version’에 이동해서, 확장기능이 올바르게 설치된 것을 확인합니다.

Configuration

Parameters

Configuration Flag	Default Value	Description
$wgOATHAuthWindowRadius	4	The number of token windows in each direction that should be valid. This tells OATH to accept tokens for a range of effectively ((1 + 2 * $wgOATHAuthWindowRadius) * 30) seconds. This range of valid windows is centered around the current time. The purpose of this configuration variable is to account for differences between the user's and server's clock. However, keeping it as low as possible is recommended.
$wgOATHAuthAccountPrefix	false	The prefix used for the OATHAuth user account name and the issuer used for the account. If false, the value of $wgSitename is used.
$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. See T403180 for more information.
$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 에서 제거됨) The database domain. Only used in a multi-database environment. 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 ],
		]

Note that the user-global key is available only since 1.35. Earlier versions have to rely on user and perhaps ip-all. See the documentation of $wgRateLimits for details.

User permissions

User right	Description	Given by default to
oathauth-enable	Allows users to configure two-factor authentication on their account, using Special:AccountSecurity.	user
oathauth-disable-for-user	Enables trusted people to remove two-factor authentication from other user's account, by using Special:DisableOATHForUser.	sysop
oathauth-recover-for-user	(1.46버전부터 도입됨) Users with this right can generate additional recovery codes (using Special:Recover2FAForUser) for other users, helping them to recover access to their account if they lose all their 2FA methods	sysop
oathauth-verify-user	Allows users to check if another user has two-factor authentication enabled on their account, using Special:VerifyOATHForUser.	sysop
oathauth-view-log	Grants access to Special:Log/oath, where all administrative operations related to two-factor authentication are recorded.	sysop

Administration

Resetting a user token

If a user loses both their token generator and the recovery tokens, two-factor authentication may be removed from the user by running the disableOATHAuthForUser maintenance script:

미디어위키 버전:

1.40

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

미디어위키 버전:

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

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

See also

• Product_Safety_and_Integrity/Account_Security
• Two-factor authentication (TFA)
• Initiative for Open Authentication (OATH)

References