Skip to content

Commit f608c48

Browse files
turt2liveturt2live
authored
Merge pull request #2290 from matrix-org/anoa/msc_separate_hs_api
MSC2290: Separate Endpoints for Threepid Binding
2 parents 3d60e04 + 46e7137 commit f608c48

File tree

2 files changed

+234
-0
lines changed

2 files changed

+234
-0
lines changed

‎proposals/2229-rebind-existing-3pid.md

+11
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,16 @@
11
# Allowing 3PID Owners to Rebind
22

3+
## Note: This MSC has been made obsolete by MSC2290.
4+
5+
MSC2290 provides two separate API endpoints, one for adding a 3PID to the
6+
homeserver, and another for binding to an identity server. These new
7+
endpoints will allow the homeserver to enforce rules on emails that already
8+
exist on the homeserver, only when modifying homeserver email, while only
9+
needing to forward requests when binding to an identity server. This removes
10+
the problem MSC2229 is trying to solve, and it is thus made obselete.
11+
12+
---
13+
314
```
415
3PID
516
noun

‎proposals/2290-separate-threepid-bind-hs.md

+223
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# Separate Endpoints for Binding Threepids
2+
3+
*Note: This MSC obsoletes
4+
[MSC2229](https://github.com/matrix-org/matrix-doc/pull/2229), which dealt
5+
with changing the rules of the `bind` flag on [POST
6+
/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid).
7+
That endpoint is being deprecated as part of this MSC, thus MSC2229 is no
8+
longer relevant.*
9+
10+
On the Client Server API there is currently a single endpoint for binding a
11+
threepid (an email or a phone number): [POST
12+
/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid).
13+
Depending on whether the `bind` flag is `true` or `false`, the threepid will
14+
be bound to either a user's account on the homeserver, or both the homeserver
15+
and an identity server. Note that we use the term `add` when talking about
16+
adding a threepid to a homeserver, and `bind` when binding a threepid to an
17+
identity server. This terminology will be used throughout the rest of this
18+
proposal.
19+
20+
Typically, when using the `/account/3pid` endpoint, the identity server
21+
handles the verification -- either by sending an email to an email address,
22+
or a SMS message to a phone number. Once completed, the homeserver will check
23+
with the identity server that verification had indeed happened, and if so,
24+
the threepid would be either added to the homeserver, or added to the
25+
homeserver and bound to the identity server simultaneously.
26+
27+
Now, consider the fact that the identity server used in this process is
28+
provided by the user, using the endpoint's `id_server` parameter. If the user were
29+
to supply a malicious identity server that would immediately answer "yes" to
30+
any threepid validation, then the user could add any threepid to their
31+
account on the homeserver (which is likely not something homeserver admins want).
32+
33+
To be clear, this is not a long-standing security issue. It is not a problem
34+
in any released version of Synapse, as Synapse keeps a list of "trusted
35+
identity servers" that acts a whitelist for what identity servers a user can
36+
specify.
37+
38+
The concept of this whitelist is being removed in this MSC however, as part
39+
of lessening the reliance of homeservers on identity servers. This cannot be
40+
done while the homeserver is still trusting an identity server for validation
41+
of threepids. If the endpoints are split, the homeserver will handle the
42+
validation of threepids being added to user accounts, and identity servers
43+
will validate threepids being bound to themselves.
44+
45+
## Proposal
46+
47+
To solve this problem, two new endpoints will be added to the Client Server
48+
API: `POST /account/3pid/bind` and `POST /account/3pid/add`. Binding to an
49+
identity server will require standard authentication, whereas adding a 3pid
50+
to a user account will require [User-Interactive
51+
Authentication](https://matrix.org/docs/spec/client_server/r0.5.0#user-interactive-authentication-api).
52+
The latter is to prevent someone from adding a 3pid (which can be used to
53+
reset passwords) to someone who's left their account open on a public
54+
computer, without needing their password to do so.
55+
56+
Both endpoints will be rate-limited. The request parameters of `POST
57+
/account/3pid/bind` are the same as [POST
58+
/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid),
59+
minus the `bind` flag, and the contents of `three_pid_creds` have been
60+
brought to the top level of the request body. The request parameters of `POST
61+
/account/3pid/add` will simply consist of a JSON body containing
62+
`client_secret` and `sid`.
63+
64+
The homeserver should prevent a threepid being added to a user's account if
65+
it's already part of another user's account. However, the homeserver should not
66+
check for existing threepids when binding to an identity server. Identity
67+
servers do not enforce this requirement and neither should the proxying
68+
homeserver.
69+
70+
An example of binding a threepid to an identity server with this new endpoint
71+
is as follows:
72+
73+
First the client must request the threepid be validated by its chosen
74+
identity server.
75+
76+
```
77+
POST https://identity.server/_matrix/identity/v2/validate/email/requestToken
78+
79+
{
80+
"client_secret": "don'tT3ll",
81+
"email": "[email protected]",
82+
"send_attempt": 1
83+
}
84+
```
85+
86+
The identity server must send an email to the specified address, including a
87+
link to a URL on the identity server which will accept the validation session
88+
ID, the given client_secret, and a randomly-generated token.
89+
90+
Once an email has been sent, the user clicks the link in the email, which
91+
notifies the identity server that the email has been verified.
92+
93+
Next, the client completes the bind by calling the new endpoint on the
94+
homeserver:
95+
96+
```
97+
POST https://home.server/_matrix/client/r0/account/3pid/bind
98+
99+
{
100+
"id_server": "example.org",
101+
"id_access_token": "abc123_OpaqueString",
102+
"sid": "abc123987",
103+
"client_secret": "don'tT3ll"
104+
}
105+
```
106+
107+
The homeserver will then make a bind request to the specified identity server
108+
on behalf of the user. The homeserver will record if the bind was successful
109+
and notify the user. The homeserver will remember this bind and the identity
110+
server it occurred on so that it can perform an unbind later if the user
111+
requests it or their account is deactivated.
112+
113+
The threepid has now been bound on the user's requested identity server
114+
without causing that threepid to be used for password resets or any other
115+
homeserver-related functions.
116+
117+
For completeness, here is an example of adding a threepid to the homeserver
118+
only, using the `/account/3pid/add` endpoint:
119+
120+
The homeserver is validating the threepid in this instance, so the client
121+
must use the `/requestToken` endpoint of the homeserver:
122+
123+
```
124+
POST https://home.server/_matrix/client/r0/account/3pid/email/requestToken
125+
126+
{
127+
"client_secret": "don'tT3ll",
128+
"email": "[email protected]",
129+
"send_attempt": 1,
130+
}
131+
```
132+
133+
Here the homeserver must send an email to the specified address, including a
134+
link to a URL on the homeserver which will accept the validation session ID,
135+
the given client_secret, and a randomly-generated token.
136+
137+
Once an email has been sent, the user clicks the link in the email, which
138+
notifies the homeserver that the threepid has been verified.
139+
140+
The client then sends a request to the endpoint on the homeserver to add
141+
the threepid to a user's account.
142+
143+
```
144+
POST https://home.server/_matrix/client/r0/account/3pid/add
145+
146+
{
147+
"sid": "abc123987",
148+
"client_secret": "don'tT3ll"
149+
}
150+
```
151+
152+
The homeserver checks the threepid validation session referred to by the
153+
given ID and client_secret was validated, and if so adds the threepid to the
154+
user's account.
155+
156+
To achieve the above flows, some changes need to be made to existing
157+
endpoints. The [POST
158+
/account/3pid](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid)
159+
endpoint is deprecated as the two new endpoints replace its functionality.
160+
The `bind` parameter is to be removed, with the endpoint functioning as if
161+
`bind` was `false`. Allowing an endpoint to add a threepid to both the
162+
identity server and homeserver at the same time requires one to trust the
163+
other, which is the exact behaviour we're trying to eliminate. Doing this
164+
also helps backward compatibility, as explained in [Backwards
165+
compatibility](#backwards-compatibility).
166+
167+
Either the homeserver itself or a service that the homeserver delegates to
168+
should be handling the sending of validation messages, not a user-provided
169+
server. Any mention of the homeserver being able to proxy to an identity
170+
server in the below endpoint descriptions:
171+
172+
* [POST /account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken)
173+
* [POST /account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken)
174+
* [POST /register/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-register-email-requesttoken)
175+
* [POST /register/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-register-msisdn-requesttoken)
176+
* [POST /account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-password-email-requesttoken)
177+
* [POST /account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-password-msisdn-requesttoken)
178+
179+
As well as the text "It is imperative that the homeserver keep a list of
180+
trusted Identity Servers and only proxies to those that it trusts." is to be
181+
removed from all parts of the spec, as the homeserver should no longer need
182+
to trust any identity servers.
183+
184+
## Tradeoffs
185+
186+
One may question why clients don't just contact an identity server directly
187+
to bind a threepid, bypassing the implications of binding through a
188+
homeserver. While this will work, binds should still occur through a
189+
homeserver such that the homeserver can keep track of which binds were made,
190+
which is important when a user wishes to deactivate their account (and remove
191+
all of their bindings made on different identity servers).
192+
193+
A verification could occur on an identity server, which could then tell the
194+
homeserver that a validation happened, but then there are security
195+
considerations about how to authenticate an identity server in that instance
196+
(and prevent people pretending to be identity servers and telling homeservers
197+
about hundreds of fake threepid additions to a user's account).
198+
199+
## Backwards compatibility
200+
201+
A new flag will be added to `/versions`' unstable_features section,
202+
`m.separate_add_and_bind`. If this flag is present and set to `true`, then
203+
clients should use the new API endpoints to carry out threepid adds and
204+
binds. If this flag is not present or set to `false`, clients should use
205+
`/account/3pid`, being aware that they can only bind threepids to the
206+
homeserver, not the identity server.
207+
208+
Old matrix clients will continue to use the `/account/3pid` endpoint. This
209+
MSC removes the `bind` parameter and forces `/account/3pid` calls to act as
210+
if `bind` was set to `false`. Old clients will still be able to add 3pids to
211+
the homeserver, but not bind to the identity server. New homeservers must
212+
ignore any `id_server` information passed to this endpoint.
213+
214+
## Security considerations
215+
216+
Reducing the homeserver's trust in identity servers should be a boost to
217+
security and improve decentralisation in the Matrix ecosystem to boot.
218+
219+
Some endpoints of the Client Server API allow a user to provide an
220+
`id_server` parameter. Caution should be taken for homeserver developers to
221+
stop using these user-provided identity servers for any sensitive tasks where
222+
possible, such as password reset or account registration, if it removes the
223+
concept of a trusted identity server list.

0 commit comments

Comments
 (0)