wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1534 from turt2live/travis/as/auth-impersonation

Browse source 
Encourage appservices to use the Authorization header
This commit is contained in:
Travis Ralston 2018-08-21 12:13:35 -06:00 • committed by GitHub
commit 997562786b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

45
specification/application_service_api.rst
View file

@ -197,29 +197,34 @@ 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`` for the ``access_token`` alongside the user the
application service would like to masquerade as.
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 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. 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
+++++++++++++++++++
@ -236,11 +241,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
++++++++++++++++++++++++++++++
@ -263,12 +267,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: "<desired user localpart in AS namespace>"
username: "_irc_example"
}
Application services which attempt to create users or aliases *outside* of