Merge 68184aac31 into e9f0f31d27
Hugh Nimmo-Smith
1 week ago
committed by
GitHub
commit
d2e96c5d8c
@ -0,0 +1,178 @@
|
||||
# MSC4341: Support for RFC 8628 Device Authorization Grant
|
||||
|
||||
The current [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-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](https://datatracker.ietf.org/doc/html/rfc8628) 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](https://datatracker.ietf.org/doc/html/rfc8628) to the [list of supported
|
||||
grant types](https://spec.matrix.org/v1.15/client-server-api/#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](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery)
|
||||
- `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](https://spec.matrix.org/v1.15/client-server-api/#login-flow) 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](https://spec.matrix.org/v1.15/client-server-api/#refresh-token-grant).
|
||||
|
||||
### 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](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery).
|
||||
|
||||
This step is as per the current Matrix spec, but as per [RFC 8628 section 4](https://datatracker.ietf.org/doc/html/rfc8628#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](https://spec.matrix.org/v1.15/client-server-api/#client-registration).
|
||||
|
||||
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](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1).
|
||||
|
||||
The `client_id` should be as per the registration step above, and the `scope` as described in the current [spec](https://spec.matrix.org/v1.15/client-server-api/#scope).
|
||||
|
||||
e.g.
|
||||
|
||||
```http
|
||||
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](https://datatracker.ietf.org/doc/html/rfc8628#section-3.2).
|
||||
|
||||
For example:
|
||||
|
||||
```http
|
||||
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](https://datatracker.ietf.org/doc/html/rfc8628#section-3.4).
|
||||
|
||||
e.g.
|
||||
|
||||
```http
|
||||
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](https://datatracker.ietf.org/doc/html/rfc8628#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](https://spec.matrix.org/v1.15/client-server-api/#login-flow).
|
||||
|
||||
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](https://oauth.net/2/grant-types/device-code/) grant type or [Device Flow](https://curity.io/resources/learn/oauth-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](https://datatracker.ietf.org/doc/html/rfc8628#section-5) contains various security considerations
|
||||
that homeserver and client implementors should consider.
|
||||
|
||||
Additionally, [RFC 9700](https://datatracker.ietf.org/doc/html/rfc9700) 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](https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv1auth_metadata) as being
|
||||
[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) it isn't appropriate to introduce unstable prefixes.
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
Loading…
Reference in New Issue