By MW in mediawiki — 08 Feb 2025

Integrating OAuth Authentication in MediaWiki for Secure User Management

Why OAuth Matters for Your MediaWiki

Ever tried logging into a wiki with the same password you use for your email, social media, and that one forum you forgot you signed up for? Yeah, it feels risky. In the wake of a few high‑profile credential leaks earlier this year, admins are finally waking up to the idea that passwords alone aren’t enough. That’s where OAuth swoops in – a token‑based dance that lets users authenticate through a trusted third‑party, like Google, GitHub, or a corporate SSO, without ever handing the wiki your raw password.

In plain English: your wiki says, “Hey, I trust Google to tell me who you are,” and Google replies, “Sure thing, here’s a token. Keep it safe.” The wiki never sees the password, and you get the sweet convenience of a single sign‑on. For sites handling sensitive information – think internal documentation for a research lab or a community portal for a medical association – that extra layer can be the difference between “just another breach” and “we’ve got this under control.”

Getting Started: Extension Checklist

Before you dive into code, make sure you have the right extensions at your disposal. MediaWiki doesn’t ship with OAuth support out of the box, but the community has built solid tools:

PluggableAuth – a framework that lets you swap authentication mechanisms without rewriting core code.
OAuth – the official MediaWiki OAuth extension, handling the token exchange.
OAuthConsumer – optional, needed if you want your wiki to act as an OAuth client for another service.

All three play nicely together, but you can get away with just PluggableAuth and OAuth if you’re only interested in letting users sign in via external providers.

Installation in a Nutshell

Assuming you have a working MediaWiki installation (≥ 1.39 LTS is recommended), run the following on your server:


cd /var/www/mediawiki/extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PluggableAuth.git
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/OAuth.git
# Optional, if you need to be a consumer:
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/OAuthConsumer.git

Then drop the usual require_once lines into LocalSettings.php:


// Load the extensions
wfLoadExtension( 'PluggableAuth' );
wfLoadExtension( 'OAuth' );
wfLoadExtension( 'OAuthConsumer' ); // if you need it

Don’t forget to run the update script afterwards – otherwise you’ll get a nice “missing table” error that nobody wants to see.

Registering Your OAuth Client

Now comes the part that feels a bit like paperwork, but it’s actually pretty straightforward. You need to create an “OAuth consumer” – basically a record that tells the provider (Google, GitHub, Azure AD, etc.) who you are, what scopes you need, and where to send the user back after authentication.

Here’s a quick walkthrough for Google:

Head over to Google Cloud Console and create a new project (or use an existing one).
Enable the “Google+ API” (or the newer “People API”) – Google loves to rename things.
Under “Credentials”, click “Create OAuth client ID”. Choose “Web application”.
Set the Authorized redirect URIs to something like https://yourwiki.org/wiki/Special:OAuthRedirect. That’s where Google will send the token after the user consents.
Copy the Client ID and Client secret. Keep them safe – they’re the keys to your kingdom.

If you’re using GitHub or Azure AD the steps are similar: register an app, set the redirect URI, grab the client ID/secret.

Storing Secrets Securely

Never, ever paste the client secret directly into a public repo. A common trick is to keep them in a separate .pw file that’s .gitignored, then load them at runtime:


$secrets = parse_ini_file( __DIR__ . '/oauth-secrets.pw' );
$wgOAuthClientId = $secrets['client_id'];
$wgOAuthClientSecret = $secrets['client_secret'];

Even better, if your server supports environment variables (Docker, Kubernetes, etc.), pull them from $_ENV. That way you never have a secret lying around in a plaintext file.

Configuring PluggableAuth to Use OAuth

Now that the external provider knows about your wiki, flip the switch on the MediaWiki side. Below is a minimal but functional snippet you can drop into LocalSettings.php. Feel free to tinker – the comments are there for a reason.


// Enable PluggableAuth
$wgPluggableAuth_EnableLocalLogin = false; // we don’t want native password logins
$wgPluggableAuth_EnablePasswordReset = false;

// Tell PluggableAuth which auth plugin to use
$wgPluggableAuth_EmailPassword = false; // OAuth handles it

// Register the OAuth plugin
$wgAuth = new OAuthPluggableAuth();

// Set the OAuth provider details
$wgOAuthConsumerKey = $wgOAuthClientId; // from your secrets file
$wgOAuthConsumerSecret = $wgOAuthClientSecret;

// Which scopes do we need? For a wiki, usually just basic profile info.
$wgOAuthScopes = [ 'email', 'profile' ];

// Optional: map provider fields to MediaWiki user fields
$wgOAuthUserInfoMapping = [
    'username' => 'email', // use email as username (unique)
    'realname' => 'name',
    'email' => 'email',
];

// Optional: auto-create accounts on first login
$wgPluggableAuth_EnableAutoCreate = true;

That block is enough to get most wikis up and running with Google or GitHub. If you’re using a corporate SAML‑to‑OAuth bridge, you might need to add extra mapping rules – the extension is pretty flexible, but the docs (see the “OAuth” page on mediawiki.org) are worth a skim.

Fine‑Tuning the User Experience

