matrix-spec-proposals/proposals/4126-deprecate-query-string-auth.md

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. 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:

• 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, 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 to adopt OIDC for authentication, which is based on OAuth 2.0, which advises against 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 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.

Removal from the specification requires a second MSC and at least 1 specification release to pass. This is currently described as MSC4127.

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 requires this MSC to land first.