From 857bcc0fe7613fa8d4623ba4ee0ee509eb528953 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 17 Aug 2018 13:49:24 -0600 Subject: [PATCH 1/3] Encourage appservices to use the Authorization header This also throws in a mention about how to handle a request with a lack of user_id. The request samples now encourage the use of the header over the query string, and have had their sample values added for some readability. Fixes https://github.com/matrix-org/matrix-doc/issues/1296 Fixes https://github.com/matrix-org/matrix-doc/issues/1424 --- specification/application_service_api.rst | 36 +++++++++++++---------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..7119bd5a 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -192,22 +192,28 @@ they wish to be acting on behalf of. For real users, this would require additional permissions granting the AS permission to masquerade as a matrix user. Inputs: - - Application service token (``access_token``) + - Application service token (``as_token``) - User ID in the AS namespace to act as. Notes: - - This will apply on all aspects of the CS API, except for Account Management. + - This will apply on all aspects of the Client-Server API, except for Account Management. - The ``as_token`` is inserted into ``access_token`` which is usually where the - client token is. This is done on purpose to allow application services to - reuse client SDKs. + client token is, such as via the query string or ``Authorization`` header. This + is done on purpose to allow application services to reuse client SDKs. + - The ``access_token`` should be supplied through the ``Authorization`` header where + possible to prevent the token appearing in HTTP request logs by accident. -:: +The application service may specify the virtual user to act as through use of a +``user_id`` query string parameter on the request. The user specified in the query +string must be covered by one of the application service's ``user`` namespaces. If +the parameter is missing, the homeserver is to assume the application service intends +to act as the user implied by the ``sender_localpart`` property of the registration. - /path?access_token=$token&user_id=$userid +An example request would be:: + + GET /_matrix/client/%CLIENT_MAJOR_VERSION%/account/whoami?user_id=@_irc_user:example.org + Authorization: Bearer YourApplicationServiceTokenHere - Query Parameters: - access_token: The application service token - user_id: The desired user ID to act as. Timestamp massaging +++++++++++++++++++ @@ -223,11 +229,10 @@ Notes: :: - /path?access_token=$token&ts=$timestamp + PUT /_matrix/client/r0/rooms/!somewhere:domain.com/send/m.room.message/txnId?ts=1534535223283 + Authorization: Bearer YourApplicationServiceTokenHere - Query Parameters added to the send event APIs only: - access_token: The application service token - ts: The desired timestamp + Content: The event to send, as per the Client-Server API. Server admin style permissions ++++++++++++++++++++++++++++++ @@ -250,12 +255,13 @@ including the AS token on a ``/register`` request, along with a login type of :: - /register?access_token=$as_token + POST /_matrix/client/%CLIENT_MAJOR_VERSION%/register + Authorization: Bearer YourApplicationServiceTokenHere Content: { type: "m.login.application_service", - username: "" + username: "_irc_example" } Application services which attempt to create users or aliases *outside* of From 13a1628f59f8279d1a5889830a3514a6fec9c3a9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 12:34:52 -0600 Subject: [PATCH 2/3] Improve wording about how masquerading works --- specification/application_service_api.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 7119bd5a..4a29a1d8 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -185,18 +185,17 @@ homeserver. Identity assertion ++++++++++++++++++ The client-server API infers the user ID from the ``access_token`` provided in -every request. It would be an annoying amount of book-keeping to maintain tokens -for every virtual user. It would be preferable if the application service could -use the CS API with its own ``as_token`` instead, and specify the virtual user -they wish to be acting on behalf of. For real users, this would require -additional permissions granting the AS permission to masquerade as a matrix user. +every request. To avoid the application service from having to keep track of each +user's access token, the application service should identify itself to the Client-Server +API by providing its ``as_token`` instead for the ``access_token`` alongside the +user the application service would like to masquerade as. Inputs: - Application service token (``as_token``) - User ID in the AS namespace to act as. Notes: - - This will apply on all aspects of the Client-Server API, except for Account Management. + - This applies to all aspects of the Client-Server API, except for Account Management. - The ``as_token`` is inserted into ``access_token`` which is usually where the client token is, such as via the query string or ``Authorization`` header. This is done on purpose to allow application services to reuse client SDKs. From 389fa87e6e65a39b50748817d55d4c71f2f9e965 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Aug 2018 12:10:40 -0600 Subject: [PATCH 3/3] English --- specification/application_service_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 4a29a1d8..502472a0 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -187,8 +187,8 @@ Identity assertion The client-server API infers the user ID from the ``access_token`` provided in every request. To avoid the application service from having to keep track of each user's access token, the application service should identify itself to the Client-Server -API by providing its ``as_token`` instead for the ``access_token`` alongside the -user the application service would like to masquerade as. +API by providing its ``as_token`` for the ``access_token`` alongside the user the +application service would like to masquerade as. Inputs: - Application service token (``as_token``)