2019-11-21 23:27:28 +01:00
|
|
|
# Sign in to a homeserver
|
|
|
|
|
|
|
|
This document describes the flow of signin to a homeserver. Examples come from the `matrix.org` homeserver.
|
|
|
|
|
|
|
|
## Sign up flows
|
|
|
|
|
|
|
|
### First step
|
|
|
|
|
|
|
|
Client request the sign-in flows, once the homeserver is chosen by the user and its url is known (in the example it's `https://matrix.org`)
|
|
|
|
|
|
|
|
TODO: Complete the doc with signin flow
|
|
|
|
|
|
|
|
## Reset password
|
|
|
|
|
|
|
|
Ref: `https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-account-password-email-requesttoken`
|
|
|
|
|
|
|
|
When the user has forgotten his password, he can reset it by providing an email and a new password.
|
|
|
|
|
|
|
|
Here is the flow:
|
|
|
|
|
|
|
|
### Send email
|
|
|
|
|
|
|
|
User is asked to enter the email linked to his account and a new password.
|
|
|
|
We display a warning regarding e2e.
|
|
|
|
|
|
|
|
At the first step, we do not send the password, only the email and a client secret, generated by the application
|
|
|
|
|
|
|
|
> curl -X POST --data $'{"client_secret":"6c57f284-85e2-421b-8270-fb1795a120a7","send_attempt":0,"email":"user@domain.com"}' 'https://matrix.org/_matrix/client/r0/account/password/email/requestToken'
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
|
|
|
|
"send_attempt": 0,
|
|
|
|
"email": "user@domain.com"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
#### When the email is not known
|
|
|
|
|
|
|
|
We get a 400
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"errcode": "M_THREEPID_NOT_FOUND",
|
|
|
|
"error": "Email not found"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
#### When the email is known
|
|
|
|
|
|
|
|
We get a 200 with a `sid`
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"sid": "tQNbrREDACTEDldA"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
Then the user is asked to click on the link in the email he just received, and to confirm when it's done.
|
|
|
|
|
|
|
|
During this step, the new password is sent to the homeserver.
|
|
|
|
|
|
|
|
If the user confirms before the link is clicked, we get an error:
|
|
|
|
|
|
|
|
> curl -X POST --data $'{"auth":{"type":"m.login.email.identity","threepid_creds":{"client_secret":"6c57f284-85e2-421b-8270-fb1795a120a7","sid":"tQNbrREDACTEDldA"}},"new_password":"weak_password"}' 'https://matrix.org/_matrix/client/r0/account/password'
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"auth": {
|
|
|
|
"type": "m.login.email.identity",
|
|
|
|
"threepid_creds": {
|
|
|
|
"client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
|
|
|
|
"sid": "tQNbrREDACTEDldA"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"new_password": "weak_password"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
401
|
|
|
|
|
2019-11-22 00:04:36 +01:00
|
|
|
```json
|
2019-11-21 23:27:28 +01:00
|
|
|
{
|
|
|
|
"errcode": "M_UNAUTHORIZED",
|
|
|
|
"error": ""
|
|
|
|
}
|
2019-11-22 00:04:36 +01:00
|
|
|
```
|
2019-11-21 23:27:28 +01:00
|
|
|
|
|
|
|
### User clicks on the link
|
|
|
|
|
|
|
|
The link has the form:
|
|
|
|
|
|
|
|
https://matrix.org/_matrix/client/unstable/password_reset/email/submit_token?token=fzZLBlcqhTKeaFQFSRbsQnQCkzbwtGAD&client_secret=6c57f284-85e2-421b-8270-fb1795a120a7&sid=tQNbrREDACTEDldA
|
|
|
|
|
|
|
|
It contains the client secret, a token and the sid
|
|
|
|
|
|
|
|
When the user click the link, if validate his ownership and the new password can now be ent by the application (on user demand):
|
|
|
|
|
|
|
|
> curl -X POST --data $'{"auth":{"type":"m.login.email.identity","threepid_creds":{"client_secret":"6c57f284-85e2-421b-8270-fb1795a120a7","sid":"tQNbrREDACTEDldA"}},"new_password":"weak_password"}' 'https://matrix.org/_matrix/client/r0/account/password'
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"auth": {
|
|
|
|
"type": "m.login.email.identity",
|
|
|
|
"threepid_creds": {
|
|
|
|
"client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
|
|
|
|
"sid": "tQNbrREDACTEDldA"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"new_password": "weak_password"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
200
|
|
|
|
|
|
|
|
```json
|
|
|
|
{}
|
|
|
|
```
|
|
|
|
|
|
|
|
The password has been changed, and all the existing token are invalidated. User can now login with the new password.
|