wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Address review comments

Browse source
This commit is contained in:
Andrew Morgan 2019-09-17 12:10:32 +01:00
parent 2a55310754
commit 0b67f34578
1 changed files with 53 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

117
proposals/2290-separate-threepid-bind-hs.md
View file

@ -1,8 +1,15 @@
# Separate Endpoints for Binding Threepids # Separate Endpoints for Binding Threepids
*Note: This MSC obseletes
[MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt
with changing the rules of the `bind` flag on [POST
/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid).
That endpoint is being deprecated as part of this MSC, thus MSC2229 is no
longer relevant.*
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/unstable#post-matrix-client-r0-account-3pid). /account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#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. Note that we use the term `add` when talking about and an identity server. Note that we use the term `add` when talking about
@ -28,46 +35,30 @@ in any released version of Synapse, as Synapse keeps a list of "trusted
identity servers" that acts a whitelist for what identity servers a user can identity servers" that acts a whitelist for what identity servers a user can
specify. specify.
Synapse is soon to lose this whitelist however, as part of lessening the The concept of this whitelist is being removed in this MSC however, as part
reliance of homeservers on identity servers. This cannot be done while the of lessening the reliance of homeservers on identity servers. This cannot be
homeserver is still trusting an identity server for validation of threepids. done while the homeserver is still trusting an identity server for validation
If the endpoints are split, the homeserver will handle the validation of of threepids. If the endpoints are split, the homeserver will handle the
threepids being added to user accounts, and identity servers will validate validation of threepids being added to user accounts, and identity servers
threepids being bound to themselves. will validate threepids being bound to themselves.
To solve this problem, we propose adding two new endpoints. `POST
/account/3pid/add` that is only used for adding to user's account on a
homeserver, and `POST /account/3pid/bind` that is only for binding to an
identity server of the user's choice. The existing binding endpoint (`POST
/account/3pid`) will be deprecated.
One may question why clients don't just contact an identity server directly
to bind a threepid, bypassing the implications of binding through a
homeserver. While this will work, binds should still occur through a
homeserver such that the homeserver can keep track of which binds were made,
which is important when a user wishes to deactivate their account (and remove
all of their bindings made on different identity servers).
A verification could occur on an identity server, which could then tell the
homeserver that a validation happened, but then there are security
considerations about how to authenticate an identity server in that instance
(and prevent people pretending to be identity servers and telling homeservers
about hundreds of fake threepid additions to a user's account).
This MSC obseletes
[MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt
with changing the rules of the `bind` flag on the original endpoint. Since
that endpoint is being deprecated, the MSC is no longer relevant.
## Proposal ## Proposal
Two new endpoints will be added to the Client Server API: `POST To solve this problem, two new endpoints will be added to the Client Server
/account/3pid/bind` and `POST /account/3pid/add`. Both will require API: `POST /account/3pid/bind` and `POST /account/3pid/add`. Both will
authentication. The request parameters of `POST /account/3pid/bind` are the require authentication and be rate-limited. The request parameters of `POST
same as [POST /account/3pid/bind` are the same as [POST
/account/3pid](https://matrix.org/docs/spec/client_server/unstable#post-matrix-client-r0-account-3pid), /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` minus the `bind` flag, and the contents of `three_pid_creds` have been
will simply consist of a JSON body containing `client_secret` and `sid`. brought to the top level of the request body. The request parameters of `POST
/account/3pid/add` will simply consist of a JSON body containing
`client_secret` and `sid`.
The homeserver should prevent a threepid being added to a user's account if
it already part of another user's account. However, the homeserver should not
check for existing threepids when binding to an identity server. Identity
servers do not enforce this requirement and neither should the proxying
homeserver.
An example of binding a threepid to an identity server with this new endpoint An example of binding a threepid to an identity server with this new endpoint
is as follows: is as follows:
@ -93,12 +84,10 @@ Next, the client completes the bind by calling the new endpoint on the homeserve
POST https://home.server/_matrix/client/r0/account/3pid/bind POST https://home.server/_matrix/client/r0/account/3pid/bind
{ {
"three_pid_creds": { "id_server": "example.org",
"id_server": "example.org", "id_access_token": "abc123_OpaqueString",
"id_access_token": "abc123_OpaqueString", "sid": "abc123987",
"sid": "abc123987", "client_secret": "don'tT3ll"
"client_secret": "don'tT3ll"
}
} }
``` ```
@ -161,17 +150,25 @@ 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 other, which is the exact behaviour we're trying to eliminate. Doing this
also helps backward compatibility, as explained below. also helps backward compatibility, as explained below.
This MSC also requests that the text "It is imperative that the homeserver The text "It is imperative that the homeserver keep a list of trusted
keep a list of trusted Identity Servers and only proxies to those that it Identity Servers and only proxies to those that it trusts." is to be removed
trusts." be removed from all parts of the spec, as the homeserver should no from all parts of the spec, as the homeserver should no longer need to trust
longer need to trust any identity servers. any identity servers.
## Tradeoffs ## Tradeoffs
It may be possible to reduce the two calls per flow into a single endpoint, One may question why clients don't just contact an identity server directly
but the current asynchronous approach makes it easy for a client to send a to bind a threepid, bypassing the implications of binding through a
request, go offline, have the threepid be validated, and then come online homeserver. While this will work, binds should still occur through a
again to finalize the validation afterwards. homeserver such that the homeserver can keep track of which binds were made,
which is important when a user wishes to deactivate their account (and remove
all of their bindings made on different identity servers).
A verification could occur on an identity server, which could then tell the
homeserver that a validation happened, but then there are security
considerations about how to authenticate an identity server in that instance
(and prevent people pretending to be identity servers and telling homeservers
about hundreds of fake threepid additions to a user's account).
## Backwards compatibility ## Backwards compatibility
@ -191,16 +188,8 @@ receiving a HTTP `404` error code, should either attempt to use
Reducing the homeserver's trust in identity servers should be a boost to Reducing the homeserver's trust in identity servers should be a boost to
security and improve decentralisation in the Matrix ecosystem to boot. security and improve decentralisation in the Matrix ecosystem to boot.
Caution should be taken for homeserver developers to be sure not to continue Some endpoints of the Client Server API allow a user to provide an
to use user-provided identity servers for any sensitive tasks once it removes `id_server` parameter. Caution should be taken for homeserver developers to
the concept of a trusted identity server list. stop using these user-provided identity servers for any sensitive tasks, such
as password reset or account registration, if it removes the concept of a
## Conclusion trusted identity server list.
This MSC helps to minimize the homeserver's trust in an identity server even
further to the point where it is only used for binding addresses for lookup -
which was the original intention of identity servers to begin with.
Additionally, by clearly separating the original threepid endpoint into two
endpoints that each have a clear intention, the concept of attaching
threepids to a Matrix user becomes a lot easier to reason about.