User:APaskulin (WMF)/OAuth 2.0 notes

Wikimedia OAuth 2.0 flow
Wikimedia wikis use the MediaWiki OAuth extension, which supports OAuth 1.0a and 2.0. Meta is configured as the central OAuth wiki for Wikimedia wikis. This section describes the Wikimedia OAuth 2.0 process as of 2020-02-05.

Step 1: Meta wiki form
Developers can register for three types of Wikimedia OAuth 2.0 consumers at m:Special:OAuthConsumerRegistration/propose on Meta:
 * User authorization (Consumer can be authorized by a user to act on their behalf in specific ways)
 * Required information
 * Callback URL
 * Grant types
 * User identity verification only (Either with or without access to real name and email address. No ability to read pages or act on a user’s behalf. No API access.)
 * Owner-only consumers (Authorized to act on behalf of a single user, such as a bot account.)

Step 2: Manual review (user authorization consumers only)
User authorization consumers require manual review. Developers requesting a new consumer can post a request to Steward_requests/Miscellaneous on Meta. These requests can be approved by users with the mwoauthmanageconsumer right. For Wikimedia, this right is associated with these groups:
 * OAuth admins group
 * Staff group
 * Stewards group

Key management
Once registered, developers can perform these actions via m:Special:OAuthConsumerRegistration/list on Meta:
 * Update the Allowed IP ranges for the key
 * Reset the secret key to a new value
 * Update the public RSA key

Step 1: Ask the user to authorize the app
After registering a user-authorization consumer, developers receive a “client application key” and a “client application secret”. These credentials let consumers send authorization requests asking users for the permissions specified at registration.

To ask a user to authorize an app, send the user to https://meta.wikimedia.org/w/rest.php/oauth/authorize and include the client ID and response type (authorization code).

The authorization server displays the authorization dialog for the user and gives them the option to approve or deny. If the user approves, the server sends the user back to the consumer app with an authorization code as a query parameter.

Step 2: Get an access token
Use an authorization code to get an access token.

Returns an access token and a refresh token.

Step 3: Call the API on behalf of an authorized user
Include the access token to call the API on behalf of an authorized user.

Step 4: Refresh token
In the event that an Access Token has expired and a Refresh Token can be used as follows to retrieve a new Access Token.

User identity verification flow
Returns username, groups, status, etc.

Owner-only consumer flow
Registering for an owner-only consumer creates an access token that's pre-authorized for the registering user only. This is typically helpful in the case of a bot account. Although Meta provides a “client application key”, “client application secret”, and “access token” for owner-only consumers, only the access token is needed to authorize MediaWiki API calls.

Dev portal prototype API key flow
This section describes the capabilities of the API key flow as mocked by the dev portal prototype.


 * Single-step create a key via form
 * View key
 * Delete key
 * See historical usage date (# of calls per key per day)
 * Developer can receive notifications if their keys are blocked, limits reached, etc.

OAuth 2.0 documentation

 * https://www.mediawiki.org/wiki/Extension:OAuth#OAuth_2.0_REST_endpoints
 * https://www.mediawiki.org/wiki/OAuth/For_Developers#OAuth_2
 * https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/OAuth/+/master/src/Rest/Handler

OAuth 1.0(a) documentation

 * https://www.mediawiki.org/wiki/OAuth/For_Developers#OAuth_1.0a
 * https://docs.google.com/presentation/d/1537HnwSaSzH-b8hINcz48SNhT8ElAUPC39to0_O1iNA/edit#slide=id.g15105b408d_0_287
 * https://tools.wmflabs.org/oauth-hello-world/index.php
 * https://www.mediawiki.org/wiki/Manual:Pywikibot/OAuth/Wikimedia

Recommendations

 * On the registration form, clarify the types of consumers are available and the process for each. When is manual review required?
 * On the registration form, clarify the options. What fields are required for which types? What does each type mean? When are defaults OK? What can be changed later and what can't?
 * Create docs for owner-only consumer flow for OAuth 2.0. (Similar docs exist for OAuth 1.0a)
 * Standardize terminology for OAuth 2.0 between form, management page, and docs
 * On the OAuth 2.0 API docs, clarify the parameters.
 * On the dev guide, clarify phrasing in step 2.
 * Add examples to the API docs and dev guide.
 * On extension page, include REST API in intro.
 * Experiment with API docs formatting.

Terminology

 * OAuth 2.0 API
 * client_id
 * client_secret
 * code
 * Registration
 * client application key
 * client application secret
 * access token

Open questions

 * What does it mean for a consumer to be non-confidential?
 * Are there any libraries that support OAuth 2.0 as there are for MediaWiki OAuth 1.0a?
 * Example use case for identifying the user?
 * On the key management page, what does the “Reset the secret key to a new value” option do?
 * Do keys work while pending manual review?