Extension:OATHAuth

MediaWiki extensions manual

OATHAuth Release status: stable
Implementation	User rights , Special page , Page action
Description	Provides two-factor authentication for logging in
Author(s)	Ryan Lane
Latest version	Continuous updates
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
Database changes	Yes
Tables	oathauth_types oathauth_devices oathauth_users
License	GPL-2.0-or-later AND GPL-3.0-or-later
Download	Download extension Git [?]: Browse repository (Phabricator · GitHub) Gerrit code review Git commit log Download source tarball
Parameters $wgOATHRequiredForGroups $wgOATHRolloutPercent $wgOATHAllowMultipleModules $wgOATHExclusiveRights $wgOATHSecretKey $wgOATHAuthWindowRadius $wgOATHAuthNewUI $wgOATHAuthAccountPrefix $wgOATHPrioritizedModules
Added rights oathauth-enable oathauth-api-all oathauth-disable-for-user oathauth-view-log oathauth-verify-user
Hooks used AuthChangeFormFields GetPreferences LoadExtensionSchemaUpdates UnitTestsAfterDatabaseSetup UnitTestsBeforeDatabaseTeardown UserEffectiveGroups UserGetRights getUserPermissionsErrors
Translate the OATHAuth extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

The OATHAuth^[1] extension provides two-factor authentication support. By default, this includes a time-based one-time password (TOTP) implementation that allows users to generate 2FA codes from their phone or desktop app. Client support is available for most feature phones, smartphones, and desktops.

The help page on Two-factor authentication provides information for end users on how to use this extension. The Special:AccountSecurity page guides users through adding and managing their two-factor authentication methods and recovery codes.

Warning:

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)

• Download and move the extracted OATHAuth folder to your extensions/ directory.
  Developers and code contributors should install the extension from Git instead, using:

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

• Only when installing from Git, run Composer to install PHP dependencies, by issuing composer install --no-dev in the extension directory. (See T173141 for potential complications.)
• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'OATHAuth' );
  

• Run the update script which will automatically create the necessary database tables that this extension needs.
• 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 .
• Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

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 ip-all. See the documentation of $wgRateLimits for details.

Granting access to enable OATHAuth

Users should be given access to the oathauth-enable user right so that they can enable it at Special:OATHAuth (a link to which appears at Special:Preferences).

$wgGroupPermissions['user']['oathauth-enable'] = true;

The above will grant all registered users access to enable OATHAuth.

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:

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

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

Where ‎<user> is the name of the user to have 2FA disabled.

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';

• Product Safety and Integrity/Account Security
• Two-factor authentication (TFA)
• Extension:WebAuthn - module for the OATHAuth extension that provides support for U2F devices (such as YubiKey) and password managers.
• Initiative for Open Authentication (OATH)

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.

This extension is included in the following wiki farms/hosts and/or packages: BlueSpice Canasta Debian Miraheze MyWikis ProWiki semantic::core wiki.gg WikiForge This is not an authoritative list. Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here. Always check with your wiki farms/hosts or bundle to confirm.