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 ). Note that, in order to make use of OAuth, the MediaWiki installation will need to also have the OAuth extension installed and configured.

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.
 * 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 ).

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. 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 ). (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  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  and requesting that a new secret be generated.

Step 1: Initiate request
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 key) containing a request key and request secret.


 * 1) signed request: GET
 * 2) signed response body: (application/x-www-form-urlencoded)



Step 2: User authorization
In the second step of the handshake, you'll redirect your user to MediaWiki in order to authorize your application. This redirect is commonly performed responding to the user's browser with an HTTP  response pointing to a authorization URL on MediaWiki. 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 a 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
 * 2) the user's browser loads MediaWiki's authorization page and clicks "OK" to authorize your application
 * 3) MediaWiki redirects the user to
 * 4) the user's browser loads your callback URL with the request token and a verifier key



Step 3: Complete request
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
 * 2) signed response body: (application/x-www-form-urlencoded)

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
 * 2) signed response body: a JSON web token -- also signed with your consumer secret

Validating the JSON web token
Along with confirming that the JSON web token returned has been signed with your consumer secret, you'll need to perform the following checks:


 * Check the issuer
 * Confirm that  matches the domain of MediaWiki that you made the request to (e.g. "mediawiki.org")


 * Check the audience
 * Confirm that  matches your consumer key


 * Check the issued at time
 * Confirm that  (unix timestamp in seconds) is before the current time


 * Check the expiration time
 * Confirm that  (unix timestamp in seconds) is after the current time


 * Check the number used only once
 * Confirm that  matches the   your application sent with the original request



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.

Signing and verifying signatures
TODO

Parsing a JSON web token
TODO