Extension:OAuth

Not to be confused with Extension:OATHAuth.

MediaWiki extensions manual

OAuth Release status: stable
Implementation	User identity , User rights , API
Description	Allow users to safely authorize another application ("consumer") to use the MediaWiki action API on their behalf.
Compatibility policy	release branches
Database changes	Yes
Tables	oauth_accepted_consumer oauth_registered_consumer
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Download Git master browse repository (GitHub) commit history code review
Parameters $wgMWOAuthCentralWiki $wgMWOAuthSharedUserSource $wgMWOAuthRequestExpirationAge $wgMWOAuthSecureTokenTransfer $wgOAuthSecretKey $wgOAuthGroupsToNotify
Added rights mwoauthproposeconsumer mwoauthupdateownconsumer mwoauthmanageconsumer mwoauthsuppress mwoauthviewsuppressed mwoauthviewprivate mwoauthmanagemygrants
Hooks used ChangeTagCanCreate MergeAccountFromTo CentralAuthGlobalUserMerged LoadExtensionSchemaUpdates GetPreferences MessagesPreLoad SpecialPageAfterExecute SpecialPageBeforeFormDisplay BeforeCreateEchoEvent CentralAuthAbortCentralAuthToken TestCanonicalRedirect SetupAfterCache ApiRsdServiceApis SpecialPage_initList ListDefinedTags ChangeTagsListActive ApiCheckCanExecute RecentChange_save MarkPatrolled ApiBeforeMain
Hooks provided OAuthReplaceMessage
Translate the OAuth extension if it is available at translatewiki.net
Check usage and version matrix.
Vagrant role	oauth
Issues	Open tasks · Report a bug

The OAuth extension implements an OAuth server in MediaWiki that supports both the OAuth 1.0a and OAuth 2.0 protocol versions. It allows third party developers to securely develop applications ("consumers"), to which users can give a limited set of permissions ("grants"), so that the application can use the MediaWiki action API on the user's behalf.

If you're attempting to develop an application that uses OAuth on a wiki, see OAuth for Developers. If you are trying to use an OAuth-enabled tool on a wiki which has this extension installed, see Help:OAuth.

Requirements

• OAuth relies on the object cache for temporary tokens and sessions. This should work as long as cache configuration settings are sane. (Older versions required Memcached explicitly.)
• Currently, only mysql and sqlite database backends are supported
• If the mediawiki installation is private (i.e. users need to log in to have read access), Special:OAuth will need to be added to the white list.

Installation

• Download and place the file(s) in a directory called OAuth 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:

  wfLoadExtension( 'OAuth' );
  

• Run the update script which will automatically create the necessary database tables that this extension needs.
• Configure the general parameters as required.
• Configure the user rights by putting them into the relevant groups in $wgGroupPermissions.
•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

To users running MediaWiki 1.24 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension(). If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of wfLoadExtension( 'OAuth' );, you need to use:

require_once "$IP/extensions/OAuth/OAuth.php";

User rights

Right	Description
mwoauthproposeconsumer	User can propose a new Consumer
mwoauthupdateownconsumer	Modify a Consumer
mwoauthmanageconsumer	Approve a Consumer
mwoauthsuppress	Hide details about a Consumer
mwoauthviewsuppressed	View hidden details about a Consumer
mwoauthviewprivate	View private details about a Consumer, such as the hmac secret
mwoauthmanagemygrants	Right for users to manage what rights they have authorized for each Consumer. Typically, this right will not be granted to an OAuth Consumer.

To assign a permission to some group, for example to sysops, you add following line to LocalSettings.php:

$wgGroupPermissions['sysop']['mwoauthproposeconsumer'] = true;

Configuration

