Add password reset initiated via web form

[mman]

New Feature / Enhancement Checklist

• [x ] I am not disclosing a vulnerability.
• [ x] I am not just asking a question.
• [ x] I have searched through existing issues.

Current Limitation

When a user needs to change his/her password, a POST request has to be performed to the REST endpoint /parse/requestPasswordReset with appropriately filled HTTP headers, namely X-Parse-Application-Id and X-Parse-REST-API-Key.

This is typically handled via JS, iOS, or Android client side SDK, and can not be triggered via plain HTML email or HTML webpage by simply using a form, without resorting to JavaScript XHR.

Example Use Case

1. User receives an HTML email with simple button saying: To change your password, click the button below.
2. The button click invokes simple HTTP form POST request with username filed to a parse-server.
3. User is redirected to a webpage saying: Instructions to reset your password were sent to your email address.

Feature / Enhancement Description

I would like to offer my users a feature where they can change their password by clicking a link directly from HTML email, by simply HTTP POST-ing their username (email address) to some API endpoint to avoid use of client side JavaScript.

After they click the link, they should be redirected to a page informing them that the instructions to reset the password were sent to their email address.

Looking at the current state of https://github.com/parse-community/parse-server/blob/master/src/Routers/PublicAPIRouter.js I propose to modify POST to /request_password_reset to start the password reset flow when only username is present.

This is in line with how the /resend_verification_email endpoint works.

The functionality will then be as follows:

1. HTML email uses a form and button that does POST /request_password_reset that requires username. Parse Server generates password reset token in a db, sends password reset email with username, and token, and redirects to password_reset_initiated.html.
2. password reset email contains button with link to: GET /request_password_reset with requires username, and token, and redirects to choose_new_password.html
3. choose_new_password.html form prompts for new password, and submits to:
4. POST /request_password_reset with username, token, and new_password.
5. Password is changed in a db, when token valid, and user is redirected to password_changed.html, or to invalid_link.html when token already expired.

Example implementation is provided here: #7207

Alternatives / Workarounds

The only alternative I am aware of is to use client side JavaScript and XHR to trigger the password reset flow by posting to /parse/requestPasswordReset endpoint, handling the response, and changing the HTML DOM appropriately to indicate that instructions were sent to email address.

[mtrezza]

Thanks for suggesting.

There are some parts I want to get clarified, it may just be the wording, but to make sure we approach this the right way:

The button click invokes simple HTTP form POST request
(...)
HTML email uses a form and button that does POST /request_password_reset that requires username.

A link in an email cannot practically invoke a POST request. I say practically because, while it is technically possible to add JS or a form to a HTML email, it will likely be blocked by every major email provider and email client. In addition, such an email has a higher SPAM score and is likely to harm your email domain reputation. In addition, consider users whose email client may fall back to plain-text.

The functionality will then be as follows:

• HTML email uses a form and button (...)
• password reset email contains button with link (...)

The desired flow indicates a likely flaw in your approach, where you describe a user clicking on a link in an email just to receive yet another email with a link to click on.

This seems like a XY problem where you go from an approach to looking for possible implementations, instead of going from a problem to looking for possible approaches. I suggest to zoom out and try to describe the scenic context in which you want a user to reset their password.

[mman]

I am actually using the afterLogin hook to inform the user about new login to their account, with a wording like "If you do not recognize this login, please change your password immediately by clicking the button/link below".

My initial attempt with the button/link clicked in an email actually needs to either POST submit a <form> to initiate the password reset. If that would not work or provide to be tricky with spam filters, I will replace it with a simple link to a webpage from where a user can initiate their password reset.

I want to do this as much as possible without requiring client side JavaScript to make thinks simple.

[mman]

I agree that the flow is rather complex, but it is based on what Parse Server provides right now.

It would be kind of nice and simpler when afterLogin with wording "If you do not recognize this login, please change your password immediately by clicking the button/link below" would already contain a password reset token and would redirect a user to the "choose-new-password.html" form.

But that would require generating fresh token (or reusing a valid one) for password reset with each afterLogin, which I do not think is the right approach.

How would you handle this?
Martin

[mtrezza]

Thanks for providing more details. I assume this is the flow you would prefer:

Case a):

1. A login happens.
2. User receives an email "If you do not recognize this login..." with a link.
3. User clicks the link and gets to a webpage where they can reset their password.
4. User submits the form and the password is changed.

Then there is another use case, that could be considered:

Case b):

1. User is logged in on a website using Parse.
2. User navigates to a password reset webpage.
3. User submits the form with a new password and password is changed.

The second use case may not seem to apply to yours at first sight, but it faces the same issue, that a password reset form requires a pre-generated token.

The difference between both cases is:

• case b): the user is logged in and a password change would require a PR that changes Parse Server to also accept a session token in place of a password reset token.
• case a): the user is not logged in, but you assume that they are authorized to change their password because the link in their personal email account. The problem however is that the webpage you are directing to cannot make that assumption, because anyone can open the webpage URL, change the username form input and submit the form with a new password. Therefore it needs a form of authentication. That can either be providing a pre-generated password reset token (status quo) or requiring the user to log in to send the form.

Possible approaches:

• Create a PR that solves case b) and change your flow to require the user to log in before changing the password.
• Generate a password reset token in the afterLogin hook and send an email including a link that is the same as the current password reset link; this has the disadvantage that a token is unnecessarily created in the database if the login was genuine.
• Instead of generating a password reset token, create a link that includes a hashed session token. That means no extra token needs to be generated and stored in the DB, but that possibly exposes the token (even if only as a hash), and it does not allow to set an expiration date like the current password reset token has. That would require a PR that changes Parse Server to also accept a hashed session token in place of a password reset token.

[mman]

My case is always case a) as I only use Parse Server via iOS and Android apps with their client side SDK.

Initiating password reset from an app via client side SDK is easy, but requires the afterLogin email to say something like: "If you do not recognize this login, open the app on one of your devices and do X, Y, and Z to change your password".

Which is not ideal and generates support requests where people can not find X, do not know what Y is, etc... I can improve this in the app, that is correct. But for now - sending an email with a simple link and clear flow sounds like a better approach to me.

In other words, I do not plan to develop a fully fledged client side web app handling account related things with Parse Server, yet even using Parse Server in a mobile app still at the moment provides certain valid email based use cases, like email validation, and password reset performed by showing an ownership of the email address.

I also think this is absolutely fine, since many apps and websites use these types of flow, so they are very familiar to most people nowadays.

[mtrezza]

Can you please provide a complete step-by-step (1,2,3...) example of the flow you are referring to and you want to achieve with Parse Server?

[mman]

1. User performs a login to an account via app (does not matter which, iOS, Android, web, ...)
2. New Login Detected email is triggered via parse-server afterLogin hook containing IP address, physical location, date & time, etc. describing what happened. And containing a phrase: "If this was you, please disregard this email. If you do not recognize this login, please change your password immediately by clicking the link/button below"
3. User clicks the link/button below and is taken to the browser where he can either
   variant a. enter new password and click "Change Password" button
   variant b. click the "Request Password Reset" button to initiate password reset.
4. Result
   variant a. Redirected to "your password was successfully changed" (or invalid link)
   variant b. Redirected to "instructions to reset your password were sent to your email". The email then sent contains the link that goes to 3.a

Neither variant a, nor variant b are at the moment possible to do easily without JavaScript talking client side via XHR to the REST API.

I am currently trying to implement variant b which may sound like more steps but is simpler to implement.

Variant a requires less steps but afterLogin hook sending New Login Detected email would need to already contain a valid password reset token, which I am not sure I can generate via cloud code.

Does my explanation make any sense?

The email verification flow, as well as password reset flow in parse server currently does not contain any HTML based way to start the process. Verification email is sent automatically after signup performed via REST API, and password reset email is sent automatically after performing POST to REST API endpoint /parse/requestPasswordReset.

Then the flow continues via series of 302 redirects and GET/POST requests going to /parse/apps/APP_ID/verify_email and GET/POST requests going to /parse/apps/APP_ID/request_password_reset. This is using the publicServerURL and customPages (soon to be replaced with the PagesRouter).

Recently, an endpoint was added to POST /parse/apps/APP_ID/resend_verification_email so that verification process can be initiated without going to REST API. This is at the moment used to trigger the re-send verification email when receiving an "email verification token has expired" email. Code here:

parse-server/public/email_verification_link_expired.html

Line 17 in c05102b

<form method="POST" action="{{{publicServerUrl}}}/apps/{{{appId}}}/resend_verification_email">

I am proposing the same, to initiate password reset with a similar form as here, but using the request_password_reset endpoint:

parse-server/public/email_verification_link_expired.html

Line 17 in c05102b

<form method="POST" action="{{{publicServerUrl}}}/apps/{{{appId}}}/resend_verification_email">

[mtrezza]

Step 3a):

• The website would have to verify that the visitor has the right to change the password. 3 ways to do that (as mentioned above):
  • Require the user to log in
  • Include the pre-generated password reset token in the email link for the disadvantage that a token would be generated for every email sent
  • Include hashed session token for the risk of exposing the token and not having a token expiration feature; do we create a session in case there isn't one?

Step 3b):

• I'm not sure at this point whether the password reset email should be requested with a GET or POST request. I think it should be a POST request because it seems to not be idempotent. If you want this to be a GET request and ignore RFC 2616, you can simply add a custom endpoint for a GET request that triggers a POST request. I'm not sure this would be an acceptable PR though.

Generally, we want to follow best practice that provides a flow that is familiar for users. I looked into Instagram as an example and found:

• The email provides a link to a password reset page.
• The reset link contains a token, seemingly like the password reset token we already have: https://instagram.com/accounts/password/reset/confirm/?uidb36=[id]&token=[token]:password_reset_email&s=login_notification_email
• The token has an expiration date, after which the user is shown an "invalid link" page, like we already do.

That would conclude we should go with the current concept of pre-generating a token. Maybe a disadvantage we have here is that we do not use a TTL index to delete unused tokens, so they stay in the DB unless invalidated.

Now, to address the use case you described, I suggest to create a password reset token in the after afterLogin trigger. The solution could be to create a PR that adds a method like const link = Parse.User.generatePasswordResetLink(user, { useMasterKey: true }); that returns a URL, which also generates a password reset token. That link can then be used in a custom email template. Such a PR would not touch the PagesRouter (or PublicAPIRouter) but merely create an interface to the UserController.

@mman Would that address your use case?

[mman]

Thanks @mtrezza for the detailed proposal.

We are on the same page here.

My initial idea, and PR implementation goes with 3b) and POST. It does work, it does not break RFC 2616, uses the same method like /resend_verification_email, and was super simple to implement. And in addition to that, it offers a simple endpoint to reset passwords for the user. So when somebody asks me how do I change my password, I can direct them to a simple web form to do that without requiring full fledged account management and web app (note: we do not have a web app behind parse, only iOS and Android apps).

The instagram like solution where password reset token is generated in afterLogin sounds good to me as well, but touches areas unfamiliar to me.

I see only one drawback there:

1. When first login happens, a password reset token would be generated valid for several hours.
2. When another login happens immediately after that, a new password reset token will be generated and will invalidate the one generated in step 1, which IMHO should not happen.

The proper solution to this problem should probably be to just extend password reset validity period in case where a valid password reset token exists for a user. And this will require some more changes.

Minus of the instagram like solution will be that there is no simple endpoint to initiate password reset from the web. That will still require manual coding outside of parse-server.

What do you think?

I will investigate instagram like solution during today, but I'm still in favor of including the step 3b) solution as outlined in the PR #7207.

[mtrezza]

it does not break RFC 2616

How did you conclude that?

Another other issue with 3b) is that it basically circumvents the security mechanism of the password reset token and makes it useless, because it will only be generated as a by-product. If we allow an endpoint as suggested in 3b), we are short circuiting the token mechanism, which would be the same as removing the feature.

When another login happens immediately after that, a new password reset token will be generated and will invalidate the one generated

Tokens can be reused as long as they are valid.

[mman]

it does not break RFC 2616

How did you conclude that?

I meant that to point out that I went with POST instead of GET because POST that triggers password reset flow is not idempotent. Much like /resend_verification_email.

When another login happens immediately after that, a new password reset token will be generated and will invalidate the one generated

Tokens can be reused as long as they are valid.

Oh cool, thanks for the link. I did not catch this PR, let me take a look and draft something along this alternative solution.

[mman]

Now, to address the use case you described, I suggest to create a password reset token in the after afterLogin trigger. The solution could be to create a PR that adds a method like const link = Parse.User.generatePasswordResetLink(user, { useMasterKey: true }); that returns a URL, which also generates a password reset token. That link can then be used in a custom email template.

@mtrezza Just to clarify, adding a method to Parse.User would require modification of Parse JS SDK (https://github.com/parse-community/Parse-SDK-JS/blob/master/src/ParseUser.js) which is also available client side in the browser.

My opinion is that better fit would be adding a method to the UserController.js (https://github.com/parse-community/parse-server/blob/master/src/Controllers/UserController.js) where the token generation and link building happens now.

Is my understanding correct?
Martin

[mtrezza]

To summarize, I think we can conclude the following:

• I'm pretty sure that using a GET endpoint to create a password reset token would violate RFC 2616, therefore your previous suggestion may work for your project, but it is not a PR Parse Server should accept.
• Generating a password reset token on-the-fly as you suggest is not best practice (given the Instagram example) nor does it make sense, because it short-circuits the password reset token; implementing this would be the same as removing the token mechanism.
• The only viable solution so far seems to be adding a method to generate a password reset link incl. token in Cloud Code. This also short-circuits the token mechanism but under control of the developer, not the user. The downside of this is that the token stays in the DB and is not deleted, which unnecessarily clutters the DB. If these tokens are expected to be generated at high frequency, a lot of users will have an unnecessary token. That's an already existing problem of the password reset and email verification token and could be addressed in a separate PR (e.g. via TTL index or a clean-up job that deletes expired tokens).

adding a method to Parse.User would require modification of Parse JS SDK (https://github.com/parse-community/Parse-SDK-JS/blob/master/src/ParseUser.js) which is also available client side in the browser.
My opinion is that better fit would be adding a method to the UserController.js (https://github.com/parse-community/parse-server/blob/master/src/Controllers/UserController.js) where the token generation and link building happens now.

It needs to be implemented in both, or how would you access a new method in the user controller?