Core Platform Team/Initiative/OAuth2/Epics, User Stories, and Requirements

From mediawiki.org

< OAuth2

Epic 1 - Add OAuth2 support to MediaWiki for use by web-based clients[edit]

Personas:

  • Server: wiki that is used as an OAuth identity provider
  • Admin: administrator of a wiki used as an OAuth identity provider
  • Client: client web application that uses a wiki as the OAuth identity provider
  • User: user of a client web application requesting authentication

Non-functional requirements:

  • OAuth 1.0 and OAuth 2.0 must be able to coexist
  • Implementation in an extension: OAuth2
  • Code must be extensible to support API-based clients in Epic 2
  • The MediaWiki code should not depend upon a particular client in any way
  • Possibly test with Wikimedia-hosted Discourse instance
  • Security review of all new code
  • Implement on top of new MediaWiki REST API support, if possible
  • Use existing library, if possible
User Story Title User Story Description Priority Notes
1 Admin adds new client Admin runs a script to add a new OAuth 2.0 client to a MediaWiki instance
  • Pass in redirect URI for the client
    • for Discourse, this will be of the form https://DISCOURSE_HOST/auth/oauth2_basic/callback
  • Script generates client ID and secret and returns them
  • Script stores client ID and redirect URI in the MediaWiki database
  • Admin provides client ID, secret, authorization URL, and token URL to client to configure the client application
 Must Have This could be a self-service interface in the future, but this is out of scope for this epic
2 Admin removes client Admin runs a script to remove an existing OAuth 2.0 client from a MediaWiki instance
  • Pass in client ID
  • Client ID and associated information are deleted
  • Indicate success or failure
 Must Have
3 User requests login to client when user is already logged in to server (wiki)
  1. Client sends a request of the form:
    • https://WIKI_AUTH_ENDPOINT/auth?response_type=code&client_id=CLIENT_ID& scope=SCOPE&state=STATE
    • State is a random string generated by the client which will be sent back to the client.
  2. Server verifies that there is a logged-in user associated with the wiki
  3. User is presented with the authorization prompt (unless the client is whitelisted)
  4. If the user does not approve, an authentication failure is returned
  5. If the user approves:
    • Server generates authentication code
    • Server redirects back to the client with:
      • https://REDIRECT_URI/cb?code=AUTH_CODE&state=STATE
  6. Client sends a POST request to https://WIKI_AUTH_ENDPOINT/token with the following parameters
    • grant_type=authorization_code
    • code=AUTH_CODE
    • client_id=CLIENT_ID
    • client_secret=CLIENT_SECRET
  7. Server responds with and access token and expiration or an error
  8. Configurable optional step to get user information from the server
Must Have
4 User requests login to client when user is not already logged in to server (wiki) Same as 3 above except at step 2 the server must initiate a login workflow with the user. If the user is not able to login, and error is returned. If the user logs in correctly, the workflow above continues at step 3. Must Have
7 Admin whitelists client Admin whitelists client so that users do not have to accept the authorization dialog every time they login Optional


Epic 2 - Add OAuth 2.0 support to MediaWiki REST API[edit]

In Phabricator: https://phabricator.wikimedia.org/T234665

In this stage, we will use OAuth 2.0 as the primary authorization mechanism for the MediaWiki REST API.

Note: "client ID" is another word for "API key".

Personas:

  • Developer - a software developer that uses the MediaWiki REST API on their own behalf or on behalf of users
  • User - a person who reads, contributes to, curates or administrates a MediaWiki
ID Title Use Case Priority Notes
1 Client ID for Authorization As a Developer, I want to use a client ID as a bearer token for the REST API, to identify requests made on behalf of my company. Must Have This encompasses two requirements, at least one of which is required (TODO: check with PMs whether both are required):
  • Implementation of the client_credentials flow. Yes Done in current WIP patches.
  • Display a permanent access token when registering/updating consumers with oarc_owner_only set, as the OAuth 1 implementation already does.
2 Access Token for Authorization As a Developer, I want to use an access token as a bearer token for the REST API, to identify requests made on behalf of a user. Must Have Implement a SessionProvider, which may be as simple as doing the OAuth2 equivalent in place of MWOAuthSessionProvider lines 85–93.
3 Request new client ID As a Developer, I want to request a new client ID, to identify an application that uses the REST API. Must Have Yes Done in current WIP patches by reusing the existing m:Special:OAuthConsumerRegistration.
4 List client IDs As a Developer, I want to view a list of my existing client IDs, to know which IDs I have to use. Must Have Yes Done in current WIP patches by reusing the existing m:Special:OAuthConsumerRegistration.
5 Delete client ID As a Developer, I want to delete disable a client ID, so that I am no longer responsible for keeping it secure, since I no longer use it. Must Have Site admins can already disable (not delete) a consumer to the same effect via m:Special:OAuthManageConsumers. This functionality does not seem to be available to developers, it may need to be added to m:Special:OAuthConsumerRegistration. If so, it should apply to both 1.0a and 2.0.
6 List access tokens As a User, I want to view a list of all the access tokens I have approved, so that I can see what organizations have access to my account. Must Have Yes Done in current WIP patches by reusing the existing Special:OAuthManageMyGrants.
7 Delete access token As a User, I want to delete an access token, so that an organization I no longer approve cannot access my account. Must Have Yes Done in current WIP patches by reusing the existing Special:OAuthManageMyGrants.
8 Delete all access tokens As a User, I want to delete all access tokens, so that no organizations have access to my account, because I am concerned there may be a security problem. Optional Implement if time allows. A "delete all" button should be added to Special:OAuthManageMyGrants, and apply to both 1.0a and 2.0 access tokens.
9 Delete tokens on password change As a User, I want to delete all access tokens when I change my password, so that applications need to re-authorize. Optional Implement if time allows. This will require a change to MediaWiki core, abstracting the existing call at AuthManager.php line 909 to call a method on all registered SessionProviders. The SessionProvider base class would implement this method as a no-op. BotPasswordSessionProvider would implement it to do what line 909 does now. The OAuth SessionProvider implementation would also implement it.

Support for OAuth 2.0 in the Action API and Core REST API would be supported after implementation of Epic 2, since Epic 2 will provide a SessionProvider. In future epics, other APIs supported inside the organization would also support OAuth 2.0 authorization.

Retrieved from "https://www.mediawiki.org/w/index.php?title=Core_Platform_Team/Initiative/OAuth2/Epics,_User_Stories,_and_Requirements&oldid=4716599"