Extension:OAuth

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual - list
Crystal Clear action run.png
OAuth

Release status: beta

Implementation User identity, User rights, API
Description Allow users to safely authorize another application (Consumer) to use the MediaWiki api on their behalf.
MediaWiki 1.22+
Database changes yes
License GPL v2 or later
Download
Parameters

$wgMWOAuthCentralWiki
$wgMWOAuthGrantPermissions
$wgMWOAuthRequestExpirationAge

Added rights

mwoauthproposeconsumer
mwoauthupdateownconsumer
mwoauthmanageconsumer
mwoauthsuppress
mwoauthviewsuppressed
mwoauthviewprivate
mwoauthmanagemygrants

Translate the OAuth extension if possible

Check usage and version matrix; code metrics
Bugs: list open list all report

The OAuth extension implements OAuth 1.0a in MediaWiki. It allows third party developers to securely develop applications (Consumer), which users can grant a limited set of permissions (Grants) to, so that the application can use the MediaWiki API on the user's behalf.

NOTE: If you're attempting to develop an application and that uses OAuth on a wiki, see OAuth for Developers.

Requirements[edit | edit source]

  • OAuth relies on memcached for temporary tokens and sessions
  • Currently, only mysql database backend is supported

Download[edit | edit source]

You can download the extension directly from the MediaWiki source code repository (browse code). You can get:

One of the extensions tags

Not all extensions have tags. Some extensions have tags for each release, in which case those tags have the same stability as the release. To download a tag

  • Go to the tags list
  • Click the name of the tag you want to download
  • Click "snapshot"
The latest version of one of the extensions branches

Each extension has a master branch containing the latest code (might be unstable). Extensions can have further branches as well.

  • Go to the branches list
  • Click the branch name
  • Click "snapshot"
A snapshot made during the release of a MediaWiki version.

This might be unstable and is not guaranteed to work with the associated MediaWiki version.

After you've got the code, save it into the extensions/OAuth directory of your wiki.

If you are familiar with git and have shell access to your server, you can obtain the extension, with all its tags and branches, as follows:

cd extensions
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/OAuth.git

Installation[edit | edit source]

  • Download and extract the files in a directory called OAuth in your extensions/ folder. If you're a developer and this extension is in a Git repository, then instead you should clone the repository.
  • Add the following code at the bottom of your LocalSettings.php:
require_once( "$IP/extensions/OAuth/OAuth.php" );
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • Done! Navigate to "Special:Version" on your wiki to verify that the extension is successfully installed.

You will need to configure the user rights below into relevant groups in $wgGroupPermissions.

User rights[edit | edit source]

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.

Configuration[edit | edit source]

Variable name Default value Description
$wgMWOAuthCentralWiki false Wiki where OAuth grants are stored and Consumers registered, if this is a multi-wiki cluster
$wgMWOAuthSharedUserIDs false
$wgMWOAuthSharedUserSource false Extension to use as the source of shared user IDs if enabled
$wgMWOAuthGrantPermissions Groups of permissions (Grants)
$wgMWOAuthRequestExpirationAge 30 days (30 * 86400 seconds) 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 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.

Using OAuth[edit | edit source]

In order to use OAuth to make MediaWiki api calls on behalf of another user, you need to:

  1. Register your application (Consumer), and get it approved by a wiki admin
  2. Get the user's permission, and get a set of authorized tokens
  3. When making api calls, include an Authorization: HTTP header, which identify the user and prove your possession of the authorized token

An example php script that handles the technical portions of this can be found here: User:CSteipp/OAuth_demo_client

An example using flask-oauth: wikitech:Setting_up_Flask_cgi_app_as_a_tool/OAuth

Register your Consumer[edit | edit source]

  • To propose your Consumer, you must have the 'mwoauthproposeconsumer' right
    • On WMF wikis, this right is given to autoconfirmed accounts
  • Visit Special:OAuthConsumerRegistration/propose
  • Fill in the required information
    • Name and description: This is what your users will see when authorizing your application, along with your wiki username
    • Version: The permissions you grant are tied to a specific version of your application. You will increase the version number if you need to change grants later.
    • Callback URL: This is the url where user will be redirected after they have authorized your application in their web browser, with the verification code added as a GET parameter, and the temporary token to identify the user to you.
      • For bots, you will probably want to redirect the user to a page that will show the verification code back to the user, and have them cut-and-paste the verification code into the bot.
    • Grants: These are the permissions you application will use, if your user also has these rights.
      • Unless this is a demo application, you will need "Basic Rights" to use the MediaWiki api
      • Users can revoke individual grants from your application, so your application always needs to handle permission errors gracefully
    • Restrictions: The OAuth specification recommends that OAuth Consumers are restricted to a limited set of IP addresses. This protects your users, in case your secret key is compromised, and an attacker attempts to use the MediaWiki api on behalf of your users. This can be updated after your application is approved.

Get Your User's Permission[edit | edit source]

For a user (who you have authenticated in your application) to allow your application to use MediaWiki on their behalf, you will need to complete the 3-step OAuth protocol, and store the user-specific token and secret for that user. You will use the user-specific token, along with your application's token and secret on each API call, for MediaWiki to act on behalf of the user.

  • Step 1: Obtain a temporary token by calling Special:OAuth/initiate from your application
    • Caveat: When constructing your url, use /w/index.php?title=Special:OAuth/initiate instead of /wiki/Special:OAuth/initiate, because MediaWiki silently will create a title parameter that isn't included in your signature calculation.
  • Step 2: Direct the user's browser to /wiki/Special:OAuth/authorize, with the token from Step #1 as a GET parameter
  • Step 3: After the user has authorized your application and been redirected back to your application, exchange the verification code and the temporary token for a permanent authorized token

Identify the User (optional)[edit | edit source]

Your application can optionally identify the user who has authorized it by making a signed request to Special:OAuth/identify. The request is signed with both your application's key/secret, and the authorized token/secret that you obtained in step 3 above.

MediaWiki returns a Json Web Token (JWT), which has been signed with your Consumer Secret, which was issued to you when you registered your consumer. To identify the user, you must:

  • Check the signature on the JWT (you can use the JWT::decode() function included in the extension's source). This prevents an attacker from tampering with the content of the JWT
  • Verify that the token was issued by the expected wiki, to your application, within a valid time frame, with a valid nonce. This prevents an attacker from responding to your request with an old JWT, or a JWT for another consumer. The token contains fields for you to validate:
    • iss: The issuing MediaWiki's $wgCanonicalServer
    • aud: Your application's Consumer Key
    • iat: Timestamp the token was issued at
    • exp: Timestamp when this token expires
    • nonce: The nonce from your OAuth request

If the JWT has a valid signature, and you have verified the JWT, you can know that the MediaWiki user had the following attributes at the time of the check:

  • username: The MediaWiki username
  • sub: The MediaWiki user_id
  • editcount: The user's edit count
  • confirmed_email: The user has a confirmed email set in MediaWiki
  • registered: The date when the user registered
  • groups: A list of groups to which the user belongs
  • rights: A list of user rights that this user has been granted on the wiki

Use the API, setting Authorization header[edit | edit source]

  • MediaWiki requires that you use the http Authorization header, instead of including the OAuth parameters your GET or POST values
  • You will still need to get and use CSRF tokens to make edits, just as if you were using the API normally. Your application does not need to keep track of the wiki's session cookie-- the OAuth extension will create and use a session based on the user's authorized token, which will last up to 1 hour
  • Your API calls will be limited to the user rights that were both given to the user, and granted by the user to your application during the authorization step
  • Edits from your application will be tagged with your Consumer's id number

See also[edit | edit source]