OAuth sequence.md

OAuth sequence.md

• Date: 2024-07-28
• Status: Possibly incomplete / inaccurate

The client's goal during the OAuth sequence is to obtain a long lived access_token that can be used to authenticate future requests.

Data

Client managed

• domain
  • The domain the user wants to log in to, e.g., mastodon.social
• client_name
  • The client's name, as it should be presented to the user when they are prompted to authorise it. E.g., "Pachli"
• website
  • The URL for the client's website, as it should be presented to the user when they are prompted to authorise the client. E.g., "https://pachli.app"
• scopes and scope
  • Different names for the same thing; the specific permissions the client is asking for (read, write, push, etc)
  • Different APIs use either the singular or plural form.
• redirect_uris and redirect_uri
  • Different names for the same thing; a URI that is controlled by the client, and the client can process requests for this URI.
  • Different APIs use either the singular or plural form.

Server managed

These values are returned by the server in different responses, and must be used by the client in followup requests.

• client_id and client_secret
  • Short-lived tokens that identify and authorise the client
• code
  • Short-lived token the client can use to request an access_token
• access_token
  • Long-lived token the client can use to act on behalf of the user. Allows the application to perform operations on the user's behalf, limited by the scopes associated with the token.

Sequence

Obtaining the access token requires five distinct steps.

1. Get the user account's domain
2. Register application with server
3. User authorises the application
4. Receive authorisation code
5. Convert code to access_token

sequenceDiagram
    actor U as User
    participant C as ClientApp
    participant B as ClientBrowser
    participant S as Server
    note over U,S: Step 1. Get the user account's domain
    C->>+U: Prompt for domain
    U->>-C: Enters domain
	Note over C,U: E.g., "mastodon.social"
    note over U,S: Step 2. Register application with server
    C->>+S: Register application<br/>POST $domain/api/v1/apps
    Note over C,S: Form data parameters:<br/>- client_name (e.g., "Pachli")<br/>- redirect_uris (e.g., "oauth2redirect://app.pachli")<br/>- scopes (e.g., "read write follow push")<br/>- website (e.g,. "https://pachli.app")
    S->>-C: 200: Application
    Note over C,S: Includes client_id, client_secret, redirect_uri
    C->>C: Save $client_id, $client_secret
    note over U,S: Step 3. User authorises the application
    C->>+B: GET $domain/oauth/authorize
    Note over C,B: Params:<br/>client_id=$client_id<br/>redirect_uri=$redirect_uri<br/>response_type=code<br/>scope=$scopes
    B->>+S: GET $domain/oauth/authorize
    opt if user is not logged in
    S->>B: HTML login page
    U->>B: Authenticates
    B->>S: POST $domain/auth/sign_in
    end
	S->>-B: HTML app authorisation form
	U->>B: Authorises app
    B->>+S: Sends form
    S->>-B: 301 $website?code=...
    note over U,S: Step 4. Receive authorisation code
    C->>C: Receives URL from $website?code=...
    C->>C: Extract code parameter
    note over U,S: Step 5. Convert code to access_token
    C->>+S: POST $domain/oauth/token
    Note over C,S: client_id=$client_id<br/>client_secret=$client_secret<br/>redirect_uri=$redirect_uri<br/>code=$code<br/>grant_type=authorization_code
    S->>-C: 200 Token
    Note over C,S: Contains access_token, token_type, scope, created_at
    C->>C: Save $access_token for future use

Loading