element-android/docs/signin.md

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'

{
  "client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
  "send_attempt": 0,
  "email": "user@domain.com"
}

When the email is not known

We get a 400

{
  "errcode": "M_THREEPID_NOT_FOUND",
  "error": "Email not found"
}

When the email is known

We get a 200 with a sid

{
  "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'

{
  "auth": {
    "type": "m.login.email.identity",
    "threepid_creds": {
      "client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
      "sid": "tQNbrREDACTEDldA"
    }
  },
  "new_password": "weak_password"
}

401

{
  "errcode": "M_UNAUTHORIZED",
  "error": ""
}

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'

{
  "auth": {
    "type": "m.login.email.identity",
    "threepid_creds": {
      "client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
      "sid": "tQNbrREDACTEDldA"
    }
  },
  "new_password": "weak_password"
}

200

{}

The password has been changed, and all the existing token are invalidated. User can now login with the new password.