Extension:WSOAuth

From MediaWiki.org
Jump to navigation Jump to search
PluggableAuth Icon.svg This extension requires the PluggableAuth extension to be installed first.
MediaWiki extensions manual
OOjs UI icon advanced.svg
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
  • $wgOAuthUri
  • $wgOAuthClientId
  • $wgOAuthClientSecret
  • $wgOAuthRedirectUri
  • $wgOAuthCustomAuthProviders
  • $wgOAuthAuthProvider
  • $wgOAuthAutoPopulateGroups
  • $wgOAuthMigrateUsersByUsername
Translate the WSOAuth extension
Check usage and version matrix.

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[edit]

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[edit]

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[edit]

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>/wiki/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>/wiki/index.php?title=Special:OAuth';

Facebook[edit]

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[edit]

WSOAuth performs additional checks to protect users account unauthorised 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[edit]

This extension requires the PluggableAuth extension.
  • 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 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.
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

See also[edit]