From 72e694ba0b85604f4f59c5fb84d79514a70f783a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 22 Apr 2024 09:26:42 -0600 Subject: [PATCH] MSC4126: Deprecation of query string auth (#4126) * MSC: Deprecation of query string auth * Update proposals/4126-deprecate-query-string-auth.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/4126-deprecate-query-string-auth.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 proposals/4126-deprecate-query-string-auth.md diff --git a/proposals/4126-deprecate-query-string-auth.md b/proposals/4126-deprecate-query-string-auth.md new file mode 100644 index 00000000..264555f7 --- /dev/null +++ b/proposals/4126-deprecate-query-string-auth.md @@ -0,0 +1,74 @@ +# MSC4126: Deprecation of query string auth + +Presently, the Client-Server API allows clients to provide their access token via the `Authorization` +request header or via an `access_token` query string parameter, described [here](https://spec.matrix.org/v1.10/client-server-api/#using-access-tokens). +Clients are already encouraged to use the header approach, though the query string option exists for +largely backwards compatibility reasons. + +The query string approach is subject a number of security, usability, and practical concerns, discussed +on [matrix-spec#1780](https://github.com/matrix-org/matrix-spec/issues/1780): + +* The query string of an HTTP request is often logged by the client itself, middleware reverse proxy, + and application/homeserver as well. Though some of these layers may be aware of this issue, they + can trivially accidentally break to log sensitive credentials again. By contrast, headers are not + typically logged by default. + +* Users often copy and paste URLs from their clients to either get support or provide direct links + to content/media. While the media angle is largely expected to be resolved with [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916), + users are currently able to right click images in their client and copy the URL - if this URL + includes authentication in the query string, the user will likely end up disclosing their access + token. The same scenario applies when copy/pasting request logs out of a client when getting + support. + +* Having two ways of doing things could lead to compatibility issues, where a client using the query + string approach is tried against a server which only supports the header. The client ends up not + working, leading to subpar user experience. + +* Most clients have already adopted the header approach, largely forgetting that the query string + even exists. Continuing to support the query string option leaves some maintenance burden for what + is effectively unused code. + +* Matrix has [decided](https://matrix.org/blog/2023/09/matrix-2-0/) to adopt OIDC for authentication, + which is based on OAuth 2.0, which [advises against](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.3.2) + the query string approach. + +With these conditions in mind, this proposal sets the query string approach on a path towards removal +from the Matrix specification. This affects the Client-Server API and [Identity Service API](https://spec.matrix.org/v1.10/identity-service-api/#authentication) +as both support the approaches described above. + +## Proposal + +For both the Client-Server API and Identity Service API, the `access_token` query string authentication +parameter becomes *deprecated*, and SHOULD NOT be used by clients (as already stated in the specification). +Deprecation is required for at least 1 spec version before removal under the [deprecation policy](https://spec.matrix.org/v1.10/#deprecation-policy). + +Removal from the specification requires a second MSC and at least 1 specification release to pass. This +is currently described as [MSC4127](https://github.com/matrix-org/matrix-spec-proposals/pull/4127). + +## Potential issues + +Clients which rely on the query string approach may stop working. This is considered acceptable for +the purposes of this MSC. + +## Alternatives + +Most alternatives are not practical as they would maintain the security risk described in the introduction +for this proposal. + +Alterations to the deprecation policy may be discussed in a future MSC to make this sort of removal +easier. + +## Security considerations + +Security considerations are described throughout this proposal. + +## Unstable prefix + +This proposal cannot feasibly have an unstable prefix. Clients are already discouraged from using +query string authentication and should switch to `Authorization` as soon as possible, regardless of +this MSC. + +## Dependencies + +This MSC has no direct dependencies itself. [MSC4127](https://github.com/matrix-org/matrix-spec-proposals/pull/4127) +requires this MSC to land first.