matrix-spec-proposals/proposals/2078-homeserver-password-resets.md

# MSC2078 - Sending Third-Party Request Tokens via the Homeserver

This MSC proposes removing the current requirement of the identity server to
send third-party request tokens, and allows homeservers to implement the
functionality instead. These request tokens are used to verify the identity of
the request auther as an owner of the third-party identity (3PID). This can be
used for binding a 3PID to an account, or for resetting passwords via email or
SMS. The latter is what this proposal mainly focuses on, but be aware that it
allows for any task that requires requesting a token through a 3PID to be
taken on by the homeserver instead of the identity server.

The intention is to put less trust in the identity server, which is currently
one of the most centralised components of Matrix. As it stands, an attacker in
control of a identity server can reset a user's password if the identity server
is considered trusted by that homeserver, and the user has registered at least
one 3PID. This is due to the identity server currently handling the job of
confirming the user's control of that identity.

The MSC aims to simply clarify that homeservers can take on the responsibility
of sending password reset tokens themselves.

## Proposal

Currently when a client requests a password reset, it makes a call to either
[/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken)
or
[/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken).
This request is supplied all the necessary details as well as an `id_server`
field containing the address of a identity server trusted by the homeserver.

The `id_server` field is currently required as the homeserver must know where
to proxy the request to. This MSC proposes not to change the requirements of
this field. Instead, it asks to clarify that the homeserver is allowed to not
proxy the request, but carry it out itself. This would mean the homeserver can
both send password reset tokens (via email or SMS), as well as accept requests
an endpoint (with the same parameters as
[/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken))
to verify that token.

Consideration was taken not to make `id_server` and optional field. Let's
assume for a moment that it was optional. Now, a client could send a request to
`/requestToken` omitting the `id_server` field. The homeserver however has
opted to continue proxying `/requestToken` to the identity server, even though
it knows this is potentially insecure. The homeserver now has no idea which
identity server to proxy the request to, and must return a failure to the
client. The client could then make another request with an `id_server`, but
we've now made two requests that ended up in the same outcome, instead of one,
in hopes of saving a very small amount of bandwidth by omitting the field
originally.

An additional complication is that in the case of SMS, a full link to reset
passwords is not sent, but a short code. The client then asks the user to enter
this code, however the client may now not know where to send the code. Should
it send it to the identity server or the homeserver? Which sent out the code?

In order to combat this problem, the field `submit_url` should be added in the
response from both the email and msisdn variants of the `/requestToken`
Client-Server API, if and only if the verification message contains a code the
user is expected to enter into the client (for instance in the case of a short
code through SMS). It SHOULD be in the form of
`/_matrix/identity/api/v1/validate/{3pid_type}/submitToken`, similar to the
[same endpoint that exists in the Identity-Server
API](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken).
If this field is omitted, the client MUST continue the same behaviour from
before, which is to send the token to the identity server directly. This is
intended for backwards compatibility with older servers.

If the client receives a response to `/requestToken` with `submit_url`, it MUST
accept the token from user input, then make a POST request to the content of
`submit_url` with the `sid`, `client_secret` and user-entered token.
`submit_url` can lead to anywhere the homeserver deems necessary for
verification. This data MUST be submitted as a JSON body.

An example exchange from the client's perspective is shown below:

```
POST https://homeserver.tld/_matrix/client/r0/account/password/email/requestToken

{
  "client_secret": "monkeys_are_AWESOME",
  "email": "alice@homeserver.tld",
  "send_attempt": 1,
  "id_server": "id.example.com"
}
```

If the server responds with a `submit_url` field, it means the client should
collect a token from the user and then submit it to the provided URL.

```
{
  "sid": "123abc",
  "submit_url": "https://homeserver.tld/_matrix/identity/api/v1/validate/msisdn/submitToken"
}
```

Since a `submit_url` was provided, the client will now collect a token from the
user, say "123456", and then submit that as a POST request to the
`"submit_url"`.

```
POST https://homeserver.tld/_matrix/identity/api/v1/validate/msisdn/submitToken

{
  "sid": "123abc",
  "client_secret": "monkeys_are_AWESOME",
  "token": "123456"
}
```

The client will then receive an appropriate response:

```
{
  "success": true
}
```

If the client did not receive a `submit_url` field, they should instead assume
that verification will be completed out of band (e.g. the user clicks a link in
their email and makes the submitToken request with their web browser).

## Tradeoffs

If homeservers choose to not proxy the request, they will need to implement the
ability to send emails and/or SMS messages. This is left as a detail for the
homeserver implementation.

## Future Considerations

At some point we should look into removing the `id_server` field altogether and
removing any email/SMS message sending from the identity server. This would
drastically reduce the amount of trust needed in the identity server and its
required ability. This is, however, a good first step.