Skip to content

Commit 8d2fb67

Browse files
sandhoserichvdhtonkku107anoadragon453clokep
authored
MSC4254: Usage of RFC7009 Token Revocation for Matrix client logout (#4254)
* MSC4254: Usage of RFC7009 Token Revocation for Matrix client logout * Clarify how the token_type_hint parameter is used * Clarify what the server should do if the client_id is not provided * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Tonkku <contact@tonkku.me> * Explain why we allow revoking without a client_id better * Clarify how this replaces the /logout API * Some non-contentious clarifying bits * s/login/logout/ Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Tonkku <contact@tonkku.me> Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
1 parent 1e689aa commit 8d2fb67

File tree

1 file changed

+121
-0
lines changed

1 file changed

+121
-0
lines changed

‎proposals/4254-oauth2-revocation.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# MSC4254: Usage of [RFC7009] Token Revocation for Matrix client logout
2+
3+
This proposal is part of the broader [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC][MSC3861].
4+
5+
This MSC specifies how Matrix clients should use OAuth 2.0 Token Revocation as defined in [RFC7009] to implement client logout.
6+
7+
## Proposal
8+
9+
### Prerequisites
10+
11+
This proposal requires the client to know the following authorization server metadata about the homeserver:
12+
13+
- `revocation_endpoint`: the URL where the client is able to revoke tokens
14+
15+
The discovery of the above metadata is out of scope for this MSC, and is currently covered by [MSC2965].
16+
17+
### Token revocation
18+
19+
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].
20+
21+
The server MUST revoke both the access token and refresh token associated with the token provided in the request.
22+
23+
The request includes the following parameters, encoded as `application/x-www-form-urlencoded`:
24+
25+
- `token`: This parameter MUST contain either the access token or the refresh token to be revoked.
26+
- `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
27+
- `client_id`: The client identifier obtained during client registration. This parameter is OPTIONAL.
28+
29+
If the `client_id` is not provided, or does not match the client associated with the token, the server SHOULD still revoke the token.
30+
This behavior is meant to help good actors like secret scanning tools to proactively revoke leaked tokens.
31+
The server MAY also warn the user that one of their sessions may be compromised in this scenario.
32+
33+
#### Sample flow
34+
35+
Revoking using the access token:
36+
37+
```http
38+
POST /oauth2/revoke HTTP/1.1
39+
Host: auth.example.com
40+
Content-Type: application/x-www-form-urlencoded
41+
42+
token=mat_ooreiPhei2wequu9fohkai3AeBaec9oo&
43+
token_type_hint=access_token&
44+
client_id=s6BhdRkqt3
45+
```
46+
47+
```http
48+
HTTP/1.1 200 OK
49+
```
50+
51+
Or equivalently, using the refresh token:
52+
53+
```http
54+
POST /oauth2/revoke HTTP/1.1
55+
Host: auth.example.com
56+
Content-Type: application/x-www-form-urlencoded
57+
58+
token=mar_Pieyiev3aenahm4atah7aip3eiveizah&
59+
token_type_hint=refresh_token&
60+
client_id=s6BhdRkqt3
61+
```
62+
63+
```http
64+
HTTP/1.1 200 OK
65+
```
66+
67+
### Handling errors
68+
69+
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.
70+
71+
The client should handle these errors appropriately:
72+
73+
- If the token is already revoked or invalid, the server returns a 200 OK response
74+
- If the client is not authorized to revoke the token, the server returns a 401 Unauthorized response
75+
- For other errors, the server returns a 400 Bad Request response with error details
76+
77+
### Replacement of existing APIs
78+
79+
This proposal replaces the existing [`/_matrix/client/v3/logout`] endpoint for [MSC3861]-compatible clients.
80+
Those clients MUST use this mechanism to logout, and clients using the [`/_matrix/client/v3/login`] endpoint to login MUST keep using the existing [`/_matrix/client/v3/logout`] endpoint.
81+
82+
Note that this proposal does not itself provide alternatives to endpoints like [`POST /_matrix/client/v3/logout/all`], [`DELETE /_matrix/client/v3/devices/{deviceId}`] or [`POST /_matrix/client/v3/delete_devices`].
83+
Under the [MSC3861] proposal, management of other devices is not the responsibility of the client, and should instead be provided in a separate user interface by the homeserver.
84+
85+
86+
## Potential issues
87+
88+
The main consideration around token revocation is ensuring proper cleanup of all related tokens and state. The server must:
89+
90+
1. Track the relationship between access tokens and refresh tokens
91+
2. Properly revoke both tokens when either one is provided
92+
3. Clean up any Matrix device associated with the session
93+
94+
## Alternatives
95+
96+
### OpenID Connect RP-Initiated Logout
97+
98+
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:
99+
100+
1. Allow the server to clear browser session state
101+
2. Support single logout across multiple clients
102+
3. Give visual feedback to the user about the logout process
103+
104+
However, this approach requires a browser redirect which may not be desirable for all clients, especially mobile platforms.
105+
106+
## Security considerations
107+
108+
Token revocation is a critical security feature that allows users to terminate access when needed. Some key security aspects:
109+
110+
- Servers must revoke both the access token and refresh token when either is revoked
111+
- The server should consider revoking other related sessions, like browser cookie sessions used during authentication
112+
- Revoking a token should be effective immediately, and not be usable for any further requests
113+
114+
[RFC7009]: https://tools.ietf.org/html/rfc7009
115+
[MSC2965]: https://github.com/matrix-org/matrix-spec-proposals/pull/2965
116+
[MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861
117+
[`/_matrix/client/v3/login`]: https://spec.matrix.org/v1.13/client-server-api/#login
118+
[`/_matrix/client/v3/logout`]: https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3logout
119+
[`POST /_matrix/client/v3/logout/all`]: https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3logoutall
120+
[`DELETE /_matrix/client/v3/devices/{deviceId}`]: https://spec.matrix.org/v1.13/client-server-api/#delete_matrixclientv3devicesdeviceid
121+
[`POST /_matrix/client/v3/delete_devices`]: https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3delete_devices

0 commit comments

Comments
 (0)