matrix-spec-proposals/proposals/2778-appservice-login.md

# MSC2778: Providing authentication method for appservice users

Appservices within Matrix are increasingly attempting to support End-to-End Encryption. As such, they
need a way to generate devices for their users so that they can participate in E2E rooms. In order to
do so, this proposal suggests implementing an appservice extension to the 
[`POST /login` endpoint](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-login).

Appservice users do not usually need to login as they do not need their own access token, and do not
traditionally need a "device". However, E2E encryption demands that at least one user in a room has a Matrix device
which means bridge users need to be able to generate a device on demand. In the past, bridge developers
have used the bridge bot's device for all bridge users in the room, but this causes problems should the bridge
wish to only join ghosts to a room (e.g. for DMs).

## Proposal

A new `type` is to be added to `POST /login`.

`m.login.application_service`

The `/login` endpoint may now take an `access_token` in the same way that other
authenticated endpoints do. No additional parameters should be specified in the request body.

Example request

```json
{
  "type": "m.login.application_service",
  "identifier": {
    "type": "m.id.user",
    "user": "_bridge_alice"
  }
}
```

Note: Implementations MUST use the `identifier.type`=`m.id.user` method of specifying the
localpart. The deprecated top-level `user` field **cannot** use this login flow type. This
is deliberate so as to coax developers into using the new identifier format when implementing
new flows.

The response body should be unchanged from the existing `/login` specification.

If:

- The access token is not provided
- The access token does not correspond to a appservice
- The access token does not correspond to a appservice that manages this user
- Or the user has not previously been registered

Then the servers should reject with HTTP 403, with an `errcode` of `"M_FORBIDDEN"`. 

Homeservers should ignore the `access_token` parameter if a type other than
`m.login.application_service` has been provided.

The expected flow for appservices would be to `/register` their users, and
then `/login` to generate the appropriate device.

## Potential issues

This proposal means that there will be more calls to make when setting up a appservice user, when
using encryption. While this could be done during the registration step, this would prohibit creating
new devices should the appservice intentionally or inadvertently lost the client-side device data.

## Alternatives

One minor tweak to the current proposal could be to include the token as part of the auth data, rather than
being part of the header/params to the request. An argument could be made for either, but since the specification
expects the appservice to pass the token this way in all requests, including `/register`, it seems wise to keep
it that way.

Some community members have used implementation details such as a "shared secret" authentication method to
log into the accounts without having to use the /login process at all. Synapse provides such a function,
but also means the appservice can now authenticate as any user on the homeserver. This seems undesirable from a
security standpoint.

A third option could be to create a new endpoint that simply creates a new device for an appservice user on demand.
Given the rest of the matrix eco-system does this with /login, and /login is already extensible with `type`, it would
create more work for all parties involved for little benefit.

## Security considerations

The /login endpoint will generate an access token which can be used to control the appservice user, which
is superflous as the appservice `as_token` should be used to authenticate all requests on behalf of ghosts.
This can safely be ignored or used, but is an extra token hanging around.

## Unstable prefix

Implementations should use `uk.half-shot.msc2778.login.application_service` for `type` given in the
`POST /login` until this lands in a released version of the specification.

## Implementations

The proposal has been implemented by a homeserver, a bridge SDK and two bridges:

- [synapse](https://github.com/matrix-org/synapse/pull/8320)
- [mautrix-python](https://github.com/tulir/mautrix-python/commit/12d7c48ca7c15fd3ff61608369af1cf69e289aeb)
- [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp/commit/ead8a869c84d07fadc7cfcf3d522452c99faaa36)
- [matrix-appservice-bridge](https://github.com/matrix-org/matrix-appservice-bridge/pull/231/files#diff-5e93f1b51d50a44fcf0ca46ea1793c1cR851-R864)