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 apps using the Okta-embedded solutions.

---

Learning outcomes

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

What you need

• An Okta org configured for a password-only use case.

• An app that uses the embedded Sign-In Widget or SDK

Sample code

• Embedded Javascript SDK sample application (opens new window)

• Embedded Javascript widget sample application (opens new window)

---

Overview

The Okta-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:

1. Create and configure your Okta org as described in Set up your Okta org for a password factor only use case.
2. Set up the SDK and Sign-In Widget
3. Build an app with the embedded Sign-In Widget or SDK.
   • For apps using the embedded Sign-In Widget, implement Basic sign-in flow.
   • For apps using the SDK, implement User Password Recovery.

To test the flows without creating an app yourself, use the sample apps. These provide support for password recovery and email customizations.

Summary of changes

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

• Update your org to support the email authenticator with password recovery
• Update the Forgot Password email template to point to your app
• Depending on your embedded integration solution either:
  • Update your Sign-In Widget based app
  • Update your SDK-based app

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 Add Authenticator and locating Email.
3. Find the Password authenticator, click its Actions link, and then select Edit from the dropdown list.
4. On the Password page, scroll down to the rules section. Edit the Default Rule (or currently active rule) by clicking 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}. Update it to an endpoint in your app 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 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 app that processes the magic link. 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:

   <a id="reset-password-link"
      href="http://localhost:8080/login/callback?otp={oneTimePassword}&state={request.relayState}"
      style="text-decoration: none;">
      <span style="padding: 9px ...;">
         Reset Password
      </span>
   </a>
   

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.

Initiate password recovery

Initiate the password recovery flow and choose email as the authenticator. After the user submits the email as an authenticator, Okta sends an email to their email address. These initial steps are described in detail in the User password recovery guide.

Before sending the email, Okta builds the message based on the Forgot Password template. The otp and request.relayState variables are translated into actual values. For example,http://localhost:8080/login/callback?otp={oneTimePassword}&state={request.relayState} becomes http://localhost:8080/login/callback?otp=726009&state=1b34371af02dd31d2bc4c48a3607cd32.

Click the email magic link

The next step is to open the Okta email and click its reset password link.

Add a route to accept the link's URL in your app. Include logic to parse the otp and state parameters out of the URL string.

router.get('/login/callback', async (req, res, next) => {
  const parsedUrl = new URL(req.protocol + '://' + req.get('host') + req.originalUrl);
  const { search, href } = parsedUrl;
  const { state, otp } = req.query;
  const authClient = getAuthClient(req);
  ...

Check the URL

Check to see if the otp and state parameters exist in the query parameter by calling OktaAuth.idx.isEmailVerifyCallback() and passing in the query parameter string. For example, the query string can look like ?otp=726009&state=1b34371af02dd31d2bc4c48a3607cd32.

if (authClient.idx.isEmailVerifyCallback(search)) {
  ...
}

Check for the existence of an in-progress password recovery

Call OktaAuth.idx.canProceed() and pass in thestate parameter to verify that there's an active in-progress password recovery for the current user.

    if (authClient.idx.canProceed({ state })) {
      res.redirect(`/login?state={state}&otp={otp}`);
      return;

Set up and render Sign-In Widget with otp and state

After you validate the state parameter, the final step is to set up the otp and state in the Sign-In Widget configurations. Set up the configurations based on the following snippet. Use the latest version (opens new window) of the Widget: 7.26.1.

    const widgetConfig = {
      issuer,
      clientId,
      redirectUri,
      state,
      scopes,
      codeChallenge,
      codeChallengeMethod,
      otp
    };
    res.render('login', {
      siwVersion: '7.26.1',
      widgetConfig: JSON.stringify(widgetConfig),
      selfHosted: !!process.env.SELF_HOSTED_WIDGET
    });

Important: In Okta Sign-In Widget version 7+, Identity Engine is enabled by default. If you’re using an earlier version than 7, you must explicitly enable Identity Engine features by setting useInteractionCodeFlow: true in the widgetConfig object in the previous code snippet. If you’re using version 7+ and you want to use Okta Classic Engine rather than Identity Engine, specify useClassicEngine: true in the widgetConfig object.

After set up, render the client site page and pass the configurations to the Sign-In Widget during initialization.

<script type="text/javascript">
  const widgetConfig = {{{widgetConfig}}};
  const signIn = new OktaSignIn({
    el: '#okta-signin-widget-container',
    ...widgetConfig
  });
  signIn.showSignInAndRedirect()
    .catch(err => {
      console.log('Error happen in showSignInAndRedirect: ', err);
    });
</script>

Display the password reset page

After the Sign-In Widget is loaded, the following reset page appears and the password recovery flow continues.

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.

1: Initiate password recovery

The first step is to initiate the password recovery flow and choose email as the authenticator. After the user submits the email as an authenticator, Okta verifies that an account exists for the user using the information that they entered in step 2 above. If the account exists, Okta then sends a recovery email that matches the Forgot Password template that was altered earlier to the associated email address.

The email's Reset Password link includes the otp and request.relayState variables sent back as query parameters to the application. For instance, the URL in the email template, http://localhost:8080/magic-link/callback?otp={oneTimePassword}&state={request.relayState}, might be rendered as http://localhost:8080/magic-link/callback?otp=726009&state=1b34371af02dd31d2bc4c48a3607cd32 in the email sent to the user.

These initial steps are described in detail in the User password recovery guide.

2: Click the email magic link

The next step is to open the Okta email and click its reset password link.

Add a route to accept the link's URL in your app. Include logic to parse the otp and state parameters out of the URL string.

router.get('/login/callback', async (req, res, next) => {
  const { protocol, originalUrl } = req;
  const parsedUrl = new URL(protocol + '://' + req.get('host') + originalUrl);
  const { search, href } = parsedUrl;
  const authClient = getAuthClient(req);
  ...

3: Check if otp and state parameters are included in URL

Check to see if otp and state exists in the query parameter by calling OktaAuth.idx.isEmailVerifyCallback() and passing in the query parameter string. An example query string: ?otp=726009&state=1b34371af02dd31d2bc4c48a3607cd32

if (authClient.idx.isEmailVerifyCallback(search)) {
  ...
}

4: Submit the otp and state parameters

If the parameters exist, submit and verify them by calling OktaAuth.idx.handleEmailVerifyCallback() and passing in the query string used in the previous step.

const transaction = await authClient.idx.handleEmailVerifyCallback(search);
handleTransaction({ req, res, next, authClient, transaction });

5: Handle next step response

If the otp and state are valid, OktaAuth.idx.handleEmailVerifyCallback() returns an IdxTransaction object indicating that the next step is for the user to reset their password. Specifically, status equals PENDING and nextStep.name is set to reset-authenticator.

{
  status: "PENDING",
  nextStep: {
    name: "reset-authenticator",
    inputs: [
      {
        name: "password",
        label: "New password",
        secret: true,
        ...
      },
    ],
    type: "password",
    authenticator: {
      type: "password",
      ...
    },
  }
}

6: Display password reset page and continue the password recovery flow

Based on the IdxTransaction response, display the password reset page and continue the password recovery flow described in the User password recovery guide.

See also

• User password recovery