Password Reset

Walkthrough guide on how to implement a Password Reset walkthrough using Form.io

Introduction

One common requirement for any application is a password reset workflow for its users. There are a few ways to accomplish this, but this tutorial will walk you through a method that leverages the Email Login to provide the user with an email link where they can update their user record with a new password. The steps involved in this workflow are as follows.

The user fills out a Password Reset form
The Password Reset form contains an action that sends the user an email with a special SSO link to reset their password.
Once the user clicks on this link, they are sent to a different form where they will provide their new password.
Once submitted, the user record is updated with the new password.

User Resource Self-Access

To keep things simple, the default User resource will be utilized to save and update the user records.

Set Self Access & Update Own Permission

To allow each user to update their own account, we will first need to ensure that we enable the setting on the User resource. This will grant access to the user's record within the Resource.

Navigate to the User resource, and then click on Access. Scroll down and check the Enable Self Access checkbox setting under the Self Access Permissions section.

With self-access enabled, scroll up to the Submission Data Permission and set the Update Own Permission to Authenticated. This setting will allow the user with the authenticated role to update their record.

Send Password Reset Form

The next step in this process is to create a form that will initiate the Password Reset workflow for the user.

Create Form

Create a new Form called Send Password Reset. Ensure you have an Email field with the property name set to email. Feel free to add a Content component to the form to give the User instructions and context for the form.

Access Settings

Since unauthenticated users will be submitting the form, this form will need to be configured for anonymous submissions. Click on the Access tab, and add the Anonymous role to the Create Own Submission permission.

Adding Email Action

Next, an Email action will be added to the form to send off the Reset Password email. Remove the Save Submission action since submission records on not necessary for this form. Add the Email Action from the dropdown list.

Configuring the Email Action

Configure the action to send the email to the user filling out the form. This can be accomplished by adding the following to the To: Email Address field: {{ data.email }}This will interpolate the data from the email field on the form and send the email to the user's email address.

Adding the SSO Token

The User receiving the email will need an authentication token to update their user record. We can do this by including an SSO Token inside the Email action which is detailed in the Email Login System documentation.

The SSO Token link must incorporate both the application endpoint and the Form.io Project name where user record data is stored. The SSO link should be added to the Message field of the Email action.

For this example, the FormView application @ https://pro.formview.io will be the application that will facilitate the workflow, humanresources is the project endpoint name, and passwordreset will be the Form name of the Project the user will be redirected to when the link is clicked. The Password Reset form will be created in a subsequent step.

<p>Please click on the following link to Reset your Password:</p>
<a href="https://pro.formview.io/#/humanresources/passwordreset?token=[[token(data.email=user)]]&reset=true">Click here to reset Your password</a>

If you are in a Deployed Environment, the href link will look like the following.

https://yourserver.com/yourproject/manage/view/#/form/reset?token=[[token(data.email=user)]]&reset=true

Here is how it will look in the message body.

To summarize, the user will fill out the form to fire off the Password Reset action. This action will send off the email to the address the user entered. The user will click an SSO link containing an authentication token that will redirect the user to reset their password.

Linking the Send Password Form

With the Send Password form in place, we need to ensure this form is available to the user within the authentication process of the application. As mentioned, this example is using the FormView Pro application which utilizes the default Login Form within the Form.io Project. The login form for your application may differ.

Navigate to the Login form within the Project and add an HTML component to the form. Add a href link to the content of the HTML settings that will direct the User to the Send Password form created in the previous step.

In the following example, https://pro.formview.io is the application domain, humanresources is the project name and sendpasswordreset is the form name

<b><a href="https://pro.formview.io/#/humanresources/sendpasswordreset?header=1&reset=1
">Forgot your password?</a></b>

Password Reset Form

Password Reset is the form the user will be redirected to after clicking the Email action's SSO link and will update the User's record when submitted.

Create Form

Create a new form and title it Password Reset. Since the path has already been defined within our SSO link as "passwordreset" ensure the Form's API path matches. It should already be populated and correct based on the Form title.

Custom Validation

Add a Password field called New Password, set the Required validation flag, and ensure the field property name is newPassword.

Add a second password field called Verify Password, set the Required validation flag, and add the following javascript to implement Custom Validation that will force the two password fields to match.

valid = (input === data.newPassword) ? true : 'Passwords must match';

Button Event

Modify the Submit button and change the label to Change Password. Set the Action type to Event and add changePassword to the Button Event setting field.

Access Settings

Navigate to the Access tab of the Password Reset form and add the Authenticated role to the Create Own Submission permission. This will ensure that only our authenticated users can submit the form.

Form Controller

The last thing to add is a Form Controller that will handle the User Password reset. To configure a controller, click the Form Settings within the Password Reset form. Scroll down and paste the following JavaScript within the Form Controller section and Save the Settings.

// Listen for the "changePassword" event.
instance.on('changePassword', function() {
  // Get the current form submission.
  var submission = instance.submission;
  
  // Get the current user object.
  var user = Formio.getUser();
  
  // Set the user password to the form password value.
  user.data.password = submission.data.newPassword;
  
  // Save the user
  (new Formio(Formio.getProjectUrl() + '/user/submission')).saveSubmission(user).then(function() {
    var projectName = (new Formio(Formio.getProjectUrl())).projectId;
    
    // Redirect to a thank you page.
    window.location.href = 'https://pro.formview.io/#/' + projectName + '/thankyoupage?reset=true';
  })
});

For deployed servers, this configuration will need to modified to support your environment domain:

window.location.href = 'https://yourserver.com/' + projectName + '/manage/view/#/form/thankyoupage?reset=true';

To summarize, the Form Controller triggers from the event provided by the Change Password button. The code will retrieve the user information and update the current user password with the password submitted against the Password Reset form. The user will then be redirected to a Thank You Page.

Thank you page

The last thing we will do is create a form that will serve as our Thank You page. This can be a simple form that provides context and contains a redirect link back to the Login page, like the following.

Since the Thank You Page path has already been defined within the Form Controller, ensure the form's API path is thankyoupage.

Within the Thank You Page access tab, ensure the form carries the Authenticated role for the Read Form Definition permission.

Workflow

Now that we have this configured, let's try out the Password Reset workflow

Create a User

Create a user within the User resource, by clicking on the Use tab and submitting the form.

Navigate to your application's login page. Since we are using the FormView Pro application in this example, the login page endpoint is the following:

https://pro.formview.io/#/auth/login

Send Reset Password Email

Click the Forgot Your Password? link, enter the User's email, and submit the form. Alternatively, navigate to the Send Password Reset URL https://mydomain/#/myproject/sendpasswordreset

SSO Token Email Link

Navigate to your inbox to find the Password Reset Email and click the SSO token link.

Reset Password

Input the new password for the user and click the Change Password button. This is when the Form Controller will run the code to update the password to the User's record and redirect to the Thank You Page.

Thank You Page

Click the Login Page link to redirect back to the authentication and log in the user using the updated password.

Deployed Portal Environment

The concepts and configurations detailed above can also be implemented for remote deployments of the Form.io software enabling Password Reset functionality for the Form.io user base.

Apply the instructions detailed above to the Portal Base Project
Take note of the deployed endpoint changes detailed in the SSO Token and Form Controller steps