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

Java 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: The user selects the forgot password link

The password recovery flow begins when the user clicks the Forgot your password? link on your app's sign-in page.

You need to create a form to capture the user's email for password recovery, similar to the following wireframe.

2: The user enters their email

Begin the authentication process by calling the Java SDK's IDXAuthenticationWrapper.begin() method and getting a new ProceedContext (opens new window) object.

AuthenticationResponse beginResponse = idxAuthenticationWrapper.begin();
ProceedContext proceedContext = beginResponse.getProceedContext();

After the user submits their email, call the IDXAuthenticationWrapper.recoverPassword() method with the user's email as the username argument.

 AuthenticationResponse authenticationResponse =
    idxAuthenticationWrapper.recoverPassword(username, proceedContext);

If the email is for a valid and active user in the Okta directory, the IDXAuthenticationWrapper.recoverPassword() method returns an AuthenticationResponse (opens new window) object with the following properties:

• AuthenticationStatus=AWAITING_AUTHENTICATOR_SELECTION — This status indicates that there are required authenticators that need to be verified.

• Authenticators — List of authenticators (opens new window) to be verified (in this case, there is only the email authenticator).
  Authenticators are the factor credentials that are owned or controlled by the user. These are verified during authentication.

After receiving the AWAITING_AUTHENTICATOR_SELECTION status and the list of authenticators to be verified, provide the user with a form to select the authenticator to verify. In other words, provide the user with a list of recovery factors to use. In this use case, email is the only recovery factor available.

3: The user selects the email authenticator

The user selects Email as the authenticator to recover their password. Pass the selected authenticator to the IDXAuthenticationWrapper.selectAuthenticator() method:

authenticationResponse = idxAuthenticationWrapper.selectAuthenticator(proceedContext, authenticator);

This Java SDK method sends the email authenticator selection to Okta. Okta sends a code to the user's email and the Java SDK returns AuthenticationStatus=AWAITING_AUTHENTICATOR_VERIFICATION to your client app. This status indicates that the authentication flow is waiting for an authenticator verification, in this case, an email verification code. You need to build a form to capture the code from the user.

4: The user submits the email verification code

The user receives the verification code in their email and submits it through the Verify Code form. Use VerifyAuthenticationOptions (opens new window) to capture the code and send it to the IDXAuthenticationWrapper.verifyAuthenticator() method:

VerifyAuthenticatorOptions verifyAuthenticatorOptions = new VerifyAuthenticatorOptions(code);
AuthenticationResponse authenticationResponse =
   idxAuthenticationWrapper.verifyAuthenticator(proceedContext, verifyAuthenticatorOptions);

If the request to verify the code is successful, the Java SDK returns an AuthenticationResponse object with the AuthenticationStatus=AWAITING_PASSWORD_RESET property. This status indicates that the recovery flow is waiting for an updated password for the user. You need to build a form for the user to enter their new password.

5: The user enters the new password

After the user enters their new password, call the IDXAuthenticationWrapper.verifyAuthenticator() method with the user's new password value.

VerifyAuthenticatorOptions verifyAuthenticatorOptions = new VerifyAuthenticatorOptions(newPassword);
AuthenticationResponse authenticationResponse = idxAuthenticationWrapper.verifyAuthenticator(proceedContext, verifyAuthenticatorOptions);

If the request to update the password is successful, the SDK returns an AuthenticationResponse object with AuthenticationStatus=SUCCESS and the user is successfully signed in with an updated password. Use the AuthenticationResponse.getTokenResponse() method to retrieve the required tokens (access, refresh, ID) for authenticated user activity.