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 secret) 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 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  response pointing to the authorization URL on MediaWiki,   and containing the request token you obtained in. 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 ). 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



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