Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Deprecate authentication via a query string #1808

Merged
merged 2 commits into from
Apr 30, 2024
Merged

Deprecate authentication via a query string #1808

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eb4e0dd
Deprecate authentication via a query string
zecakeh Apr 26, 2024
355ac21
Add changelogs
zecakeh Apr 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/1808.clarification
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@zecakeh should this be a .deprecation as per the list in https://github.com/matrix-org/matrix-spec/blob/main/CONTRIBUTING.rst#adding-to-the-changelog?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(we'll fix it during the changelog cleanup at release time - if there's other notable issues, please mention them in #sct-office:matrix.org)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, yeah sorry for commenting on a closed PR. I wasn't sure what the proper process was. Would it help at all if I sent a PR renaming the file?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately not, as that PR then requires a changelog itself. Our release process has a "normalize the changelog" step which takes care of this for us.

Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).
1 change: 1 addition & 0 deletions changelogs/identity_service/newsfragments/1808.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).
22 changes: 12 additions & 10 deletions content/client-server-api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
19 changes: 12 additions & 7 deletions content/identity-service-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
5 changes: 3 additions & 2 deletions data/api/client-server/definitions/security.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:
Expand Down
3 changes: 2 additions & 1 deletion data/api/identity/definitions/security.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading