Configuring OAuth Authentication in MediaWiki for Secure Logins

Why OAuth matters for MediaWiki logins

When you run a wiki that anyone can join, the old‑school username/password combo starts to feel a bit… rusty. A compromised password can open the whole site to vandalism, and keeping track of password policies across dozens of installs is a headache. OAuth offers a neat middle‑ground: users authenticate with a trusted provider (Google, GitHub, a corporate IdP) while MediaWiki receives a short‑lived token that proves “this person is who they say they are”. In practice it means secure logins without the hassle of storing passwords locally.

Prerequisites before you dive in

• MediaWiki 1.35+ (the extension is kept in sync with LTS releases).
• Shell access to the wiki’s extensions directory and the ability to edit LocalSettings.php.
• A consumer application – that could be a custom OAuth client you built, or simply the “Consumer” that MediaWiki creates for you when you enable the extension.
• If you plan to use OAuth 2.0 (highly recommended), make sure the PHP OpenSSL extension is enabled; it’s used for signing JWTs.

Installing the OAuth extension

Grab the latest tarball from the MediaWiki Extension Distributor, or pull it straight from GitHub if you prefer the bleeding edge.

cd /path/to/mediawiki/extensions
git clone https://github.com/wikimedia/mediawiki-extensions-OAuth.git OAuth
cd OAuth
composer install   # only needed for the OAuth2 helper libraries

After the files are in place, add the extension to LocalSettings.php. A single line does the trick:

wfLoadExtension( 'OAuth' );

If you get a warning about missing Composer autoload, double‑check that you ran composer install inside the extension folder.

Basic OAuth 1.0 setup (quick‑and‑dirty)

MediaWiki ships with a built‑in consumer called CentralAuth. For a simple test you can just enable it and let the extension handle the rest.

$wgOAuthEnableCentralAuth = true;
$wgOAuthConsumerKey = 'mywiki';
$wgOAuthConsumerSecret = 'random‑generated‑secret';

Save the file, clear your cache (php maintenance/update.php), and you’ll see a new “Log in with OAuth” button on the login page. It’s a decent proof of concept, but in production you’ll want the finer‑grained controls described below.

Switching to OAuth 2.0 – the modern way

OAuth 2.0 adds an extra layer of security with PKCE, refresh tokens, and scopes that match the MediaWiki API. To turn it on, set a couple of globals and point the extension at your public/private key pair.

// Enable OAuth2
$wgOAuth2EnabledGrantTypes = [ 'authorization_code', 'refresh_token' ];
$wgOAuth2PublicKey = '/path/to/public.key';
$wgOAuth2PrivateKey = '/path/to/private.key';

// Optional: force PKCE for public clients
$wgOAuth2RequireCodeChallengeForPublicClients = true;

// Token lifetimes (in seconds)
$wgOAuth2RefreshTokenTTL = 1209600;   // 14 days
$wgOAuth2GrantExpirationInterval = 3600; // 1 hour

Generating a key pair is straightforward:

openssl genpkey -algorithm RSA -out private.key -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in private.key -out public.key
chmod 600 private.key
chmod 644 public.key

Make sure the key files are readable by the web server user but not world‑writable.

Registering a consumer (the “client”)

From the wiki UI, navigate to Special:OAuthConsumerRegistration. You’ll be asked for a few pieces of info:

• Callback URL – where the OAuth provider will send the user after authentication. For a typical MediaWiki login this is https://yourwiki.org/wiki/Special:OAuthCentralLogin.
• OAuth version – pick “OAuth 2.0”.
• Grant types – tick “Authorization Code” (and “Refresh Token” if you need long‑running access).
• Allowed scopes – at a minimum you’ll need read and write for API calls; add email if you want to pull user emails.

After you submit the form, MediaWiki spits out a client_id and _secret. Keep those somewhere safe – they’re the secret handshake between your wiki and the OAuth provider.

Storing the credentials securely

Hard‑coding secrets in LocalSettings.php is a common rookie move. A tidier approach is to keep them in an environment file and load them at runtime:

$wgOAuth2ClientID = getenv('MW_OAUTH_CLIENT_ID');
$wgOAuth2ClientSecret = getenv('MW_OAUTH_CLIENT_SECRET');

Then, on your server add something like .env (make sure it’s .gitignore‑ed):

MW_OAUTH_CLIENT_ID=abcdef123456
MW_OAUTH_CLIENT_SECRET=super‑secret‑stuff

Fine‑tuning permissions

OAuth introduces a handful of new user rights that you may want to grant only to trusted staff. They live under the “OAuth” namespace:

$wgGroupPermissions['sysop']['mwoauthmanageconsumer'] = true;
$wgGroupPermissions['staff']['mwoauthviewprivate'] = true;
$wgGroupPermissions['*']['mwoauthproposeconsumer'] = false; // disable open registration

Feel free to adjust those arrays – MediaWiki’s permission system is flexible enough that you can create a bespoke “oauthadmin” group if you like.

Testing the flow

Once the wiring is done, hit the login page and click “Log in with your provider”. You should be redirected to the provider’s consent screen, then back to Special:OAuthCentralLogin. If all goes well, you’ll see a banner like “You are now logged in as MyUsername via OAuth”. A quick sanity check: run an API query that requires authentication and verify it returns data.

curl "https://yourwiki.org/w/api.php?action=query&meta=userinfo&format=json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If the response contains your user info, you’ve nailed it.

Common pitfalls and how to dodge them

• Clock skew – OAuth tokens are timestamped; if your server’s clock is off by more than a few minutes, validation fails. Sync with NTP.
• Missing PKCE support – Some providers (like GitHub) require the code challenge even for confidential clients. Double‑check the provider docs and set $wgOAuth2RequireCodeChallengeForPublicClients = true; if needed.
• CSRF tokens – The MediaWiki login flow includes its own CSRF protection. If you embed the OAuth button inside a custom login form, make sure you preserve the returnto parameter; otherwise users bounce back to the homepage.
• Database schema – After enabling the extension, run php maintenance/update.php to create the oauth_* tables. Skipping this step yields cryptic “SQLSTATE[42S02]” errors.

Advanced: Central‑wiki OAuth for a federation

If you manage several wikis under the same umbrella (say, a university’s departmental sites), you can point them all at a single “central” wiki for authentication. Set these globals on each satellite wiki:

$wgMWOAuthCentralWiki = 'https://central.example.org';
$wgMWOAuthSecureTokenTransfer = true; // forces HTTPS for token exchange
$wgMWOAuthSharedUserSource = true;    // shares user IDs across the federation

The central wiki must have the OAuth extension enabled and a consumer registered for the satellites. Once the handshake is complete, a user authenticates once on the central site and is auto‑logged into all the satellites – a neat single‑sign‑on experience without needing a separate SSO solution.

Wrapping up

Configuring OAuth in MediaWiki isn’t just a “nice‑to‑have” feature; it’s a solid step toward a more secure, user‑friendly authentication model. By installing the extension, generating a key pair, registering a consumer, and tweaking a handful of globals, you get a login flow that leans on industry‑standard protocols instead of storing raw passwords.

Sure, the first run can feel a bit like juggling “client_id”, “client_secret”, and a few cryptic token errors, but once the pieces click together the result is smooth and, more importantly, safer for everyone who edits your wiki. If you run into hiccups, the MediaWiki extension page and the Phabricator tracker are gold mines of troubleshooting tips.

In short: pull the OAuth extension into your stack, fire up the config, and let your users log in with the accounts they already trust. Your wiki – and its edit history – will thank you.