diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index 83883c7850a..398e65139a4 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -1,5 +1,16 @@ # Allowing 3PID Owners to Rebind +## Note: This MSC has been made obsolete by MSC2290. + +MSC2290 provides two separate API endpoints, one for adding a 3PID to the +homeserver, and another for binding to an identity server. These new +endpoints will allow the homeserver to enforce rules on emails that already +exist on the homeserver, only when modifying homeserver email, while only +needing to forward requests when binding to an identity server. This removes +the problem MSC2229 is trying to solve, and it is thus made obselete. + +--- + ``` 3PID noun diff --git a/proposals/2290-separate-threepid-bind-hs.md b/proposals/2290-separate-threepid-bind-hs.md new file mode 100644 index 00000000000..8c8996993bb --- /dev/null +++ b/proposals/2290-separate-threepid-bind-hs.md @@ -0,0 +1,223 @@ +# Separate Endpoints for Binding Threepids + +*Note: This MSC obsoletes +[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 +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). +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 +and an identity server. Note that we use the term `add` when talking about +adding a threepid to a homeserver, and `bind` when binding a threepid to an +identity server. This terminology will be used throughout the rest of this +proposal. + +Typically, when using the `/account/3pid` endpoint, the identity server +handles the verification -- either by sending an email to an email address, +or a SMS message to a phone number. Once completed, the homeserver will check +with the identity server that verification had indeed happened, and if so, +the threepid would be either added to the homeserver, or added to the +homeserver and bound to the identity server simultaneously. + +Now, consider the fact that the identity server used in this process is +provided by the user, using the endpoint's `id_server` parameter. If the user were +to supply a malicious identity server that would immediately answer "yes" to +any threepid validation, then the user could add any threepid to their +account on the homeserver (which is likely not something homeserver admins want). + +To be clear, this is not a long-standing security issue. It is not a problem +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 +specify. + +The concept of this whitelist is being removed in this MSC 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 bound to themselves. + +## Proposal + +To solve this problem, two new endpoints will be added to the Client Server +API: `POST /account/3pid/bind` and `POST /account/3pid/add`. Binding to an +identity server will require standard authentication, whereas adding a 3pid +to a user account will require [User-Interactive +Authentication](https://matrix.org/docs/spec/client_server/r0.5.0#user-interactive-authentication-api). +The latter is to prevent someone from adding a 3pid (which can be used to +reset passwords) to someone who's left their account open on a public +computer, without needing their password to do so. + +Both endpoints will be rate-limited. The request parameters of `POST +/account/3pid/bind` are the same as [POST +/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid), +minus the `bind` flag, and the contents of `three_pid_creds` have been +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's 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 +is as follows: + +First the client must request the threepid be validated by its chosen +identity server. + +``` +POST https://identity.server/_matrix/identity/v2/validate/email/requestToken + +{ + "client_secret": "don'tT3ll", + "email": "bob@example.com", + "send_attempt": 1 +} +``` + +The identity server must send an email to the specified address, including a +link to a URL on the identity server which will accept the validation session +ID, the given client_secret, and a randomly-generated token. + +Once an email has been sent, the user clicks the link in the email, which +notifies the identity server that the email has been verified. + +Next, the client completes the bind by calling the new endpoint on the +homeserver: + +``` +POST https://home.server/_matrix/client/r0/account/3pid/bind + +{ + "id_server": "example.org", + "id_access_token": "abc123_OpaqueString", + "sid": "abc123987", + "client_secret": "don'tT3ll" +} +``` + +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 +and notify the user. The homeserver will remember this bind and the identity +server it occurred on so that it can perform an unbind later if the user +requests it or their account is deactivated. + +The threepid has now been bound on the user's requested identity server +without causing that threepid to be used for password resets or any other +homeserver-related functions. + +For completeness, here is an example of adding a threepid to the homeserver +only, using the `/account/3pid/add` endpoint: + +The homeserver is validating the threepid in this instance, so the client +must use the `/requestToken` endpoint of the homeserver: + +``` +POST https://home.server/_matrix/client/r0/account/3pid/email/requestToken + +{ + "client_secret": "don'tT3ll", + "email": "bob@example.com", + "send_attempt": 1, +} +``` + +Here the homeserver must send an email to the specified address, including a +link to a URL on the homeserver which will accept the validation session ID, +the given client_secret, and a randomly-generated token. + +Once an email has been sent, the user clicks the link in the email, which +notifies the homeserver that the threepid has been verified. + +The client then sends a request to the endpoint on the homeserver to add +the threepid to a user's account. + +``` +POST https://home.server/_matrix/client/r0/account/3pid/add + +{ + "sid": "abc123987", + "client_secret": "don'tT3ll" +} +``` + +The homeserver checks the threepid validation session referred to by the +given ID and client_secret was validated, and if so adds the threepid to the +user's account. + +To achieve the above flows, some changes need to be made to existing +endpoints. The [POST +/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid) +endpoint is deprecated as the two new endpoints replace its functionality. +The `bind` parameter is to 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 in [Backwards +compatibility](#backwards-compatibility). + +Either the homeserver itself or a service that the homeserver delegates to +should be handling the sending of validation messages, not a user-provided +server. Any mention of the homeserver being able to proxy to an identity +server in the below endpoint descriptions: + +* [POST /account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) +* [POST /account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) +* [POST /register/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-register-email-requesttoken) +* [POST /register/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-register-msisdn-requesttoken) +* [POST /account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-password-email-requesttoken) +* [POST /account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-password-msisdn-requesttoken) + +As well as the text "It is imperative that the homeserver keep a list of +trusted Identity Servers and only proxies to those that it trusts." is to be +removed from all parts of the spec, as the homeserver should no longer need +to trust any identity servers. + +## Tradeoffs + +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). + +## Backwards compatibility + +A new flag will be added to `/versions`' unstable_features section, +`m.separate_add_and_bind`. If this flag is present and set to `true`, then +clients should use the new API endpoints to carry out threepid adds and +binds. If this flag is not present or set to `false`, clients should use +`/account/3pid`, being aware that they can only bind threepids to the +homeserver, not the identity server. + +Old matrix clients will continue to use the `/account/3pid` endpoint. 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 to +the homeserver, but not bind to the identity server. New homeservers must +ignore any `id_server` information passed to this endpoint. + +## Security considerations + +Reducing the homeserver's trust in identity servers should be a boost to +security and improve decentralisation in the Matrix ecosystem to boot. + +Some endpoints of the Client Server API allow a user to provide an +`id_server` parameter. Caution should be taken for homeserver developers to +stop using these user-provided identity servers for any sensitive tasks where +possible, such as password reset or account registration, if it removes the +concept of a trusted identity server list.