diff --git a/changelogs/application_service/newsfragments/1200.breaking b/changelogs/application_service/newsfragments/1200.breaking new file mode 100644 index 000000000..8b3620729 --- /dev/null +++ b/changelogs/application_service/newsfragments/1200.breaking @@ -0,0 +1 @@ +Replace homeserver authorization approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832). \ No newline at end of file diff --git a/content/application-service-api.md b/content/application-service-api.md index 61227660e..029e03501 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -127,11 +127,27 @@ this. #### Authorization -Homeservers MUST include a query parameter named `access_token` -containing the `hs_token` from the application service's registration -when making requests to the application service. Application services -MUST verify the provided `access_token` matches their known `hs_token`, -failing the request with an `M_FORBIDDEN` error if it does not match. +{{% changed-in v="1.4" %}} + +Homeservers MUST include an `Authorization` header, containing the `hs_token` +from the application service's registration, when making requests to the +application service. Application services MUST verify that the provided +`Bearer` token matches their known `hs_token`, failing the request with +an `M_FORBIDDEN` error if it does not match. + +The format of the `Authorization` header is similar to the [Client-Server API](/client-server-api/#client-authentication): +`Bearer TheHSTokenGoesHere`. + +{{% boxes/note %}} +In previous versions of this specification, an `access_token` query +parameter was used instead. Servers should only send this query parameter +if supporting legacy versions of the specification. + +If sending the `query_string`, it is encouraged to send it alongside +the `Authorization` header for maximum compatibility. + +Application services should ensure both match if both are provided. +{{% /boxes/note %}} #### Legacy routes diff --git a/data/api/application-service/definitions/security.yaml b/data/api/application-service/definitions/security.yaml index 6d7edd3a4..c273880ed 100644 --- a/data/api/application-service/definitions/security.yaml +++ b/data/api/application-service/definitions/security.yaml @@ -1,4 +1,5 @@ # Copyright 2018 New Vector Ltd +# Copyright 2022 The Matrix.org Foundation C.I.C. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -12,7 +13,7 @@ # See the License for the specific language governing permissions and # limitations under the License. homeserverAccessToken: - type: apiKey - description: The `hs_token` provided by the application service's registration. - name: access_token - in: query + type: http + scheme: Bearer + # Per docs, this is basically a description. https://swagger.io/docs/specification/authentication/bearer-authentication/ + bearerFormat: The `hs_token` provided by the application service's registration.