How to Configure MediaWiki for OAuth Authentication with External Providers

Introduction

MediaWiki ships with a powerful OAuth extension that can act as an OAuth server, but most sites want to delegate authentication to an existing identity provider – Google, Facebook, GitHub, Keycloak, or a corporate SSO. The OAuth2 Client and the WSOAuth extensions together provide a clean, standards‑compliant way to let users log in with any OAuth2 provider while keeping the wiki’s own permission model intact.

Prerequisites

• MediaWiki ≥ 1.35 (the extensions require at least this version).
• HTTPS access for the wiki – the OAuth flow must be secured; the OAuth2 Client can work without HTTPS only in a development environment.
• Composer installed on the server (required for both extensions).
• An account on the external provider and a registered OAuth application (client ID and secret).

1. Installing the extensions

Both extensions are installed via git and Composer. The steps are identical for a fresh MediaWiki installation.

cd /path/to/mediawiki/extensions
# Install WSOAuth (delegates authentication)
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/WSOAuth
# Install OAuth2 Client (acts as the OAuth2 consumer)
git clone https://github.com/United-Earth-Team/MW-OAuth2Client.git

After cloning, run Composer in each extension directory to pull the PHP dependencies.

cd WSOAuth && composer install --no-dev
cd ../MW-OAuth2Client && composer install --no-dev

Finally, enable the extensions from LocalSettings.php:

wfLoadExtension( 'PluggableAuth' ); // required by WSOAuth
wfLoadExtension( 'WSOAuth' );
wfLoadExtension( 'MW-OAuth2Client' );

Run the update script to create the needed tables:

php maintenance/update.php

2. Registering an OAuth application with the provider

Each provider has a small portal where you create a new “OAuth client”. The essential fields are:

• Client ID – the public identifier.
• Client secret – a confidential password.
• Redirect URI – the URL on your wiki that the provider will call after the user authorises. For the OAuth2 Client this is always Special:OAuth2Client/callback (full URL required).
• Requested scopes – e.g. openid email profile for Google.

Write down the client ID and secret; they will be used in the next step.

3. Configuring the OAuth2 Client for a specific provider

The $wgOAuth2Client array holds all configuration. Below is a minimal example for Google; similar blocks work for Facebook, GitHub, Keycloak, etc.

$wgOAuth2Client = [];

$wgOAuth2Client['client'] = [
    'id'     => 'YOUR_GOOGLE_CLIENT_ID',
    'secret' => 'YOUR_GOOGLE_CLIENT_SECRET',
];

$wgOAuth2Client['configuration'] = [
    'authorize_endpoint'    => 'https://accounts.google.com/o/oauth2/v2/auth',
    'access_token_endpoint' => 'https://oauth2.googleapis.com/token',
    'api_endpoint'          => 'https://openidconnect.googleapis.com/v1/userinfo',
    'redirect_uri'          => 'https://wiki.example.org/wiki/Special:OAuth2Client/callback',
    'username'              => 'email',   // JSON path inside the userinfo response
    'email'                 => 'email',   // same for e‑mail address
    'scopes'                => 'openid email profile',
];

// Optional: customise the login button text
$wgOAuth2Client['configuration']['service_name'] = 'Google';
$wgOAuth2Client['configuration']['service_login_link_text'] = 'Log in with Google';

For Facebook replace the endpoint URLs with https://www.facebook.com/v12.0/dialog/oauth and https://graph.facebook.com/v12.0/oauth/access_token, and use the appropriate JSON paths for username and email.

After saving LocalSettings.php reload Special:Version to confirm the extension is active.

4. Using WSOAuth for providers that do not speak the OAuth2 Client API

WSOAuth sits on top of the PluggableAuth framework. It is useful when you want to integrate a provider that offers a non‑standard flow, or when you need group synchronisation.

The configuration lives in $wgPluggableAuth_Config. A typical Facebook configuration looks like this:

$wgPluggableAuth_Config['facebook'] = [
    'plugin' => 'WSOAuth',
    'data'   => [
        'type'         => 'facebook',
        'clientId'     => 'YOUR_FB_APP_ID',
        'clientSecret' => 'YOUR_FB_APP_SECRET',
        'redirectUri'  => 'https://wiki.example.org/wiki/Special:PluggableAuthLogin',
    ],
    'buttonLabelMessage' => 'facebook-login-button-label',
];