Once the technical plumbing is in place, you’ll notice the login link now says “Log in with Google” (or whichever provider you chose). You can customize that text via the $wgOAuthLoginButtonLabel variable if you’re feeling fancy.

But there’s more you can do:

Multiple providers – you can register several consumers (Google, GitHub, Azure) and let users pick. Just add more OAuthPluggableAuth instances, each with its own $wgOAuthConsumerKey block.
Restrict domains – for corporate wikis you may only allow @yourcompany.com emails. Check the $wgOAuthAllowedEmailDomains setting.
Session timeout – control how long a token stays valid. The default is fairly generous, but you can tighten it via $wgOAuthTokenLifetime.

Remember, the goal isn’t just to “make it work”, but to make it feel seamless for your users. A little branding—like using your logo on the OAuth consent screen—goes a long way.

Debugging Common Pitfalls

OAuth can be a bit temperamental, especially when mixing providers with slightly different implementations. Here are a few hiccups I’ve run into (and survived):

Redirect URI mismatch – the dreaded “redirect_uri_mismatch” error. Double‑check that the URL in your provider console exactly matches the one MediaWiki uses, including trailing slashes.
Scope denial – if a user refuses to grant the email scope, MediaWiki won’t be able to create a username. You can either fall back to a manual username prompt or simply refuse login.
Token expiration – some providers give short‑lived tokens. If a user stays idle for too long, they’ll be bounced back to the provider. Adjust $wgOAuthTokenLifetime or implement a refresh‑token flow.
Duplicate usernames – when using email as the username, two accounts from different providers could clash. Adding a provider prefix (e.g., github:alice@example.com) solves this.

When in doubt, enable the debug log:


$wgDebugLogFile = "/var/log/mediawiki/debug.log";
$wgDebugLogGroups = [ 'OAuth' => '/var/log/mediawiki/oauth-debug.log' ];

Log files can get noisy, but they’ll show you the raw HTTP responses from the OAuth server – priceless when you’re chasing a mysterious 401.

Security Considerations Worth a Second Look

OAuth isn’t a silver bullet; you still need to keep the rest of your wiki locked down. Here are a few quick reminders that often slip through the cracks:

HTTPS everywhere – both your wiki and the redirect URI must be served over TLS. Anything else is a free pass for a man‑in‑the‑middle.
Least‑privilege scopes – only ask for what you need. If you don’t need the user’s profile picture, leave the profile scope out.
CSRF protection – MediaWiki already has built‑in tokens, but make sure any custom login pages you add don’t bypass them.
Audit logs – keep a record of OAuth logins (who, when, which provider). This helps spot anomalous activity fast.

And, as a final note: rotate your client secret at least once a year. It’s a small chore, but it can prevent a long‑term breach if a secret ever slips out.

Real‑World Example: A University Research Wiki

To illustrate, let’s look at a fictional (but plausible) scenario. The Computer Science department at Midstate University runs a MediaWiki for collaborative research notes. Historically, they used local accounts, which meant every graduate student had a password that needed to be reset every semester. After a phishing incident that exposed several student credentials, the sysadmin team decided to switch to Google OAuth, leveraging the university’s G Suite accounts.

Here’s what they did, in a nutshell:

Created a Google Cloud project named “MidstateResearchWiki”.
Registered the wiki’s domain (https://research.midstate.edu/wiki) as an authorized redirect.
Stored the client ID/secret in a .env file on the server.
Enabled PluggableAuth and OAuth as described above.
Added a custom login button that says “Log in with your university account”.
Configured $wgOAuthAllowedEmailDomains = [ 'midstate.edu' ] so only faculty, staff, and students could sign in.
Set up a nightly cron job to purge orphaned accounts (students who graduated and never logged in for 90 days).

The outcome? Over 200 users migrated in a week, password reset tickets dropped to zero, and the department’s audit logs now show a clean, single‑sign‑on trail for every edit. A win‑win.

Looking Ahead: OAuth 2.1 and Beyond

OAuth 2.0 is still the reigning champion, but the IETF is already drafting OAuth 2.1, which aims to tighten up some of the loose corners (like PKCE for public clients). MediaWiki’s extensions are already being updated to support those features, so keep an eye on the release notes.

If you’re building a new wiki from scratch, consider using PKCE even today – it adds an extra verification step that thwarts token‑interception attacks. The configuration is a bit more involved, but the extension’s OAuth2PKCE branch (still experimental) provides a decent starting point.

Final Thoughts

Integrating OAuth into MediaWiki isn’t just a “nice‑to‑have” upgrade; it’s becoming a baseline for responsible user management in an era where password fatigue is real. By leaning on reputable providers, you offload the heavy lifting of credential storage, password resets, and multi‑factor enforcement. The steps above walk you through a practical, production‑ready setup, complete with tips for troubleshooting and hardening your deployment.

Sure, there’s a learning curve – you’ll wrestle with client IDs, redirect URIs, and occasionally cryptic error messages. But once you’ve got it humming, you’ll wonder how you ever survived with plain‑old passwords. So, give OAuth a whirl, tighten those security bolts, and let your community focus on what truly matters: creating and sharing knowledge.