Extension:OAuth/Usage

OAuth is a cryptographically secure means to allow users to authorize your application to act on their behalf. This is very useful for 3rd party applications that make use of MediaWiki's API on behalf of a MediaWiki user -- allowing them to edit pages and perform other actions through your application. This page is written to help application developers understand how they can use OAuth to perform actions via MediaWiki on behalf of their users.

The Basics

There are three actors in involved in OAuth authorization, the MediaWiki user (a.k.a. the "resource owner"), your application (a.k.a. the "consumer" or "client") and a MediaWiki installation (a.k.a. the "provider"). When a user signals that they'd like to authorize your application, your application will need to coordinate a multi-stepped handshake with MediaWiki (see #Obtaining access: The OAuth handshake). Note that, in order to make use of OAuth, the MediaWiki installation will need to also have the OAuth extension installed and configured.

Terminology

Actors

• user -- (a.k.a. "resource owner") the MediaWiki user who is authorizing your application to operate on their behalf
• provider -- the system that a user is authorizing your application to access -- in this case, a MediaWiki installation
• consumer -- (a.k.a. "client") your application

Tokens

Tokens are key/secret pairs used to identify agents and sign HTTP requests and responses.

• consumer token -- a token that identifies your application. Obtained through Special:OAuthConsumerRegistration.
• request token -- a token that temporarily identifies a request for access
• access token -- a token that allows your application to operate on behalf of a user

Etc.

• callback URL -- a URL pointing back to your application (used in #Step 2: User authorization).

Getting started: Registering your application

In order to make use of OAuth, you'll need to obtain a consumer token to identify your application to the MediaWiki installation. You submit a request for a consumer token via Special:OAuthConsumerRegistration. You'll need to provide:

• A name for your application
• A short description of your applications' functionality
• The set of permissions needed by your application
• A version number for the permission set that you'll need (note: this is not the same as the version of your application)
• A callback URL (used in #Step 2: User authorization). (note: must be prefixed by http(s)://)

After registering your consumer, you'll be provided with a consumer key and secret. Save these and make sure that you store the secret in a secure location. If someone else obtains your consumer secret, they'll be able to impersonate your application. If, for some reason, your secret is compromised, you can generate a new secret by visiting Special:OAuthConsumerRegistration/list and requesting that a new secret be generated.

Obtaining access: The OAuth handshake

Step 1: Initiate request

Special:OAuth/initiate

In the first step of the handshake, your application will ask MediaWiki to provide a request token. You'll send a request including your consumer key and signed with your consumer secret and receive a response (also signed with your consumer secret) containing a request key and request secret.

1. signed request: GET .../index.php?title=Special%3AOAuth%2Finitiate
2. signed response body: (application/x-www-form-urlencoded) oauth_token=<request key>&oauth_token_secret=<request secret>

Step 2: User authorization

Special:OAuth/authorize

In the second step of the handshake, you'll redirect your user to MediaWiki and MediaWiki will ask for the user's permission on your behalf. This redirect is commonly performed responding to the user's browser with an HTTP 303 See Other response pointing to the authorization URL on MediaWiki, Special:OAuth/authorize and containing the request token you obtained in #Step 1: Initiate request. MediaWiki will ask the user to log in and authorize your application. Once the user has authorized your application, MediaWiki will redirect the user back to your application via the callback URL (provided by you when #Registering your consumer). The callback URL will contain a verifier key that you'll use in the next step.

1. direct the user to .../index.php?title=Special%3AOAuth%2Fauthorize&oauth_consumer_key=<request key>&oauth_token=<request secret>
2. the user's browser loads MediaWiki's authorization page and clicks "OK" to authorize your application
3. MediaWiki redirects the user to <callback URL>?oauth_token=<request key>&verifier=<verifier key>
4. the user's browser loads your callback URL with the request token and a verifier key

Step 3: Complete request

Special:OAuth/complete

In this step of the handshake, we'll be trading the request token an access token. Your application will send a signed request including the request token (from step 1) and the verifier key (from step 2) to MediaWiki and it will respond with an access token.

1. signed request: GET .../index.php?title=Special%3AOAuth%2Ftoken
2. signed response body: (application/x-www-form-urlencoded) oauth_token=<access key>&oauth_token_secret=<access secret>

Together, this key/secret pair represent the access token that can be used along with your consumer token to make requests MediaWiki's API on behalf of your user. You can store this access token to be used in the future.

Step 4: Identify the user (optional)

MediaWiki provides a secure means to identify which user you have obtained an access token for. To use this secure identification mechanism, you'll be sending a request signed with your consumer secret and including the access token to MediaWiki and then confirming a set of constraints about the response.

1. signed request: GET .../index.php?title=Special%3AOAuth%2Fidentify
2. signed response body: a JSON web token -- also signed with your consumer secret

Libraries and examples

TODO

PHP

General

• oauth -- This extension provides OAuth consumer and provider bindings.

Python

MediaWiki specific

• mwoauth -- A general set of utilities for performing an OAuth handshake with a MediaWiki installation
• flash-mwoauth -- A MediaWiki OAuth handler for flask.

General

• requests-oauthlib -- OAuthlib support for requests.
• oauthlib -- A generic, spec-compliant, thorough implementation of the OAuth request-signing logic.
• pyjwt -- A JSON web token utility based on the JSON web token 01 draft.

Low-level details

Signing and verifying signatures

TODO

Parsing a JSON web token

TODO

Notes

TODO: Review Extension:OAuth and look for additional details to incorporate