User password recovery

Identity Engine

Note: In proxy model architectures, where a server-side app using the embedded SDK is used as a proxy between client apps and Okta servers, a request context for the client apps is required. The expectation is that security enforcement is based on the client request context's IP address and user agent. However, since these values are currently derived from the server app rather than the client, this enforcement isn't available. As a result, network zones or behaviors that drive their conditions based on these request context values (geolocation, IP Address, or user agent) won't work until a solution to the issue is found.

This use case describes how to integrate a password recovery flow into your app using an Okta SDK. The flow includes an email factor step that the user needs to verify before updating their password.

---

Learning outcomes

• Understand how to set up password recovery with only an email factor.
• Use the Okta SDK in your app to implement a password recovery flow.

What you need

• An app that uses the embedded Identity Engine SDK
• Okta org already configured for a multifactor use case
• Identity Engine SDK set up for your own app

Sample code

Node.js Identity Engine sample app (opens new window)

---

Configuration updates

The password recovery use case requires the password and email factors.

Before you build a password recovery flow with an email factor, ensure that your org is configured for a multifactor use case. To do that, complete the steps in Set up your Okta org for a multifactor use case.

Set email as the only factor enabled for password recovery

After you configure your Okta org for the multifactor use case, enable email as the only factor for password recovery.

1. In the Admin Console, go to Security > Authenticators.
2. From the Setup tab, select Edit from the Actions dropdown menu on the Password authenticator row.
3. On the Password page, scroll down to the Add Rule section of the Default Policy and click the edit pencil icon for the Default Rule.
4. In the Edit Rule dialog, ensure that you configure the following values for AND Users can initiate recovery with:
   • Phone (SMS / Voice call): Clear
   • Email: Selected
5. Click Update Rule if you change any values.

Summary of steps

The following diagram shows the sequence of steps for the password recovery use case.

Integration steps

1. Start the password recovery flow

Add a link that allows the user to submit their username to begin the password recovery flow. The following wireframe shows a Forgot your password? link.

2. Show the password recovery page

Next, build a password recovery page that allows the user to enter their account's username or email. Include a Next button that submits this username to the SDK when selected.

3. Submit username

When the user enters their username and clicks Next, call OktaAuth.idx.recoverPassword(), passing in the username as a parameter.

try {
  const transaction = await authClient.idx.recoverPassword({ username });
  handleTransaction({ req, res, next, authClient, transaction });
} catch (error) {
  next(error);
}

4. Display a list of available authenticators

The next step is to display a list of available authenticators using the response from OktaAuth.idx.recoverPassword(). The method returns an IdxTransaction object indicating:

• The sign-in status is in the PENDING state.
• The next step is to choose an authenticator, that is, nextStep.name = select-authenticator-authenticate.
• The email authenticator is an available option in the options array.

{
  status: "PENDING",
  nextStep: {
    name: "select-authenticator-authenticate",
    inputs: [
      {
        name: "authenticator",
        type: "string",
        options: [
          {
            label: "Email",
            value: "okta_email",
          }
        ],
      },
    ],
  },
}

Using this response, display a list of authenticators to the user. In this case we are only showing the Email authenticator.

Note: If email is not included in the list of available authenticators, check you've configured your org as described in Configuration updates.

5. Verify identity with the email authenticator

Next, the user verifies their identity with the email authenticator challenge. The email authenticator supports OTP and magic links, and you can integrate both methods into your application. Learn more about integrating the email authenticator challenge by visiting the Okta email integration guide.

6. Display password reset page

After the user verifies their identity using the email authenticator, OktaAuth.idx.proceed() returns an IdxTransaction indicating:

• The sign-in status is in the PENDING state.
• The next step is to reset the user's password, that is, nextStep.name = reset-authenticator.

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

Create a password reset page that allows the user to enter their new password.

7. Submit the new password

When the user submits their new password, check that the password and confirm password fields match, and pass it to OktaAuth.idx.recoverPassword().

router.post('/reset-password', async (req, res, next) => {
  const { password, confirmPassword } = req.body;
  if (password !== confirmPassword) {
    next(new Error('Password not match'));
    return;
  }

  const authClient = getAuthClient(req);
  const transaction = await authClient.idx.recoverPassword({ password });
  handleTransaction({ req, res, next, authClient, transaction });
});

Note: Review the complete use of idx.recoverPassword in the Okta Auth JS SDK (opens new window).

If successful, the call to OktaAuth.idx.recoverPassword() returns a status of SUCCESS and the response will include ID and access tokens. The password reset is now complete and you can redirect the user to the default home page.