Rozszerzenie:OATHAuth

**Podręcznik rozszerzeń MediaWiki**
OATHAuth; Status wydania: stabilne
Realizacja	Uprawnienia użytkownika, Strona specjalna, Akcja strony
Opis	Wprowadza weryfikację dwuetapową podczas logowania
Autor(zy)	Ryan Lane
Ostatnia wersja	Ciągłe aktualizacje
Polityka zgodności	Snapshots releases along with MediaWiki. Master nie jest kompatybilny wstecznie.
Zmiany w bazie danych	Tak
Domena wirtualna	virtual-oathauth
	Tabele oathauth_types; ; oathauth_devices; ; oathauth_users;
	Parametry $wgOATHRequiredForGroups; $wgWebAuthnNewCredsDisabled; $wgWebAuthnRelyingPartyName; $wgOATH2FARequiredGroupRemovalPages; $wgOATHMaxKeysPerUser; $wgWebAuthnRelyingPartyID; $wgOATHAuthWindowRadius; $wgOATHRecoveryCodesCount; $wgOATHAuthAccountPrefix; $wgOATHSecretKey; $wgOATHPasswordlessLogin; $wgOATHExclusiveRights; $wgOATHPrioritizedModules;
	Dodawane uprawnienia oathauth-enable; oathauth-api-all; oathauth-disable-for-user; oathauth-view-log; oathauth-verify-user;
	Użyte haki AuthChangeFormFields; BeforePageDisplay; GetPreferences; LoadExtensionSchemaUpdates; ReadPrivateUserRequirementsCondition; UnitTestsAfterDatabaseSetup; UnitTestsBeforeDatabaseTeardown; UserEffectiveGroups; UserGetRights; UserRequirementsCondition; getUserPermissionsErrors;
	Licencja ; Licencja GNU General Public License 2.0 lub nowsza; Licencja GNU General Public License 3.0 lub nowsza;
Pobieranie	Pobierz rozszerzenie ; Git [?]: przeglądaj repozytorium (GitHub); ocena kodu; historia wprowadzeń; Download source tarball;
	Przetłumacz rozszerzenie OATHAuth jeżeli jest dostępne na translatewiki.net
Problemy	Otwarte zadania · Zgłoś błąd

This page is a translated version of the page Extension:OATHAuth and the translation is 30% complete.

Outdated translations are marked like this.

Rozszerzenie OATHAuth zapewnia wsparcie dla uwierzytelniania dwuskładnikowego. 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.

To rozszerzenie nie ma nic wspólnego z OAuth, który jest zupełnie innym protokołem.
The former WebAuthn extension has been merged into this extension.

Użycie

Strona pomocy na temat uwierzytelniania dwuskładnikowego zawiera informacje dotyczące używania tego rozszerzenia przez użytkowników końcowych.

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.

Instalacja

This extension comes with MediaWiki 1.31 and later, so you do not need to download it. The remaining configuration instructions must still be followed.

Uwaga:

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.

Pobierz i umieść plik(i) w katalogu o nazwie OATHAuth w folderze extensions/.
Developers and code contributors should install the extension from Git instead, using:
```
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/OATHAuth
```
Tylko w przypadku instalacji z repozytorium git należy uruchomić Composer, aby zainstalować zależności PHP, poprzez wywołanie composer install --no-dev w katalogu rozszerzenia. (Zobacz T173141 w celu uzyskania informacji o możliwych komplikacjach.)
Dodaj poniższy kod na dole twojego pliku LocalSettings.php :
```
wfLoadExtension( 'OATHAuth' );
```
Uruchom skrypt aktualizujący, który automatycznie stworzy potrzebne tabele dla tego rozszerzenia.
Skonfiguruj zgodnie z wymaganiami.
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 .
Zrobione – Przejdź do Special:Version na twojej wiki, aby sprawdzić czy rozszerzenie zostało pomyślnie zainstalowane.

Konfiguracja

Parametry

