From 1c32e21b6924d9424a8eb2d9cf2e2b7139e7bf29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 16 Jun 2025 12:27:29 +0200 Subject: [PATCH] Move up login and token refresh flows in hierarchy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 100 +++++++++++++++------------- 1 file changed, 52 insertions(+), 48 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 24db00f3..c62e6b55 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1519,10 +1519,51 @@ To use this grant, homeservers and clients MUST: Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html) for clients with an HTTPS redirect URI. -###### Login flow with the authorization code grant +###### User registration -Logging in with the OAuth 2.0 authorization code grant in the context of the -Matrix specification means to request a scope including full client-server API +Clients can signal to the server that the user desires to register a new account +by initiating the authorization code grant with the `prompt=create` parameter +set in the authorization request as defined in [Initiating User Registration via +OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html). + +Whether the homeserver supports this parameter is advertised by the +`prompt_values_supported` authorization server metadata. + +Servers that support this parameter SHOULD show the account registration UI in +the browser. + +##### Refresh token grant + +As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#section-6), +the refresh token grant lets the client exchange a refresh token for an access +token. + +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 MUST be short-lived and SHOULD be refreshed using the +`refresh_token` when expired. + +The homeserver SHOULD issue a new refresh token each time an old one is used, +and invalidate the old one. However, it MUST ensure that the client is able to +retry the refresh request in the case that the response to the request is lost. + +The homeserver SHOULD consider that the session is compromised if an old, +invalidated refresh token is used, and SHOULD revoke the session. + +The client MUST handle access token refresh failures as follows: + + - If the refresh fails due to network issues or a `5xx` HTTP status code from + the server, the client should retry the request with the old refresh token + later. + - If the refresh fails due to a `4xx` HTTP status code from the server, the + client should consider the session logged out. + +#### Login flow + +Logging in with the OAuth 2.0 API should be done with the [authorization code +grant](#authorization-code-grant). In the context of the Matrix specification, +this means requesting a [scope](#scope) including full client-server API read/write access and allocating a device ID. First, the client needs to generate the following values: @@ -1666,57 +1707,20 @@ Sample response: Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami) endpoint to get the user ID that owns the access token. -###### User registration +#### Token refresh flow -Clients can signal to the server that the user desires to register a new account -by initiating the authorization code grant with the `prompt=create` parameter -set in the authorization request as defined in [Initiating User Registration via -OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html). - -Whether the homeserver supports this parameter is advertised by the -`prompt_values_supported` authorization server metadata. - -Servers that support this parameter SHOULD show the account registration UI in -the browser. - -##### Refresh token grant - -As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#section-6), -the refresh token grant lets the client exchange a refresh token for an access -token. - -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 MUST be short-lived and SHOULD be refreshed using the -`refresh_token` when expired. - -The homeserver SHOULD issue a new refresh token each time an old one is used, -and invalidate the old one. However, it MUST ensure that the client is able to -retry the refresh request in the case that the response to the request is lost. - -The homeserver SHOULD consider that the session is compromised if an old, -invalidated refresh token is used, and SHOULD revoke the session. - -The client MUST handle access token refresh failures as follows: - - - If the refresh fails due to network issues or a `5xx` HTTP status code from - the server, the client should retry the request with the old refresh token - later. - - If the refresh fails due to a `4xx` HTTP status code from the server, the - client should consider the session logged out. - -###### Token refresh flow with the refresh token grant +Refreshing a token with the OAuth 2.0 API should be done with the [refresh token +grant](#refresh-token-grant). When the access token expires, the client must refresh it by making a `POST` request to the `token_endpoint` with the following parameters, encoded as `application/x-www-form-urlencoded` in the body: -- The `grant_type` set to `refresh_token` -- The `refresh_token` obtained from the token response during the authorization - flow -- The `client_id` value obtained by registering the client metadata with the - server +| Parameter | Value | +|-----------------|------------------------------------------------------------| +| `grant_type` | `refresh_token` | +| `refresh_token` | The `refresh_token` obtained from the token response during the last token request. | +| `client_id` | The client ID returned from client registration. | The server replies with a JSON object containing the new access token, the token type, the expiration time, and a new refresh token, like in the authorization