Extension:OATHAuth

A ne pas confondre avec : Extension:OAuth.

Manuel des extensions MediaWiki

OATHAuth État de la version : stable
Implémentation	Droits utilisateur , Page spéciale , Action de page
Description	Fournit l'authentification à deux facteurs pour se connecter
Auteur(s)	Ryan Lane
Dernière version	Mises à jour continues
Politique de compatibilité	Versions ponctuelles alignées avec MediaWiki. Le master n'est pas compatible arrière.
Modifie la base de données	Oui
Domaine virtuel	virtual-oathauth
Tables oathauth_types oathauth_devices oathauth_users
Paramètres $wgOATHMaxRecoveryCodesCount $wgOATHAuthAllowUnversionedKeys $wgOATHAdditionalRecoveryCodesValidityDays $wgOATH2FARequiredGroupRemovalPages $wgOATHMaxKeysPerUser $wgWebAuthnRelyingPartyID $wgWebAuthnNewCredsDisabled $wgWebAuthnRelyingPartyName $wgOATHAuthWindowRadius $wgOATHSecretKey $wgOATHPasswordlessLogin $wgOATHAuthAccountPrefix $wgOATHRecoveryCodesCount
Droits ajoutés oathauth-enable oathauth-api-all oathauth-disable-for-user oathauth-view-log oathauth-verify-user
Accroches utilisées AuthChangeFormFields BeforePageDisplay GetPreferences LoadExtensionSchemaUpdates ReadPrivateUserRequirementsCondition UnitTestsAfterDatabaseSetup UnitTestsBeforeDatabaseTeardown UserRequirementsCondition
Licence Licence publique générale GNU v2.0 ou ultérieur Licence publique générale GNU v3.0 ou ultérieur
Téléchargement	Télécharger l'extension Git [?]: parcourir le dépôt (Phabricator · GitHub) relecture Gerrit du code historique Git des validations (commits) Télécharger le tarball source
Traduire l’extension OATHAuth sur translatewiki.net si elle y est disponible
Problèmes	Tâches ouvertes · Signaler un bogue

L'extension OATHAuth fournit la prise en charge de l'authentification à deux facteurs. 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.

• Cette extension n'a rien à voir avec OAuth qui utilise un protocole tout à fait différent.
• The former WebAuthn extension has been merged into this extension.

Utilisation

La page d'aide sur l'Authentification à deux facteurs donne aux utilisateurs finaux des informations sur la manière d'utiliser cette 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.

Installation

Cette extension est fournie avec MediaWiki 1.31 et supérieur. Les instructions de configuration restantes doivent encore être suivies.

Avertissement :

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.

• Téléchargez et placez le(s) fichier(s) dans un répertoire appelé OATHAuth dans votre dossier extensions/.
  Les développeurs et les contributeurs au code doivent à la place installer l'extension à partir de Git en utilisant:

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

• Seulement lorsque vous installez à partir de Git, exécutez Composer pour installer les dépendances PHP, en entrant composer install --no-dev après vous être positionné dans le répertoire de l'extension. (Voir T173141 pour des complications potentielles.)
• Ajoutez le code suivant à la fin de votre fichier LocalSettings.php  :

  wfLoadExtension( 'OATHAuth' );
  

• Exécutez le script de mise à jour qui va créer automatiquement les tables de base de données dont cette extension a besoin.
• Configurer si nécessaire.
• Il est fortement recommandé d'activer le cache lorsque vous utilisez OATHAuth. Ceci améliorera les performances et la sécurité de votre wiki si vous utilisez OATHAuth. Si vous n'exécutez qu'une seule application ou un serveur web et que php-apcu est installé, avec aucun cache spécifique configuré, il est probable que MediaWiki se replie sur l'utilisation de APCu. Si vous exécutez plusieurs applications ou serveurs web, nous vous conseillons de configurer le cache de la grappe locale utilisé par tous les hôtes. Les exemples incluent Memcached .
• Fait – Accédez à Special:Version sur votre wiki pour vérifier que l'extension a bien été installée.

Configuration

Paramètres

Indicateur de configuration	Valeur par défaut	Description
$wgOATHAuthWindowRadius	4	Nombre de fenêtres valides de jetons dans chaque direction. Cela indique à OATH d'accepter les jetons dans un intervalle effectif de ((1 + 2 * $wgOATHAuthWindowRadius) * 30) secondes. Cet intervalle de fenêtre valides est centré sur l'heure actuelle. Le but de cette variable de configuration est de tenir compte des différences entre l'horloge de l'utilisateur et l'horloge du serveur. Il est toutefois recommandé de la maintenir aussi basse que possible.
$wgOATHAuthAccountPrefix	false	Le préfixe utilisé pour le nom du compte utilisateur OATHAuth et l'émetteur utilisé pour le compte. Si false, la valeur de $wgSitename est utilisée.
$wgOATHExclusiveRights	[]	(supprimé en 1.46) Ensemble de permissions qui sont révoquées aux utilisateurs qui ne se sont pas connectés en utilisant l'identification à deux facteurs.
$wgOATHRequiredForGroups	[]	(obsolète depuis v. 1.46) Définit une liste de groupes utilisateurs nécessaires pour activer une authentification à deux facteurs. Mettre 'user' si vous souhaitez que tous les utilisateurs connectés puissent utiliser l'authentification à deux facteurs. This was deprecated in MediaWiki 1.46, and should be replaced by Manual:$wgRestrictedGroups ; see the example at Manual:$wgRestrictedGroups#Requiring 2FA for a user group .
$wgOATHSecretKey	false	(introduit dans 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	(introduit dans 1.45) The default amount of recovery codes to generate for a given user.
$wgOATHMaxRecoveryCodesCount	100	(introduit dans 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	(introduit dans 1.46) Number of days for which codes generated on Special:Recover2FAForUser will be valid.
$wgOATHMaxKeysPerUser	100	(introduit dans 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	(introduit dans 1.43) If true, new WebAuthn credentials (security keys and passkeys) cannot be added. See T354701 and git #1187476.
$wgOATHAuthDatabase	false	(supprimé en 1.44) Domaine de la base de données. Utilisé seulement pour un environnement multi base de données. After MediaWiki 1.42, you should use $wgVirtualDomainsMapping['virtual-oathauth'] instead of this option.
$wgOATH2FARequiredGroupRemovalPages	[]	(introduit dans 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	(introduit dans 1.46) Allow passwordless login with passkeys.

OATHAuth ajoute également une clef au tableau $wgRateLimits pour définir les limites de taux pour les tentatives d'authentification :

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

Notez-bien que la clé user-global n'est disponible que depuis la version 1.35. Les versions antérieures devaient s'appuyer sur user et peut être ip-all. Voir la documentation de $wgRateLimits pour plus de détails.

Droits utilisateur

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	(introduit dans 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

=== Réinitialiser un jeton utilisateur ===

Si un utilisateur perd à la fois son générateur de jetons ET les jetons de récupération : l'authentification à deux facteurs peut lui être retirée en exécutant le script de maintenance disableOATHAuthForUser :

Version de MediaWiki :

1.40

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

Version de MediaWiki :

≤ 1.39

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

Où ‎<user> est le nom de l'utilisateur pour désactiver 2FA.

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

Avertissement :

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.

Voir aussi

• Sécurité du produit et intégrité/Sécurité de compte
• Two-factor authentication (TFA)
• Initiative for Open Authentication (OATH)

References