Depending on whether the `bind` flag is `true` or `false`, the threepid will
Depending on whether the `bind` flag is `true` or `false`, the threepid will
be bound to either a user's account on the homeserver, or both the homeserver
be bound to either a user's account on the homeserver, or both the homeserver
and an identity server.
and an identity server.
A threepid can be bound to an identity server to allow other users to find
For context a threepid can be bound to an identity server to allow other users to find
their Matrix ID using their email address or phone number. A threepid can
their Matrix ID using their email address or phone number. A threepid can
also be bound to a user's account on the homeserver. This allows that
also be bound to a user's account on the homeserver. This allows the
threepid to be used for message notifications, login, password reset, and
threepid to be used for message notifications, login, password reset, and
other important functions.
other important functions.
Typically, when using the `POST /_matrix/client/r0/account/3pid` endpoint,
Typically, when using the `POST /_matrix/client/r0/account/3pid` endpoint,
the identity server handles the verification -- either by sending an email to
the identity server handles the verification -- either by sending an email to
the email address, or a SMS message to the phone number. Once completed, the
an email address, or a SMS message to a phone number. Once completed, the
homeserver would check with the identity server that verification had indeed
homeserver will check with the identity server that verification had indeed
happened, and if so, the threepid would be bound (again, either to the
happened, and if so, the threepid would be bound (again, either to the
homeserver, or the homeserver and identity server simultaneously).
homeserver, or the homeserver and identity server simultaneously).
@ -28,7 +28,7 @@ account on the homeserver (which is likely not something homeserver admins want)
To solve this problem, we propose adding a second endpoint that is only used
To solve this problem, we propose adding a second endpoint that is only used
for binding to an identity server of the user's choice. This endpoint will
for binding to an identity server of the user's choice. This endpoint will
not bind the threepid to the user's account on the homeserver, only on the
not bind the threepid to the user's account on the homeserver, only the
identity server.
identity server.
In addition, the existing binding endpoint will lose the ability to bind
In addition, the existing binding endpoint will lose the ability to bind
@ -67,12 +67,12 @@ the MSC is no longer relevant.
## Proposal
## Proposal
A new endpoint will be added to the Client Server API: `POST /_matrix/client/r0/account/3pid/identity/bind`, and requires authentication.
A new endpoint will be added to the Client Server API: `POST
/_matrix/client/r0/account/3pid/identity/bind`, and will require
The endpoint definition is the same as `POST
authentication. The endpoint definition is the same as `POST
/_matrix/client/r0/account/3pid`, minus the `bind` flag.
/_matrix/client/r0/account/3pid`, minus the `bind` flag.
An example of binding a threepid to an identity server with this new endpoint:
An example of binding a threepid to **an identity server only** with this new endpoint is as follows:
First the client must request the threepid be validated by its chosen identity server.
First the client must request the threepid be validated by its chosen identity server.
@ -104,11 +104,15 @@ POST https://home.server/_matrix/client/r0/account/3pid/identity/bind
}
}
```
```
The homeserver will then make a bind request on behalf of the user to the
The homeserver will then make a bind request to the specified identity server
specified identity server. The homeserver will record if the bind was
on behalf of the user. The homeserver will record if the bind was successful
successful and notify the user.
and notify the user.
The threepid has now been binded on the user's identity server without
causing that threepid to be used for password resets or any other
homeserver-related functions.
And for completeness, here is an example of binding a threepid to the
For completeness, here is an example of binding a threepid to the
homeserver only, using the old endpoint:
homeserver only, using the old endpoint:
The homeserver is validating the threepid in this instance, so the client
The homeserver is validating the threepid in this instance, so the client
@ -125,10 +129,10 @@ POST https://home.server/_matrix/client/r0/account/3pid/email/requestToken
```
```
Once an email has been sent, the user clicks the link in the email, which
Once an email has been sent, the user clicks the link in the email, which
notifies the homeserver that the email has been verified.
notifies the homeserver that the threepid has been verified.
The client then sends a request to the old endpoint to bind the threepid to
The client then sends a request to the old endpoint on the homeserver to bind
user's account.
the threepid to user's account.
```
```
POST /_matrix/client/r0/account/3pid
POST /_matrix/client/r0/account/3pid
@ -143,14 +147,15 @@ POST /_matrix/client/r0/account/3pid
The threepid will then be bound to the user's account.
The threepid will then be bound to the user's account.
Users will be able to perform binds to an identity server for a threepid even if that threepid has not been bound to the user's account on the homeserver before.
The achieve the above flows, some changes need to be made to existing
endpoints. This MSC requests that the `id_server` and `id_access_token`
The achieve the above flow, some changes need to be made to existing
parameters be removed from the Client-Server API's [POST
endpoints as well. This MSC requests that the `id_server` and
`id_access_token` parameters be removed from the Client-Server API's [POST