Extension:WebAuthn

MediaWiki extensions manual

WebAuthn Release status: stable
Implementation	User rights , Special page
Description	Module for OATHAuth that enables support for authentication through the WebAuthn API
Author(s)	Dejan Savuljesku, Robert Vogel
Latest version	Continuous updates
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	1.34+
PHP	7.2+
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Browse repository (GitHub) Gerrit code review Git commit log Download source tarball
Parameters $wgWebAuthnRelyingPartyID $wgWebAuthnLimitPasskeysToRoaming $wgWebAuthnRelyingPartyName $wgWebAuthnNewCredsDisabled
Hooks used AuthChangeFormFields ResourceLoaderGetConfigVars
Translate the WebAuthn extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

WebAuthn is a module for the OATHAuth extension that provides support for U2F devices (such as YubiKey) and password managers (such as Bitwarden) by using the WebAuthn API in browsers. It enables support for logging in using physical security keys or passkeys, along with a regular password. Learn more about U2F on Wikipedia.

Warning:

Due to limitations in the WebAuthn API, multi-wiki setups require special handling. See the "Cross-wiki support" section below.

Installation

Basic

WebAuthn requires OATHAuth and either GMP php or BCMath php extensions to be installed first.

• Download and move the extracted WebAuthn 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/WebAuthn
  

• 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( 'WebAuthn' );
  

• Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

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.

Cross-wiki support

By default, users may only use their U2F 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 U2F 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 whatever, 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 WMF's wiki family is set up, but this feature is not well documented for third-party reuse at this time.

Configuration

parameter	default	comment
$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.

Browser support

A list of all supported web browsers can be found on Mozilla Developer Network.

Desktop

• Chrome 67+
• Edge 18+
• Firefox 60+

Mobile

• Android WebView 70+
• Chrome for Android 70+
• Firefox for Android 60+