-
Notifications
You must be signed in to change notification settings - Fork 412
MSC4254: Usage of RFC7009 Token Revocation for Matrix client logout #4254
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 5 commits
ac1602f
797d26e
d78fa2a
9dff517
cd239ce
ef03a25
0536870
047beec
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,107 @@ | ||
# MSC4254: Usage of [RFC7009] Token Revocation for Matrix client logout | ||
|
||
This proposal is part of the broader [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC][MSC3861]. | ||
|
||
This MSC specifies how Matrix clients should use OAuth 2.0 Token Revocation as defined in [RFC7009] to implement client logout. | ||
|
||
## Proposal | ||
|
||
### Prerequisites | ||
|
||
This proposal requires the client to know the following authorization server metadata about the homeserver: | ||
|
||
- `revocation_endpoint`: the URL where the client is able to revoke tokens | ||
|
||
The discovery of the above metadata is out of scope for this MSC, and is currently covered by [MSC2965]. | ||
|
||
### Token revocation | ||
|
||
When a user wants to log out from a client, the client SHOULD revoke either its access token or refresh token by making a POST request to the revocation endpoint as described in [RFC7009]. | ||
|
||
The server MUST revoke both the access token and refresh token associated with the token provided in the request. | ||
|
||
The request includes the following parameters, encoded as `application/x-www-form-urlencoded`: | ||
|
||
- `token`: This parameter MUST contain either the access token or the refresh token to be revoked. | ||
- `token_type_hint`: This parameter is OPTIONAL, and if present, MUST have a value of either `access_token` or `refresh_token`. The server MAY use this value to optimize the token lookup process | ||
erikjohnston marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- `client_id`: The client identifier obtained during client registration. | ||
anoadragon453 marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
If the `client_id` is not provided, or does not match the client associated with the token, the server SHOULD still revoke the token. | ||
This behavior is meant to help good actors like secret scanning tools to proactively revoke leaked tokens. | ||
The server MAY also warn the user that one of their sessions may be compromised in this scenario. | ||
erikjohnston marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
#### Sample flow | ||
|
||
Revoking using the access token: | ||
|
||
```http | ||
POST /oauth2/revoke HTTP/1.1 | ||
Host: auth.example.com | ||
Content-Type: application/x-www-form-urlencoded | ||
token=mat_ooreiPhei2wequu9fohkai3AeBaec9oo& | ||
token_type_hint=access_token& | ||
client_id=s6BhdRkqt3 | ||
``` | ||
|
||
```http | ||
HTTP/1.1 200 OK | ||
``` | ||
|
||
Or equivalently, using the refresh token: | ||
|
||
```http | ||
POST /oauth2/revoke HTTP/1.1 | ||
Host: auth.example.com | ||
Content-Type: application/x-www-form-urlencoded | ||
token=mar_Pieyiev3aenahm4atah7aip3eiveizah& | ||
token_type_hint=refresh_token& | ||
client_id=s6BhdRkqt3 | ||
``` | ||
|
||
```http | ||
HTTP/1.1 200 OK | ||
``` | ||
|
||
### Handling errors | ||
|
||
The server may return an error response as defined in [RFC7009]. Note that RFC7009 mandates a [RFC6749 error response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) rather than a Matrix standard error response. | ||
|
||
The client should handle these errors appropriately: | ||
|
||
- If the token is already revoked or invalid, the server returns a 200 OK response | ||
- If the client is not authorized to revoke the token, the server returns a 401 Unauthorized response | ||
- For other errors, the server returns a 400 Bad Request response with error details | ||
|
||
## Potential issues | ||
|
||
The main consideration around token revocation is ensuring proper cleanup of all related tokens and state. The server must: | ||
|
||
1. Track the relationship between access tokens and refresh tokens | ||
2. Properly revoke both tokens when either one is provided | ||
3. Clean up any Matrix device associated with the session | ||
|
||
## Alternatives | ||
|
||
### OpenID Connect RP-Initiated Logout | ||
|
||
OpenID Connect defines a [RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html) specification that allows clients to initiate a logout through a browser redirect. This would: | ||
|
||
1. Allow the server to clear browser session state | ||
2. Support single logout across multiple clients | ||
3. Give visual feedback to the user about the logout process | ||
|
||
However, this approach requires a browser redirect which may not be desirable for all clients, especially mobile platforms. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm not following why a browser redirect would ever be a problem (especially on mobile)? The main proposal made sense when i was reading it, but then on hitting this RP-Initiated Logout alternative, I thought "huh, but these advantages sound great - why aren't we doing this then?", given I don't understand the disadvantage. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it's relatively unexpected from a user perspective to be bounced through the browser for logging out. This can be relatively transparent for web clients with a redirect, but for native clients, it means opening a browser window, switching context; and there is no defined way to get back to the client after the RP-initiated logout, so you end up outside the client at the end of the logout There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. hm, okay. can you add the rationale to the MSC please? :) |
||
|
||
## Security considerations | ||
|
||
Token revocation is a critical security feature that allows users to terminate access when needed. Some key security aspects: | ||
|
||
- Servers must revoke both the access token and refresh token when either is revoked | ||
- The server should consider revoking other related sessions, like browser cookie sessions used during authentication | ||
- Revoking a token should be effective immediately, and not be usable for any further requests | ||
|
||
[RFC7009]: https://tools.ietf.org/html/rfc7009 | ||
[MSC2965]: https://github.com/matrix-org/matrix-spec-proposals/pull/2965 | ||
[MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861 |
Uh oh!
There was an error while loading. Please reload this page.