From 91b2a49b6f5a912975b3492a4c7615f2245cbf1b Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 31 May 2022 16:19:15 -0400 Subject: [PATCH] apply suggestions from review, and other clarifications --- content/client-server-api/_index.md | 98 +++++++++++++++-------------- data/api/client-server/refresh.yaml | 3 + 2 files changed, 54 insertions(+), 47 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 5eb5f8b5..5f2740b9 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -337,15 +337,15 @@ to prevent the access token being leaked in access/HTTP logs. The query string should only be used in cases where the `Authorization` header is inaccessible for the client. -{{% changed-in v="1.3" %}} When credentials are required but missing or -invalid, the HTTP call will return with a status of 401 and the error code, -`M_MISSING_TOKEN` or `M_UNKNOWN_TOKEN` respectively. Note that an error code -of `M_UNKNOWN_TOKEN` could mean one of four things: +When credentials are required but missing or invalid, the HTTP call will +return with a status of 401 and the error code, `M_MISSING_TOKEN` or +`M_UNKNOWN_TOKEN` respectively. Note that an error code of `M_UNKNOWN_TOKEN` +could mean one of four things: 1. the access token was never valid. 2. the access token has been logged out. 3. the access token has been [soft logged out](#soft-logout). -4. the access token [needs to be refreshed](#refreshing-access-tokens). +4. {{< added-in v="1.3" >}} the access token [needs to be refreshed](#refreshing-access-tokens). When a client receives an error code of `M_UNKNOWN_TOKEN`, it should: @@ -377,52 +377,56 @@ invalidate any access and refresh tokens previously assigned to that device. {{% added-in v="1.3" %}} -Access tokens can expire after a certain amount of time. Any HTTP -calls that use an expired access token will return with an error code -`M_UNKNOWN_TOKEN`, preferably with `soft_logout: true`. When a client -receives this error and it has a refresh token, it should attempt to -refresh the access token by calling `/refresh`. Clients can also -refresh their access token at any time, even if it has not yet -expired. If the token refresh succeeds, it should use the new token -for future requests, and can re-try previously-failed requests with -the new token. When an access token is refreshed, a new refresh token -may be returned; if a new refresh token is given, the old refresh -token will be invalidated, and the new refresh token should be used -when the access token needs to be refreshed. - -If the token refresh fails, then the client can treat it as a [soft -logout](#soft-logout), if the error response included a `soft_logout: -true` property, and attempt to obtain a new access token by re-logging -in. If the error response does not include a `soft_logout: true` -property, the client should consider the user as being logged out. - -Handling of clients that do not support refresh tokens is up to the -homeserver; clients indicate their support for refresh tokens by -including a `refresh_token: true` property in the request body of the -`/login` and `/register` endpoints. For example, homeservers may allow -the use of non-expiring access tokens, or may expire access tokens -anyways and rely on soft logout behaviour on clients that don't -support refreshing. +Access tokens can expire after a certain amount of time. Any HTTP calls that +use an expired access token will return with an error code `M_UNKNOWN_TOKEN`, +preferably with `soft_logout: true`. When a client receives this error and it +has a refresh token, it should attempt to refresh the access token by calling +[`/refresh`](#post_matrixclientv3refresh). Clients can also refresh their +access token at any time, even if it has not yet expired. If the token refresh +succeeds, the client should use the new token for future requests, and can +re-try previously-failed requests with the new token. When an access token is +refreshed, a new refresh token may be returned; if a new refresh token is +given, the old refresh token will be invalidated, and the new refresh token +should be used when the access token needs to be refreshed. + +The old refresh token remains valid until the new access token or refresh token +is used, at which point the old refresh token is revoked. This ensures that if +a client fails to receive or persist the new tokens, it will still be able to +refresh them. + +If the token refresh fails and the error response included a `soft_logout: +true` property, then the client can treat it as a [soft logout](#soft-logout) +and attempt to obtain a new access token by re-logging in. If the error +response does not include a `soft_logout: true` property, the client should +consider the user as being logged out. + +Handling of clients that do not support refresh tokens is up to the homeserver; +clients indicate their support for refresh tokens by including a +`refresh_token: true` property in the request body of the +[`/login`](#post_matrixclientv3login) and +[`/register`](#post_matrixclientv3register) endpoints. For example, homeservers +may allow the use of non-expiring access tokens, or may expire access tokens +anyways and rely on soft logout behaviour on clients that don't support +refreshing. ### Soft logout A client can be in a "soft logout" state if the server requires -re-authentication before continuing, but does not want to invalidate -the client's session. That is, any persisted state held by the client, -such as encryption keys and device information, must not be reused and -must be discarded, and can be re-used if the client successfully -re-authenticates. - -The server indicates that the client is in a soft logout state by -including a `soft_logout: true` parameter in an `M_UNKNOWN_TOKEN` -error response; the `soft_logout` parameter defaults to `false`. - -A client that receives such a response can try to [refresh its access -token](#refreshing-access-tokens), if it has a refresh token -available. If it does not have a refresh token available, or -refreshing fails with `soft_logout: true`, the client can acquire a -new access token by specifying the device ID it is already using to -the login API. +re-authentication before continuing, but does not want to invalidate the +client's session. The server indicates that the client is in a soft logout +state by including a `soft_logout: true` parameter in an `M_UNKNOWN_TOKEN` +error response; the `soft_logout` parameter defaults to `false`. If the +`soft_logout` parameter is omitted or is `false`, this means the server has +destroyed the session and the client should not reuse it. That is, any +persisted state held by the client, such as encryption keys and device +information, must not be reused and must be discarded. If `soft_logout` is +`true` the client can reuse any persisted state. + +{{% changed-in v="1.3" %}} A client that receives such a response can try to +[refresh its access token](#refreshing-access-tokens), if it has a refresh +token available. If it does not have a refresh token available, or refreshing +fails with `soft_logout: true`, the client can acquire a new access token by +specifying the device ID it is already using to the login API. ### User-Interactive Authentication API diff --git a/data/api/client-server/refresh.yaml b/data/api/client-server/refresh.yaml index abe8c8fb..273e6d6a 100644 --- a/data/api/client-server/refresh.yaml +++ b/data/api/client-server/refresh.yaml @@ -42,6 +42,9 @@ paths: not make any assumptions about the old access token still being valid, and should use the newly provided access token instead. + The old refresh token remains valid until the new access token or refresh token + is used, at which point the old refresh token is revoked. + Note that this endpoint does not require authentication, since authentication is provided via the refresh token.