You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# 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).
|
|
|
|
Another advantage this provides is that an appservice can now be used to generate access tokens for
|
|
any user in it's namespace without having to set a password for that user, which may be useful in the
|
|
case of software where maintaining password(s) in the configuration is undesirable.
|
|
|
|
## 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
|
|
|
|
None
|
|
|
|
## 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) |