Variable name	Default value	Description
$wgMWOAuthCentralWiki	false	Wiki ID of OAuth management wiki. On wiki farms, it makes sense to set this to a wiki that acts as a portal site, is dedicated to management, or just handles login/authentication. It can, however, be set to any wiki if the farm. For single-wiki sites or farms where each wiki manages consumers separately, it should be left as false.
$wgMWOAuthSharedUserIDs	false	deprecated, use $wgMWOAuthSharedUserSource instead Whether shared global user IDs are stored in the oauth tables. On wiki farms with a central authentication system (with integer user IDs) that share a single OAuth management wiki, this must be set to true. If wikis have a central authentication system but have their own OAuth management, then this can be either true or false. Otherwise it should always be set to false. Setting this to true requires CentralIdLookup or an MWOAuth aware authentication extension. This value should not be changed after the fact to avoid ambigious IDs. Proper user ID migration should be done before any such changes.
$wgMWOAuthSharedUserSource	null	Central ID provider when sharing OAuth credentials over a wiki farm Source of shared user IDs, if enabled. If CentralIdLookup is available, this is the $providerId for CentralIdLookup::factory(). Generally null would be what you want, to use the default provider. If that class is not available or the named provider is not found, this is passed to the 'OAuthGetUserNamesFromCentralIds', 'OAuthGetLocalUserFromCentralId', 'OAuthGetCentralIdFromLocalUser', and 'OAuthGetCentralIdFromUserName' hooks. This has no effect if $wgMWOAuthSharedUserIDs is set to false.
$wgMWOAuthRequestExpirationAge	2592000 (30 days)	Seconds after which an idle request for a new Consumer is marked as "expired"
$wgMWOAuthSecureTokenTransfer	false	Require SSL/TLS for returning Consumer and user secrets. This is required by RFC 5849, however if a wiki wants to use OAuth, but doesn't support SSL, this option makes this configuration possible. This should be set to true for most production settings.
$wgOAuthSecretKey	$wgSecretKey	A secret configuration string (random 32-bit string generated using "base64_encode(random_bytes(32))") used to hmac the database-stored secret to produce the shared secrets for Consumers. This provides some protection against an attacker reading the values out of the consumer table (the attacker would also need $wgOAuthSecretKey to generate valid secrets), and some protection against potential weaknesses in the secret generation. If this string is compromised, the site should generate a new $wgOAuthSecretKey, which will invalidate Consumer authorizations that use HMAC/shared secret signatures instead of public/private keys. Consumers can regenerate their new shared secret by using the "Reset the secret key to a new value" option under Special:MWOAuthConsumerRegistration/update. If null, the value is set to $wgSecretKey.
$wgOAuthGroupsToNotify	[]	The list of user groups which should be notified about new consumer proposals. Setting this will only have an effect when Echo is installed.
$wgMWOauthDisabledApiModules	[]	List of API module classes to disable when OAuth is used for the request
$wgMWOAuthReadOnly	false	Prevent write activity to the database. When this is set, consumers cannot be added or updated, and new authorizations are prohibited. Authorization headers for existing authorizations will continue to work. Useful for migrating database tables
$wgMWOAuthSessionCacheType	$wgSessionCacheType	The storage mechanism for session data. If null, it defaults to $wgSessionCacheType.
$wgOAuth2EnabledGrantTypes	[ "authorization_code", "refresh_token", "client_credentials" ]	List of OAuth2 grants that client applications can be allowed to use. Actual grants client application will be allowed to use can be any subset of grants listed here. Grants, other than the ones listed here, are considered legacy grants, and are not supported by this extension
$wgOAuth2PrivateKey	""	Private key or a path to the private key used to sign OAuth2 JWT being transmitted.
$wgOAuth2PublicKey	""	Public key or a path to the public key used to verify OAuth2 resource requests.
$wgOAuth2RequireCodeChallengeForPublicClients	true	Controls whether clients are required to send code challenges with OAuth2 requests. This only applies to non-confidential clients.
$wgOAuth2GrantExpirationInterva	"PT1H"	Controls validity period for access tokens. Does not apply to owner-only clients, whose access tokens are always non-expiring. Accepts ISO 8601 durations or can be set to "infinity" or false for non-expiring tokens.
$wgOAuth2RefreshTokenTTL	"PT1M"	Controls validity period for refresh tokens. Accepts ISO 8601 durations or can be set to "infinity" or false for non-expiring tokens.

OAuth 2.0 REST enpoints

The following REST endpoints are provided for OAuth 2.0 interaction

Path	Description	Allowed parameters	Allowed method
/oauth2/authorize	Used for retrieving authorization code when using authorization_code grant.	response_type (required) client_id (required) redirect_uri (optional) - if present, must match the URI that was set when client was registered exactly scope (optional) state (optional) code_challenge (optional) - required if $wgOAuth2RequireCodeChallengeForPublicClients is true code_challenge_method (optional) - - required if $wgOAuth2RequireCodeChallengeForPublicClients is true	GET
/oauth2/access_token	Used for requesting access tokens	grant_type (required) - type of grant used client_id (optional) client_secret (optional) - required if client is confidential redirect_uri (optional) - if present, must match the URI that was set when client was registered exactly scope (optional) code (optional) - required if authorization_code grant is used refresh_token (optional) - required if refresh_token grant is used code_verifier (optional)	POST
/oauth2/resource/{{type}}	Used for retrieving protected resources using the access token issued previously. Currently, two resource types can be retrieved using this endpoint, by replacing {{type}}placeholder with the type key: profile - retrieve the user profile of the user that is represented by the access token used to make the request - usually used for logging users in on 3rd party websites using MediaWiki scopes - retrieve all scopes client (application) is allowed to use with the current access token	No parameters are allowed, apart from the {{type}} parameter that is included in the path	GET/POST

If OAuth credentials are shared over a wiki farm, make sure that real names are used/hidden consistently across all wikis (using $wgHiddenPrefs ). On wikis where real names are hidden, the OAuth permission request message that tells the user which information is shared does not mention the real name, so in that case there should not be any other wiki where the OAuth consumer may still get that information from.

See also

• Extension:OAuthAuthentication – A MediaWiki extension that lets your wiki delegate authentication to another wiki that is running Extension:OAuth.
• Extension:OATHAuth - A similarly named extension which implements a second authentication factor using OATH-based one-time passwords.
• oauthclient-php – a client library for OAuth consumers.