From 625999a039075b165ccc72e49f98eb97ba87ffd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 30 Apr 2024 18:07:59 +0200 Subject: [PATCH] Deprecate authentication via a query string (#1808) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../newsfragments/1808.clarification | 1 + .../newsfragments/1808.clarification | 1 + content/client-server-api/_index.md | 22 ++++++++++--------- content/identity-service-api.md | 19 ++++++++++------ .../client-server/definitions/security.yaml | 5 +++-- data/api/identity/definitions/security.yaml | 3 ++- 6 files changed, 31 insertions(+), 20 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1808.clarification create mode 100644 changelogs/identity_service/newsfragments/1808.clarification diff --git a/changelogs/client_server/newsfragments/1808.clarification b/changelogs/client_server/newsfragments/1808.clarification new file mode 100644 index 00000000..ff2c1651 --- /dev/null +++ b/changelogs/client_server/newsfragments/1808.clarification @@ -0,0 +1 @@ +Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). diff --git a/changelogs/identity_service/newsfragments/1808.clarification b/changelogs/identity_service/newsfragments/1808.clarification new file mode 100644 index 00000000..ff2c1651 --- /dev/null +++ b/changelogs/identity_service/newsfragments/1808.clarification @@ -0,0 +1 @@ +Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 8c017e62..ba527275 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -390,8 +390,7 @@ specify parameter values. The flow for this method is as follows: ## Client Authentication Most API endpoints require the user to identify themselves by presenting -previously obtained credentials in the form of an `access_token` query -parameter or through an Authorization Header of `Bearer $access_token`. +previously obtained credentials in the form of an access token. An access token is typically obtained via the [Login](#login) or [Registration](#account-registration-and-management) processes. Access tokens can expire; a new access token can be generated by using a refresh token. @@ -405,16 +404,19 @@ investigate [macaroons](http://research.google.com/pubs/pub41892.html). ### Using access tokens -Access tokens may be provided in two ways, both of which the homeserver -MUST support: +Access tokens may be provided via a request header, using the Authentication +Bearer scheme: `Authorization: Bearer TheTokenHere`. -1. Via a query string parameter, `access_token=TheTokenHere`. -2. Via a request header, `Authorization: Bearer TheTokenHere`. +Clients may alternatively provide the access token via a query string parameter: +`access_token=TheTokenHere`. This method is deprecated to prevent the access +token being leaked in access/HTTP logs and SHOULD NOT be used by clients. -Clients are encouraged to use the `Authorization` header where possible -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. +Homeservers MUST support both methods. + +{{% boxes/note %}} +{{% changed-in v="1.11" %}} +Sending the access token as a query string parameter is now deprecated. +{{% /boxes/note %}} 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 diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 9e2d5cdf..3c20a12a 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -162,15 +162,20 @@ of access tokens to authenticate users. The access tokens provided by an Identity Server cannot be used to authenticate Client-Server API requests. -An access token is provided to an endpoint in one of two ways: +Access tokens may be provided via a request header, using the +Authentication Bearer scheme: `Authorization: Bearer TheTokenHere`. -1. Via a query string parameter, `access_token=TheTokenHere`. -2. Via a request header, `Authorization: Bearer TheTokenHere`. +Clients may alternatively provide the access token via a query string +parameter: `access_token=TheTokenHere`. This method is deprecated to +prevent the access token being leaked in access/HTTP logs and SHOULD NOT +be used by clients. -Clients are encouraged to the use the `Authorization` header where -possible 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. +Identity Servers MUST support both methods. + +{{% boxes/note %}} +{{% changed-in v="1.11" %}} +Sending the access token as a query string parameter is now deprecated. +{{% /boxes/note %}} When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code `M_UNAUTHORIZED`. diff --git a/data/api/client-server/definitions/security.yaml b/data/api/client-server/definitions/security.yaml index 16ceb8ac..0c9bd1c7 100644 --- a/data/api/client-server/definitions/security.yaml +++ b/data/api/client-server/definitions/security.yaml @@ -14,7 +14,7 @@ accessTokenQuery: type: apiKey description: |- - The `access_token` returned by a call to `/login` or `/register`, as a query + **Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query parameter. It can also be the `as_token` of an application service. @@ -33,7 +33,8 @@ accessTokenBearer: appserviceAccessTokenQuery: type: apiKey description: |- - The `as_token` of an application service, as a query parameter. + **Deprecated.** The `as_token` of an application service, as a query + parameter. name: access_token in: query appserviceAccessTokenBearer: diff --git a/data/api/identity/definitions/security.yaml b/data/api/identity/definitions/security.yaml index f3c668c5..598005b7 100644 --- a/data/api/identity/definitions/security.yaml +++ b/data/api/identity/definitions/security.yaml @@ -14,7 +14,8 @@ accessTokenQuery: type: apiKey description: |- - The `access_token` returned by a call to `/register`, as a query parameter. + **Deprecated.** The `access_token` returned by a call to `/register`, as a + query parameter. name: access_token in: query accessTokenBearer: