From f87526e6151e76be1bff5279f94a6d778ee87428 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Thu, 21 Nov 2019 23:27:28 +0100 Subject: [PATCH] Login screens: reset password: add documentation --- docs/signin.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/signin.md diff --git a/docs/signin.md b/docs/signin.md new file mode 100644 index 0000000000..d90f00d361 --- /dev/null +++ b/docs/signin.md @@ -0,0 +1,118 @@ +# 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 + +{ + "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' + +```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. \ No newline at end of file