matrix-spec-proposals/proposals/4341-device-authorization-grant.md

MSC4341: Support for RFC 8628 Device Authorization Grant

The current OAuth 2.0 API requires the user to complete authentication using a web browser on the device where the Matrix client is running.

This can be problematic if the device does not have a built in web browser or the user wishes to use a different device. It also causes issues in scenarios where catching the redirect back to the client is hard, like in CLI apps, or desktop apps with no redirect custom schemes.

RFC 8628 defines the OAuth 2.0 Device Authorization Grant which can be used for this purpose.

Proposal

Add the RFC 8628 OAuth 2.0 Device Authorization Grant to the list of supported grant types in the Client-Server API.

This grant requires the client to know the following authorization server metadata:

• grant_types_supported - this would include urn:ietf:params:oauth:grant-type:device_code
• device_authorization_endpoint - this would be added to the table of fields for the 200 response
• token_endpoint - this is already included in the spec

To use this grant, homeservers and clients MUST:

• Support the device authorization grant as per RFC 8628.
• Support the refresh token grant.

The login flow section would need to be updated to reflect that more than one login grant type exists.

As with the existing authorization code grant, when authorization is granted to a client, the homeserver MUST issue a refresh token to the client in addition to the access token.

The access token and refresh token should have the same lifetime constraints as described for the authorization code grant in the current spec.

Sample flow

The user wishes to login to a Matrix client on a device that doesn't have a web browser built in (e.g. a TV), but wishes to complete the login on another device (e.g. a smartphone).

1. The Matrix client discovers the OAuth 2.0 server metadata.

This step is as per the current Matrix spec, but as per RFC 8628 section 4 it should include the value urn:ietf:params:oauth:grant-type:device_code in the grant_types_supported field and specify a device_authorization_endpoint field.

2. The Matrix client registers itself as a client with the homeserver.

This step is as per the current Matrix spec.

3. The Matrix client sends a Device Authorization Request to the device_authorization_endpoint as per RFC 8628 section 3.1.

The client_id should be as per the registration step above, and the scope as described in the current spec.

e.g.

POST /oauth2/device HTTP/1.1
Host: account.matrix.org
Content-Type: application/x-www-form-urlencoded

client_id=my_client_id&scope=urn%3Amatrix%3Aclient%3Aapi%3A%2A%20urn%3Amatrix%3Aclient%3Adevice%3AABCDEGH

4. The homeserver responds to the Matrix client with the Device Authorization Response as per RFC 8628 section 3.2.

For example:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://account.matrix.org/link",
  "verification_uri_complete": "https://account.matrix.org/link?user_code=WDJB-MJHT",
  "expires_in": 1800,
  "interval": 5
}

It is recommended that the server provides a verification_uri_complete such that the user does not need to type in the user_code.

5. The Matrix client device conveys the returned verification_uri_complete (and/or verification_uri+user_code) to the user.

Exactly how the client does this depends on the specific device characteristics and use case.

For example, for a CLI application the verification_uri and user_code could be displayed as text for the user to type into their other device.

Or, another example would be the verification_uri_complete (with fallback to the verification_uri) could be encoded and displayed as a QR code for scanning on the other device (e.g. on a TV).

6. The user opens the verification_uri_complete (or verification_uri) on their other device that has a web browser.

The user then completes authentication and authorization for the login.

7. Whilst the user is doing this, the Matrix client starts polling the token_endpoint for an outcome.

Frequency of polling is determined by the interval value returned in the Device Authorization Response from step 4.

The poll request made by the client is the Device Access Token Request from RFC 8628 section 3.4.

e.g.

POST /oauth2/token HTTP/1.1
Host: account.matrix.org
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS&client_id=my_client_id

The server in turn responds with the Device Access Token Response as per RFC 8628 section 3.5.

Whilst the authorization is still outstanding a authorization_pending (or slow_down in the case of rate limiting) error code will be returned.

If the authorization is rejected then the access_denied error code will be returned.

If the authorization does not complete within the expires_in timeframe then the expired_token error code will be returned.

For a successful authorization the response will be an access token and refresh token as described in the current Matrix spec.

8. The Matrix client refreshes the access token with the refresh token grant when it expires.

This is as per the current spec.

9. The Matrix client revokes the tokens when the users wants to log out of the client.

This is as per the current spec.

Potential issues

Some literature refers to the Device Authorization Grant as the Device Code grant type or Device Flow. This MSC uses the name from the actual RFC.

Otherwise, none identified.

Alternatives

I'm not aware of any other standardised OAuth grant types that would be suitable as an alternative.

Requiring support for the new grant type

We could make it mandatory that new grant type is supported by Matrix homeservers.

As currently proposed it is optional and discoverable via the grant_types_supported metadata.

Make verification_uri_complete be mandatory

RFC 8628 makes makes verification_uri_complete optional, but we could make it mandatory. This could improve the UX for some use cases.

Security considerations

RFC 8628 section 5 contains various security considerations that homeserver and client implementors should consider.

Additionally, RFC 9700 Best Current Practice for OAuth 2.0 Security mentions clickjacking as a consideration for the server and advises on appropriate measures.

Unstable prefix

Although the response from the server metadata discovery endpoint is modified, because we already defined it as being RFC 8414 it isn't appropriate to introduce unstable prefixes.

Dependencies

None.