diff --git a/changelogs/client_server/newsfragments/3324.feature b/changelogs/client_server/newsfragments/3324.feature new file mode 100644 index 00000000..346de35d --- /dev/null +++ b/changelogs/client_server/newsfragments/3324.feature @@ -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). \ No newline at end of file diff --git a/content/application-service-api.md b/content/application-service-api.md index e324bba0..02d7ed6f 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -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 diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 1f50ae7a..f9ef6063 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1024,6 +1024,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": "" + } +} +``` + +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" %}}