Document toolboxDocument toolbox

Device Authorization Grant

Owned by Bruce Hoff
Jun 19, 2021
2 min read

 

One way to authorize a CLI is using the Device Authorization Grant RFC 8628: OAuth 2.0 Device Authorization Grant . This would allow the CLI to obtain a Synapse access token without the user having to enter any secret (like a personal access token) in the client. The authorization flow was designed for devices with no keypad or web browser but could be used in our case too. The elements to implement are:

 

Three new services (plus an extension to the token endpoint service):

  1. /device_authorization
    inputs: client_id, scopes and claims
    returns: device_code, user_code, verification_uri

Side effect: stores device_code, user_code, scopes and claims,
with creation date in a non-migrating table. Expiration would
be very short, just a few minutes. A boolean field, 'consented'
is intially 'false'.

 

2. service request description

input: user_code

returns: a user readable description of the requested access (client, scopes, claims)

Side effects: None

 

3. an endpoint similar to the current /consent endpoint

input: user code

returns nothing (204 status)

Side effect: Logs in the user and marks consented=true in the record created by the /device_authorization service.

 

4. /token endpoint

inputs: grant_type = device_code, client_id, device_code.

returns: OIDC access, id, and optionally refresh token if

Server looks up the record for the given device_code, if consented=true. If not,
it returns "authorization_pending" (if time limit hasn't passed) or "expired_token" otherwise.

 

 

verification_uri is http://signin.synapse.org , which would recognize the user_code
parameter, call the description and consent services, and display some acknowledgement
after authorization is given.

 

The flow is:

  1. User initiates ‘log in’ in the CLI.

  2. client presents verification_uri and user_code to user at stdout OR, if possible, launches a browser with the verification_uri and user_code.

  3. Client begins polling the token endpoint

  4. Browser logs in the user, shows a description of the requested scope, and asks for consent.

  5. User indicates their consent. Is advised to return to the CLI.

  6. CLI receives the token and indicates to the user that it has authenticated.

  7. If user doesn’t log in within the allotted time, CLI indicates the time out.