Extension:OAuth/Usage
This page is outdated. |
This page is currently a draft.
|
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 edit
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 edit
Actors edit
- 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 edit
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. edit
- callback URL -- a URL pointing back to your application (used in #Step 2: User authorization).
Getting started: Registering your application edit
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 edit
Step 1: Initiate request edit
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.
- signed request: GET
.../index.php?title=Special%3AOAuth%2Finitiate - signed response body: (application/x-www-form-urlencoded)
oauth_token=<request key>&oauth_token_secret=<request secret>
Step 2: User authorization edit
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.
- direct the user to
.../index.php?title=Special%3AOAuth%2Fauthorize&oauth_consumer_key=<request key>&oauth_token=<request secret> - the user's browser loads MediaWiki's authorization page and clicks "OK" to authorize your application
- MediaWiki redirects the user to
<callback URL>?oauth_token=<request key>&verifier=<verifier key> - the user's browser loads your callback URL with the request token and a verifier key
At this point, you must verify that the request key included in the callback URL matches the request key received in #Step 1: Initiate request. |
Step 3: Complete request edit
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.
- signed request: GET
.../index.php?title=Special%3AOAuth%2Ftoken - 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) edit
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.
- signed request: GET
.../index.php?title=Special%3AOAuth%2Fidentify - signed response body: a JSON web token -- also signed with your consumer secret
Along with confirming that the JSON web token returned has been signed with your consumer secret, you'll need to perform the following checks:
|
Libraries and examples edit
TODO
PHP edit
- General
- oauth -- This extension provides OAuth consumer and provider bindings.
Python edit
- 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 edit
Signing and verifying signatures edit
TODO
Parsing a JSON web token edit
TODO
Notes edit
TODO: Review Extension:OAuth and look for additional details to incorporate