Key points:

• type selects the built‑in provider (currently mediawiki or facebook); custom providers can be added by writing a subclass of WSOAuthProvider.
• The redirectUri must point to Special:PluggableAuthLogin – this is the entry point that WSOAuth uses after the external provider redirects back.
• Set $wgPluggableAuth_EnableAutoLogin = true; and $wgPluggableAuth_EnableLocalLogin = false; if you want the external provider to be the sole login method.

WSOAuth also supports automatic group population. Example:

$wgPluggableAuth_Config['facebook']['data']['autoPopulateGroups'] = [
    'mygroups' => ['editor', 'autoconfirmed'],
];
$wgPluggableAuth_Config['facebook']['groupsyncs'] = [
    'mygroupsync' => [
        'type'               => 'syncall',
        'groupAttributeName' => 'mygroups',
    ],
];

This will map a group attribute returned by the provider to MediaWiki groups, allowing you to keep permissions in sync with the external identity store.

5. Private wikis and whitelisting

If the wiki is not publicly readable you must add the special pages used by the extensions to $wgWhitelistRead. Otherwise the login flow will be blocked before it even starts.

$wgWhitelistRead = [
    'Special:OAuth2Client',
    'Special:OAuth2Client/callback',
    'Special:PluggableAuthLogin',
    'Special:Userlogin',
    'Main Page',
];

For a completely private wiki you will also want to disable anonymous read:

$wgGroupPermissions['*']['read'] = false;

Consult Manual:Preventing access for a full discussion of private‑wiki hardening.

6. Testing the login flow

1. Visit the wiki’s front page as an anonymous user.
2. Click the login button that now reads “Log in with Google” (or the text you configured).
3. You are redirected to the provider’s consent screen. Approve the request.
4. The provider redirects back to Special:OAuth2Client/callback. MediaWiki creates a local account (or links to an existing one) and logs you in.
5. Check that the account appears in Special:UserLogin and that your groups match the expected values.

If the flow fails, enable debug logging:

$wgDebugLogFile = "/var/log/mediawiki/debug.log";
$wgDebugLogGroups[] = 'OAuth2Client';
$wgDebugLogGroups[] = 'WSOAuth';

Inspect the log for messages such as “OAuth2 client token exchange failed”. Common problems are mismatched redirect URIs, missing scopes, or an incorrectly configured $wgSecretKey on the wiki.

7. Advanced topics

• PKCE for public clients – the OAuth2 Client respects $wgOAuth2RequireCodeChallengeForPublicClients. For mobile or JavaScript apps set this to true and the extension will automatically generate the code_challenge and code_verifier parameters.
• Refresh tokens – the extension stores refresh tokens in the session cache. Adjust $wgOAuth2RefreshTokenTTL if you need a longer lifetime.
• Multiple providers – you can register several entries in $wgOAuth2Client (e.g. google, github) and expose separate login links via MediaWiki:Logintext or custom skin hooks.
• Group synchronisation with WSOAuth – the syncall algorithm copies every group returned by the provider. For finer control write a custom synchroniser that implements the WSOAuthGroupSync interface.

8. Security checklist

1. Use HTTPS for both the wiki and the provider callback.
2. Keep $wgOAuth2Client['client']['secret'] out of version control – store it in a separate, protected file and include it at runtime.
3. Enable $wgMWOAuthSecureTokenTransfer = true (the default) to force TLS for the OAuth server side.
4. Limit the scopes to the minimum required (e.g. openid email instead of profile if you do not need the full profile).
5. Regularly audit the list of enabled extensions; the OAuth extensions are stable but should be kept up‑to‑date with MediaWiki releases.

Conclusion

By combining OAuth2 Client for standard OAuth2 providers and WSOAuth for more flexible or custom providers, MediaWiki can become a seamless part of any modern SSO ecosystem. The configuration lives entirely in LocalSettings.php, requires only a few dozen lines of PHP, and respects MediaWiki’s existing permission model, allowing you to keep fine‑grained control over groups, page protection, and private‑wiki behaviour. Follow the steps above, test each provider, and you’ll have a secure, user‑friendly login experience that scales from small community wikis to enterprise intranets.