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

Add m.login.appservice to the spec (#3324)

Browse source 
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Co-authored-by: Hubert Chathi <hubertc@matrix.org>
Co-authored-by: Travis Ralston <travisr@matrix.org>
This commit is contained in:
Will Hunt 2021-12-28 21:16:33 +00:00 • committed by Travis Ralston
parent 3ebe4e801b
commit a05706780d
3 changed files with 59 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/3324.feature Normal file
View file

@ -0,0 +1 @@
Extend `/_matrix/client/r0/login` to accept a `m.login.appservice`, as per [MSC2778](https://github.com/matrix-org/matrix-doc/pull/2778).

27
content/application-service-api.md
View file

@ -312,10 +312,11 @@ information.
The homeserver needs to give the application service *full control* over
its namespace, both for users and for room aliases. This means that the
AS should be able to create/edit/delete any room alias in its namespace,
as well as create/delete any user in its namespace. No additional API
AS should be able to manage any users and room alias in its namespace. No additional API
changes need to be made in order for control of room aliases to be
granted to the AS. Creation of users needs API changes in order to:
granted to the AS.
Creation of users needs API changes in order to:
- Work around captchas.
- Have a 'passwordless' user.
@ -334,8 +335,26 @@ user ID without a password.
username: "_irc_example"
}
Similarly, logging in as users needs API changes in order to allow the AS to
log in without needing the user's password. This is achieved by including the
`as_token` on a `/login` request, along with a login type of
`m.login.application_service`.
POST /_matrix/client/%CLIENT_MAJOR_VERSION%/login
Authorization: Bearer YourApplicationServiceTokenHere
Content:
{
type: "m.login.application_service",
"identifier": {
"type": "m.id.user",
"user": "_irc_example"
}
}
Application services which attempt to create users or aliases *outside*
of their defined namespaces will receive an error code `M_EXCLUSIVE`.
of their defined namespaces, or log in as users outside of their defined
namespaces will receive an error code `M_EXCLUSIVE`.
Similarly, normal users who attempt to create users or aliases *inside*
an application service-defined namespace will receive the same
`M_EXCLUSIVE` error code, but only if the application service has

35
content/client-server-api/_index.md
View file

@ -1022,6 +1022,41 @@ client supports it, the client should redirect the user to the
is complete, the client will need to submit a `/login` request matching
`m.login.token`.
#### Appservice Login
An appservice can log in by providing a valid appservice token and a user within the appservice's
namespace.
{{% boxes/note %}}
Appservices do not need to log in as individual users in all cases, as they
can perform [Identity Assertion](/application-service-api#identity-assertion)
using the appservice token. However, if the appservice needs a scoped token
for a single user then they can use this API instead.
{{% /boxes/note %}}
This request must be authenticated by the [appservice `as_token`](/application-service-api#registration)
(see [Client Authentication](#client-authentication) on how to provide the token).
To use this login type, clients should submit a `/login` request as follows:
```json
{
"type": "m.login.appservice",
"identifier": {
"type": "m.id.user",
"user": "<user_id or user localpart>"
}
}
```
If the access token is not valid, does not correspond to an appservice
or the user has not previously been registered then the homeserver will
respond with an errcode of `M_FORBIDDEN`.
If the access token does correspond to an appservice, but the user id does
not lie within its namespace then the homeserver will respond with an
errcode of `M_EXCLUSIVE`.
{{% http-api spec="client-server" api="login" %}}
{{% http-api spec="client-server" api="logout" %}}