archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Two new endpoints instead of one

Browse Source
pull/977/head
Andrew Morgan 5 years ago
parent 5193c319e7
commit cb7c072edb
2 changed files with 55 additions and 39 deletions
Show Stats Download Patch File Download Diff File

2
proposals/2229-rebind-existing-3pid.md
Unescape Escape View File

@ -1,5 +1,7 @@
# Allowing 3PID Owners to Rebind # Allowing 3PID Owners to Rebind
## Note: This MSC has been made obselete by MSC2290.
``` ```
3PID 3PID
noun noun

92
proposals/2290-separate-threepid-bind-hs.md
Unescape Escape View File

@ -2,7 +2,7 @@
On the Client Server API there is currently a single endpoint for binding a On the Client Server API there is currently a single endpoint for binding a
threepid (an email or a phone number): [POST threepid (an email or a phone number): [POST
/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid). /account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid).
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.
@ -26,26 +26,23 @@ to supply a malicious identity server that would immediately answer "yes" to
any threepid validation, then the user could add any threepid to their any threepid validation, then the user could add any threepid to their
account on the homeserver (which is likely not something homeserver admins want). 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 be clear, this is not a long-standing security issue. It is not a problem
for binding to an identity server of the user's choice. This endpoint will in any released version of Synapse, as Synapse keeps a list of "trusted
not bind the threepid to the user's account on the homeserver, only the identity servers" that acts a whitelist for what identity servers a user can
identity server. specify.
In addition, the existing binding endpoint will lose the ability to bind The requirement for homeservers to keep this whitelist is soon to be lost
threepids to an identity server, by removing its `bind` flag. Instead, it however, as part of lessening the reliance of homeservers on identity
will solely be used to bind to the user's account on the homeserver. servers. This cannot be done while the homeserver is still trusting an
identity server for validation of threepids. If the endpoints are split, the
homeserver will handle the validation of threepids being added to user
accounts, and identity servers will validate threepids being added to their
own database.
To be clear, the above issue is not a long-standing security issue. Indeed it To solve this problem, we propose adding two new endpoints. One that is only
is not a problem in any released version of Synapse, as Synapse keeps a list used for binding to user's account, and another that is only for binding to
of "trusted identity servers" that acts a whitelist for what identity servers an identity server of the user's choice. The existing binding endpoint will
a user can specify. be deprecated.
Synapse is soon to lose this whitelist however, as part of lessening the
reliance of homeservers on identity servers. This cannot be done while the
homeserver is still trusting an identity server for validation of threepids.
If the endpoints are split, the homeserver will handle the validation of
threepids being added to user accounts, and identity servers will validate
threepids being added to their own database.
One may question why clients don't just contact an identity server directly One may question why clients don't just contact an identity server directly
to bind a threepid, bypassing the implications of binding through a to bind a threepid, bypassing the implications of binding through a
@ -62,18 +59,21 @@ about hundreds of fake binds to a user's account).
This MSC obseletes This MSC obseletes
[MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt [MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt
with changing the rules of the `bind` flag. Since this flag is being removed, with changing the rules of the `bind` flag on the original endpoint. Since
the MSC is no longer relevant. that endpoint is being deprecated, the MSC is no longer relevant.
## Proposal ## Proposal
A new endpoint will be added to the Client Server API: `POST Two new endpoints will be added to the Client Server API: `POST
/account/3pid/identity/bind`, and will require authentication. The endpoint /account/3pid/bind` and `POST /account/3pid/add`. Both will require
definition is the same as [POST authentication. The request parameters of `POST /account/3pid/bind` are the
/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid), same as [POST
minus the `bind` flag. /account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid),
minus the `bind` flag. The request parameters of `POST /account/3pid/add`
will simply consist of a JSON body containing `client_secret` and `sid`.
An example of binding a threepid to **an identity server only** with this new endpoint is as follows: 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.
@ -93,7 +93,7 @@ notifies the identity server that the email has been verified.
Next, the client completes the bind by calling the new endpoint on the homeserver: Next, the client completes the bind by calling the new endpoint on the homeserver:
``` ```
POST https://home.server/_matrix/client/r0/account/3pid/identity/bind POST https://home.server/_matrix/client/r0/account/3pid/bind
{ {
"three_pid_creds": { "three_pid_creds": {
@ -109,8 +109,8 @@ The homeserver will then make a bind request to the specified identity server
on behalf of the user. The homeserver will record if the bind was successful on behalf of the user. The homeserver will record if the bind was successful
and notify the user. and notify the user.
The threepid has now been binded on the user's identity server without The threepid has now been binded on the user's requested identity server
causing that threepid to be used for password resets or any other without causing that threepid to be used for password resets or any other
homeserver-related functions. homeserver-related functions.
For completeness, here is an example of binding a threepid to the For completeness, here is an example of binding a threepid to the
@ -136,7 +136,7 @@ The client then sends a request to the old endpoint on the homeserver to bind
the threepid to user's account. the threepid to user's account.
``` ```
POST /_matrix/client/r0/account/3pid POST /_matrix/client/r0/account/3pid/bind
{ {
"three_pid_creds": { "three_pid_creds": {
@ -151,15 +151,20 @@ The threepid will then be bound to the user's account.
The achieve the above flows, some changes need to be made to existing 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` endpoints. This MSC requests that the `id_server` and `id_access_token`
parameters be removed from the Client-Server API's [POST parameters be removed from the Client-Server API's [POST
/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) /account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-email-requesttoken)
and [POST and [POST
/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) /account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid-msisdn-requesttoken)
endpoints, as these endpoints are now only intended for the homeserver to endpoints, as these endpoints are now only intended for the homeserver to
send validation requests from. Additionally, the same parameters will be send validation requests from.
removed from the [POST
/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid) endpoint's Additionally, the [POST
`three_pid_creds` parameter as an identity server is no longer required to /account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid)
perform verification. endpoint is deprecated as the two new endpoints replace its functionality.
The `bind` endpoint will also be removed, with the endpoint functioning as if
`bind` was `false`. Allowing an endpoint to add a threepid to both the
identity server and homeserver at the same time requires one to trust the
other, which is the exact behaviour we're trying to eliminate. Doing this
also helps backward compatibility, as explained below.
This MSC also requests that the text "It is imperative that the homeserver This MSC also requests that the text "It is imperative that the homeserver
keep a list of trusted Identity Servers and only proxies to those that it keep a list of trusted Identity Servers and only proxies to those that it
@ -175,7 +180,16 @@ again to finalize the validation afterwards.
## Backwards compatibility ## Backwards compatibility
TODO Old matrix clients will continue to use the `/account/3pid` endpoint. As this
MSC removes the `bind` parameter and forces `/account/3pid` calls to act as
if `bind` was set to `false`, old clients will still be able to add 3pids,
but they will only be added to the homeserver, not the identity server. New
homeservers will ignore any `id_server` information passed to this endpoint.
New matrix clients running with old homeservers should try their desired
endpoint (either `/account/3pid/add` or `/account/3pid/bind`) and on
receiving a HTTP `404` error code, should either attempt to use
`/account/3pid` with the `bind` parameter or give up, at their discretion.
## Security considerations ## Security considerations

Write Preview
Loading…
Cancel
Save