Release status: stable
|Implementation||User rights, Special page, Page action|
|Description||Provides two-factor authentication for logging in|
|Latest version||Continuous updates|
|Compatibility policy||Snapshots releases along with MediaWiki. Master is not backward compatible.|
|License||GPL-2.0-or-later AND GPL-3.0-or-later|
|Translate the OATHAuth extension if it is available at translatewiki.net|
|Issues||Open tasks · Report a bug|
The OATHAuth extension is a time-based one-time password (TOTP) implementation. It provides two-factor authentication via something you have (your phone or desktop client) and something you know (your user name/password). Client support is available for most feature phones, smartphones and desktops (see Client implementations).
The help page on Two-factor authentication provides information for end users on how to use this extension. However the special page used will also guide users.
- Download and place the file(s) in a directory called
- Only when installing from git run Composer to install PHP dependencies, by issuing
composer install --no-devin the extension directory. (See task T173141 for potential complications.)
- Add the following code at the bottom of your LocalSettings.php:
wfLoadExtension( 'OATHAuth' );
- Run the update script which will automatically create the necessary database tables that this extension needs.
- Configure as required.
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
|Configuration Flag||Default Value||Description|
||The number of token windows in each direction that should be valid.
This tells OATH to accept tokens for a range of effectively
||The database domain. Only used in a multi-database environment.|
||The base OATHAuth secret for this wiki from which all encryption keys are derived.
||The prefix used for the OATHAuth user account name and the issuer used for the account.
||Set of permissions that are revoked from users who did not log in using two-factor authentication.|
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 version have to rely on
user and perhaps
See the documentation of
$wgRateLimits for details.
- Granting access to enable OATHAuth
$wgGroupPermissions['user']['oathauth-enable'] = true;
The above will grant all registered users access to enable OATHAuth.
- Resetting a user token
In the event that a user both loses their token generator AND the recovery tokens; two-factor authentication may be removed from the user by deleting their row from the
oathauth_users database table.
Alternatively, a sysadmin with shell access may type on a command line
cd /path/to/mediawiki/extensions/OATHAuth/maintenance/ and then execute
php disableOATHAuthForUser.php "username" where
"username" is the user to have 2FA disabled.
- Wikimedia Security Team/Two-factor Authentication for CentralAuth wikis
- Two-factor authentication (TFA)
|This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page.|