Zmienna konfiguracyjna	Wartość domyślna	Opis
`$wgOATHAuthWindowRadius`	`4`	Liczba kodów (tokenów) w każdym kierunku, która powinna być ważna. Wymusza to akceptowanie przez OATH kodów z zakresu `((1 + 2 * $wgOATHAuthWindowRadius) * 30)` sekund. Zakres ten jest wyśrodkowany wokół bieżącego czasu. Zadaniem tej zmiennej konfiguracyjnej jest uwzględnienie różnic pomiędzy zegarem w urządzeniu użytkownika a zegarem serwera. Aczkolwiek zaleca się, aby jej wartość była możliwie mała.
`$wgOATHAuthAccountPrefix`	`false`	Prefiks wykorzystywany w nazwie użytkownika OATHAuth Jeśli wartość tej zmiennej to `false`, to używana jest zmienna `$wgSitename`.
`$wgOATHExclusiveRights`	`[]`	Lista uprawnień odbieranych, gdy użytkownik nie jest zalogowany z wykorzystaniem uwierzytelniania dwuskładnikowego.
`$wgOATHRequiredForGroups`	`[]`	Lista grup użytkowników, którzy muszą używać uwierzytelniania dwuskładnikowego. Należy użyć opcji „user”, aby włączyć uwierzytelnianie dwuskładnikowe wszystkim użytkownikom.
`$wgOATHSecretKey`	`false`	(wprowadzono w 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`	The default amount of recovery codes to generate for a given user.
`$wgOATHMaxKeysPerUser`	`100`	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`	If `true`, new WebAuthn credentials (security keys and passkeys) cannot be added, see T354701 and git #1187476.
`$wgOATHAuthDatabase`	`false`	(przestarzałe) Domena bazy danych. Zmienna wykorzystywana tylko w środowiskach z wieloma bazami danych. After MediaWiki 1.42, you should use $wgVirtualDomainsMapping['virtual-oathauth'] instead of this option.
`$wgOATH2FARequiredGroupRemovalPages`	`[]`	(wprowadzono w 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.

OATHAuth dodaje również klucz do tablicy $wgRateLimits w celu ustalenia maksymalnej ilości prób uwierzytelnienia:

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

Należy zauważyć, że klucz user-global jest dostępny od wersji 1.35. Wcześniejsze wersje muszą używać klucza user oraz, ewentualnie, ip-all. Zobacz dokumentację $wgRateLimits, aby uzyskać szczegółowe informacje.

Uprawnienia użytkowników

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`	(wprowadzono w 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`

Administracja

=== Resetowanie tokenów użytkownika ===

W przypadku, gdy użytkownik utraci zarówno swoje urządzenie uwierzytelniające ORAZ kody zapasowe, uwierzytelnianie dwuskładnikowe może zostać wyłączone dla jego konta poprzez usunięcie odpowiadającego mu wiersza z tabeli disableOATHAuthForUser w bazie danych.

Wersja MediaWiki:

1.40

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

Wersja 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

Uwaga:

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^[1], 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 2025.^[2]

Zobacz też

References

↑ OATH is the acronym for Open Authentication, which is the organization that created the standards for the HOTP and TOTP protocols that this extension provides.
↑ T303495

To rozszerzenie jest wykorzystywane przez jeden lub więcej projektów Wikimedia. Oznacza to prawdopodobnie, że to rozszerzenie jest stabilne i działa wystarczająco dobrze, aby wykorzystywać je na stronach o dużym natężeniu ruchu. Odnajdź nazwę tego rozszerzenia w plikach konfiguracyjnych Wikimedia CommonSettings.php oraz InitialiseSettings.php, aby zobaczyć gdzie są zainstalowane. Pełną listę rozszerzeń zainstalowanych na określonej wiki można znaleźć na stronie Special:Version na danej wiki.

To rozszerzenie jest dołączone do następujących farm/hostów wiki lub pakietów:

[oath-1] OATH is the acronym for Open Authentication, which is the organization that created the standards for the HOTP and TOTP protocols that this extension provides.

[2] T303495

[1]

[2]