Extension:WSOAuth

Not to be confused with Extension:OAuth.

This extension requires the PluggableAuth extension to be installed first.

It is recommended to only install WSOAuth from GitHub, instead of from the ExtensionDistributor, until T263955 is resolved.

MediaWiki extensions manual

WSOAuth Release status: stable
Implementation	User identity , User rights
Description	Extends the PluggableAuth extension to provide authentication using an OAuth provider
Author(s)	Xxmarijnwtalk (Wikibase Solutions) and others
Latest version	4.0 (2020-08-17)
Compatibility policy	master
MediaWiki	1.31+
PHP	7.0+
Database changes	Yes
License	MIT License
Download	GitHub: project page git repository URL [help ] commit history Note: No localisation updates are provided by translatewiki.net .
Parameters $wgOAuthUri $wgOAuthClientId $wgOAuthClientSecret $wgOAuthRedirectUri $wgOAuthCustomAuthProviders $wgOAuthAuthProvider $wgOAuthAutoPopulateGroups $wgOAuthMigrateUsersByUsername
Hooks used LoadExtensionSchemaUpdates PluggableAuthPopulateGroups
Hooks provided WSOAuthAfterGetUser WSOAuthBeforeLogout WSOAuthBeforeAutoPopulateGroups WSOAuthGetAuthProviders
Translate the WSOAuth extension
Check usage and version matrix.
Vagrant role	wsoauth

The WSOAuth extension extends the PluggableAuth extension to provide authentication using an OAuth provider. It provides a layer on top of PluggableAuth to enable authentication via OAuth. The following OAuth providers are currently available:

• MediaWiki OAuth (MediaWiki instance running OAuth)
• Facebook

WSOAuth makes it easier to add new OAuth providers. You can read more about how to add a new OAuth provider to the extension on WSOAuth for Developers.

The extension must be used with exactly one OAuth provider.

Configuration

Values must be provided for the following mandatory configuration variables:

Flag	Default	Description
$wgOAuthUri	no default value	The OAuth application authentication URL.
$wgOAuthClientId	no default value	The consumer key received from the OAuth application.
$wgOAuthClientSecret	no default value	The consumer secret received from the OAuth application.

In addition, the following optional configuration variables are provided:

Flag	Default	Description
$wgOAuthRedirectUri	no default value	The default callback URL to which the OAuth application returns after a successful authentication request.
$wgOAuthCustomAuthProviders	no default value	An array containing a list of custom OAuth providers together with their class name (see WSOAuth for Developers for more information).
$wgOAuthAuthProvider	mediawiki	The OAuth provider that the extension will use.
$wgOAuthAutoPopulateGroups	no default value	An array containing a list of MediaWiki group names that must be automatically assigned to the user after they are authenticated.
$wgOAuthMigrateUsersByUsername	false	Whether or not to allow usurpation of existing accounts. If a user is already registered on your wiki before installing WSOAuth with the same username as a user that is logging in via OAuth, this setting will determine whether that existing account will be given to the user signing in (true), or whether the user singing in through OAuth will be prevented from doing so because the user already exists (false). Once an account has been migrated, the user associated with that account will always be able to sign in through OAuth, even after this setting is changed to false.

OAuth providers

If you're attempting to add a new OAuth provider, see WSOAuth for Developers.

Currently, the following OAuth providers are supported:

• MediaWiki OAuth (MediaWiki instance running OAuth)
• Facebook

MediaWiki OAuth

Follow the steps below to enable authentication and authorization via MediaWiki OAuth.

1. Register a new OAuth application on the wiki you are delegating access to. Do not use an RSA key pair for authentication and let MediaWiki generate the secret for you. Use https://<local wiki url>/wiki/index.php?title=Special:PluggableAuthLogin as OAuth "callback" URL. Select User identity verification only, no ability to read pages or act on a user's behalf. under Types of grants being requested.
2. Write down the key and secret you received from MediaWiki.
3. Set the following in your LocalSettings.php:

$wgOAuthUri = 'https://<central wiki>/w/index.php?title=Special:OAuth';
$wgOAuthClientId = '<The client ID (key) you received from MediaWiki when you registered your app>';
$wgOAuthClientSecret = '<The secret you received from MediaWiki when you registered your app>';

To exclusively use MediaWiki as your sign-on system and to automatically log in when visiting the wiki, also set the following in LocalSettings.php:

$wgPluggableAuth_EnableAutoLogin = true;
$wgPluggableAuth_EnableLocalLogin = false;

For OAuth applications that utilize a "callback" prefix, a redirect URI must be set. This redirect URI must have the prefix specified:

$wgOAuthRedirectUri = 'https://<central wiki>/w/index.php?title=Special:OAuth';

Facebook

Follow the steps below to enable authentication and authorization via Facebook.

1. Create a new app on Facebook for Developers.
2. Under Add a Product, select Facebook Login.
3. In the menu on the left, select Settings under Facebook Login.
4. Add the domain of your wiki to the list of Valid OAuth Redirect URIs and hit save.
5. In the menu on the left, click Settings, then Basic and write down the App ID and App Secret.
6. Set the following in your LocalSettings.php:

$wgOAuthAuthProvider = 'facebook';
$wgOAuthUri = '';
$wgOAuthClientId = '<The App ID>';
$wgOAuthClientSecret = '<The App Secret>';
$wgOAuthRedirectUri = 'https://<wiki domain>/index.php/Special:PluggableAuthLogin';

To exclusively use Facebook as your sign-on system and to automatically log in when visiting the wiki, also set the following in LocalSettings.php:

$wgPluggableAuth_EnableAutoLogin = true;
$wgPluggableAuth_EnableLocalLogin = false;

Upgrading from before 3.0

WSOAuth performs additional checks to protect users from unauthorized account usurpation since WSOAuth 3.0. This is done by keeping track of users that have logged in through WSOAuth via the database.

This poses an issue for administrators upgrading to version 3.0, since users that have registered via WSOAuth will no longer be able to log in, because no record of them would exist in the WSOAuth database, unless $wgOAuthMigrateUsersByUsername is set to true. If you do not want to enable $wgOAuthMigrateUsersByUsername, you can use the maintenance script migrateUser.php located in the extension's maintenance folder to manually migrate certain or all users to WSOAuth:

$ php extensions/WSOAuth/maintenance/migrateUser.php --user 'Foobar'

$ php extensions/WSOAuth/maintenance/migrateUser.php --user '*' --migrate-all

Installation

This extension requires the PluggableAuth extension.

• If using Vagrant , install with vagrant roles enable wsoauth --provision

Manual installation

• Download and place the file(s) in a directory called WSOAuth in your extensions/ folder.
• Only when installing from git run Composer to install PHP dependencies, by issuing composer install --no-dev in the extension directory. (See task T173141 for potential complications.)
• Add the following code at the bottom of your LocalSettings.php:

  $wgGroupPermissions['*']['autocreateaccount'] = true;
  
  wfLoadExtension( 'PluggableAuth' );
  wfLoadExtension( 'WSOAuth' );
  

• Run the update script which will automatically create the necessary database tables that this extension needs.
• Configure as required.
•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

See also

• Extension:OAuthAuthentication - Also delegates authentication to a wiki that is an OAuth provider