Instructions for

On this page

Custom password recovery

Identity Engine

This guide shows you how to integrate Email Magic Links (EML) into the self-service password recovery flow of your applications using Okta's embedded solutions.


Learning outcomes

  • Understand the flows supported by password recovery
  • Learn to customize your user's password recovery experience

What you need

Sample code


Overview

Okta's embedded solutions allow you to customize your authentication use cases with full support for theming, branding, and extensive ways to control the user experience. This guide covers customizations for one particular use case, self-service password recovery, where an email authenticator is used to verify the user before they can reset their password.

Note: The Email Magic Links overview explains the difference in user experience between using one-time passcodes and magic links.

Before you begin

Before you begin you need to:

Summary of changes

To give your users this customized experience, perform the following steps:

Update your org

Confirm that you have the email authenticator set up for password recovery by performing the following steps:

  1. In the Admin Console, go to Security > Authenticators.
  2. On the Authenticators page, confirm you have the Email authenticator added to your org. If not present, add it by clicking on Add Authenticator and locating Email.
  3. Find the Password authenticator, click on its Actions link, and select Edit in the dropdown.
  4. On the Password page, scroll down to the rules section. Edit the Default Rule (or currently active rule) by clicking on its pencil icon.
  5. On the Edit Rule page, confirm that Email is checked for the Users can initiate recovery with field.
  6. If changes were made, click Update Rule.

Update the Forgot Password email template

Okta sends users an email based on the Forgot Password template when they start a password recovery. All Okta email templates are written using Velocity Templating Language (VTL) (opens new window) and use predefined variables to insert relevant values into that email. Okta defines three VTL variables specific to this template:

Variable Contains
${oneTimePassword} The one-time passcode Okta generated for the user
${request.relayState} The current SAML relaystate (opens new window) value
${resetPasswordLink} The Okta-hosted URL that continues the password recovery flow

Note: The ${oneTimePassword} and ${request.relayState} variables aren't supported in the Password Reset by Admin template. As a result, you can't use this template in the custom password recovery flow described in this guide.

By default, the magic link in the template is set to ${resetPasswordLink}. You must update it to an endpoint in your application that expects ${oneTimePassword} and ${request.relayState} as query parameters and uses them to continue the password recovery flow:

  1. In the Admin Console, go to Customizations > Emails.

  2. On the Emails page, find the Password category on the template menu.

  3. Under Password, click Forgot Password.

  4. On the Forgot Password email template page, click Edit.

  5. Under Default Email, click Edit.

  6. In the Message field, locate the magic link in the field's HTML. The link is located in the href attribute of an <a> tag with the id of reset-password-link. It looks like this:

    <a id="reset-password-link"
      href="${resetPasswordLink}"
      style="text-decoration: none;">
      <span style="padding: 9px ...;">
         Reset Password
      </span>
      </a>
    

    Replace the ${resetPasswordLink} variable with the URL for the endpoint in your application that processes the magic link. You must append the ${oneTimePassword} and ${request.relayState} variables as query parameter values. For example, if you're using one of the sample apps, the updated link is as follows:

  7. Click Save and close the dialog.

Update your Sign-In Widget integration

Now to implement the endpoint that you linked to in the revised Forgot Password email template. If you're using the Sign-In Widget, execute the following steps. If your app uses the SDK, go to Update your SDK integration.

Summary of steps

The following diagram shows the steps for a customized password recovery in an app that uses the Sign-In Widget.

Update your SDK integration

Now to implement the endpoint that you linked to in the revised Forgot Password email template. If you're using the SDK, execute the following steps. If your app uses the Sign-In Widget, go to Update your Sign-In Widget integration.

Summary of steps

The following diagram shows the steps for a customized password recovery in an app that uses the SDK.

See also