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.

Registration

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 and user identity verification consumers require manual review. Developers requesting a new consumer can post a request to m: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:

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

User authorization flow

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 clients request authorization from 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).

https://meta.wikimedia.org/w/rest.php/oauth/authorize?client_id=<client id>&response_type=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.

POST https://meta.wikimedia.org/w/rest.php/oauth/access_token?grant_type=authorization_code&code=<authorization code>&client_id=<client id>&client_secret=<client secret>

Returns an access token and a refresh token.

{
  "access_token": "...",
  "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.

<Any MediaWiki API request>
Authorization: Bearer abcde....6789

Step 4: Refresh token

If an access token expires, you can use a refresh token to retrieve a new access token.

POST https://meta.wikimedia.org/w/rest.php/oauth/access_token?grant_type=refresh_token&refresh_token=<refresh token>

Returns an access token and a refresh token.

{
  "access_token": "...",
  "refresh_token": "..."
}

Using state in authorization requests

^{[examples needed]}

User identity verification flow

^{[clarification needed]}

https://meta.wikimedia.org/w/rest.php/oauth2/resource/profile
Authorization: Bearer abcde....6789

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.

<Any MediaWiki API request>
Authorization: Bearer abcde....6789

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.

Workflow	Auth flow
Anonymous, read-only access to Wikimedia content
Log in with Wikimedia only	User identity verification client
Log in with Wikimedia and interact with Wikimedia sites	User authorization client
Interact with Wikimedia sites as an approved bot	Owner-only client registered by a dedicated Wikimedia bot account

Documentation

OAuth 2.0 documentation

OAuth 1.0(a) documentation

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 (Note that "client" is more friendly than "consumer")
- 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?
- Non-confidential clients are not capable of keeping secrets private, for example a mobile app, desktop app, or JavaScript app running in-browser.
Are there any libraries that support OAuth 2.0 as there are for MediaWiki OAuth 1.0a?
Example use case for identifying the user?
Do keys work while pending manual review?
For the /oauth2/access_token endpoint, the docs for the redirect_uri parameter state "If present, must match the URI that was set when client was registered exactly." If this endpoint only works for user authorization consumers (which are required to provide a redirect URL at registration), what is the use case for this parameter?