Upgrade your app to the Identity Engine SDK

Identity Engine

Upgrade your app to use Identity Engine SDK methods after you update your project to the latest Identity Engine SDK. Also, make sure you have an Identity Engine org.

Review the following sections, which detail Identity Engine SDK concepts. This guide discusses the differences between how the Classic Engine authentication SDK and APIs approach authentication compared to the Identity Engine approach. Mappings of Classic Engine authentication SDK method calls, and back-end APIs, to Identity Engine SDK methods are provided for some sample use cases.

---

Learning outcomes

• Understand why you should upgrade your app to use the Identity Engine SDK.
• Learn the differences between the Classic Engine authentication SDK and the Identity Engine SDK.
• Identify the mappings between Classic Engine authentication SDK methods and the Identity Engine SDK for your language.
• Identify the mappings between Classic Engine authentication APIs and the Identity Engine SDK for your language.

What you need

• An Identity Engine org
• The Interaction Code grant enabled
• The latest Classic Engine authentication SDK installed
• An app that uses the Classic Engine authentication SDK or back-end APIs

Sample code

• Okta Auth JavaScript SDK (opens new window)

Note: The Classic Engine Authentication SDK and the new Identity Engine SDK are combined in the latest Okta Auth JavaScript SDK.

---

Why upgrade your app to the Identity Engine SDK

The Identity Engine SDK provides your applications with greater flexibility to create and configure user access experiences. The SDK’s architecture achieves this flexibility by shifting the control of application configurations and authorization policies to the org administrator, rather than requiring the developer to make updates at the code level. The SDK’s recursive method call format is also designed for dynamic Identity Engine policies that may require more access or authorization steps for one user over another.

If your application is a server-side, customized authentication solution, migrating to the Identity Engine SDK is the ideal path to benefit from Identity Engine features and configuration flexibility.

The upgrade process is also designed to be non-disruptive and iterative over a period of time. Your Classic Engine Authentication SDK application code works with an Identity Engine configured org, and you can test and migrate use cases incrementally. See the following three examples for further information on upgrading your application code:

• Authentication (sign-in flow): Map basic sign-in code to the Identity Engine SDK
• Multifactor Authentication (Email and SMS): Map MFA code to the Identity Engine SDK
• Password Recovery: Map password recovery code to the Identity Engine SDK

Classic Engine Authentication APIs and SDK vs Identity Engine SDK

The authentication flow for the Classic Engine Authentication SDK methods and their backend API calls function similarly to the Identity Engine SDK methods. Both versions call Okta, receive a transaction object, and ultimately receive tokens after a successful authentication.

The Classic Engine authentication flow returns a transaction object that can proceed in the process. You call a method on the transaction object based on the status, for example authClient.signInWithCredentials to authenticate the user.

The Identity Engine SDK, however, uses a recursive process. You call the same method again based on the information returned in the transaction object. The Identity Engine SDK uses the nextStep property on the transaction object to provide a hint at the required information.

For the basic authentication example, the Identity Engine SDK calls authClient.idx.authenticate again with information as part of the call, the user’s email address, authenticator, and so on to complete the flow and return a success state.

Another difference between Classic Engine Authentication SDK and Identity Engine SDK methods is how you receive tokens after a successful authentication. For the Classic Engine Authentication SDK, the method setCookieAndRedirect, which is deprecated in Identity Engine, makes a call to get the tokens. In the Identity Engine SDK, after receiving a success state, the tokens are included with the transaction object. There’s no separate call to get the tokens.

For further information on the Classic Engine Authentication SDK and the Identity Engine SDK, see the following documentation at the okta-auth-js repository:

• Okta Authentication API (authn) (opens new window)
• Okta Identity Engine API (IDX) (opens new window)
• Migrating from authn to IDX (opens new window)

The following table is a high-level mapping of the typical classic API requests and Classic Engine Authentication SDK methods to Identity Engine SDK methods. There are various combinations to achieve classic authentication flows, so the mapping list isn't exhaustive.

Okta API endpoints	Classic Engine SDK methods	Identity Engine SDK methods	Description
/api/v1/authn /api/v1/sessions (opens new window)	signInWithCredentials (opens new window) session.setCookieAndRedirect (opens new window)	idx.authenticate (opens new window)	Authenticate a user with username and password credentials. See Map basic sign-in code to the Identity Engine SDK.
/api/v1/authn /api/v1/factors (opens new window)	signInWithCredentials (opens new window) transaction.factors (opens new window) transaction.verify (opens new window) session.setCookieAndRedirect (opens new window)	idx.authenticate (opens new window)	Sign in a user using multifactor authentication, verify the factor and challenge. See Map MFA code to the Identity Engine SDK.
/api/v1/authn/recovery/password /api/v1/authn/recovery/token /api/v1/authn/credentials/reset_password	forgotPassword (opens new window) transaction.verify (opens new window) transaction.resetPassword (opens new window) session.setCookieAndRedirect (opens new window)	idx.recoverPassword (opens new window)	Password recovery flow, including a factor challenge and password reset. See Map password recovery code to the Identity Engine SDK.
/api/v1/authn/cancel (opens new window)	transaction.cancel (opens new window)	idx.cancel (opens new window)	Cancels the Auth flow.
/v1/logout (opens new window)	getSignOutRedirectUrl (opens new window) revokeAccessToken (opens new window)	n/a	Sign out. See User sign out (local app).

Map a basic sign-in code to the Identity Engine SDK

The following sections highlight the Classic Engine Authentication SDK method calls and back-end Authentication APIs that require migration to the Identity Engine SDK. The Identity Engine SDK methods can perform authentication using Identity Engine's new features and workflows.

Map the Authentication SDK to the Identity Engine SDK

If your application uses the Classic Engine Authentication SDK methods to authenticate through Okta, you generally start the authentication flow with a call to the signInWithCredentials method on an OktaAuth object (for example, authClient), using the parameters of username and password. This call returns a status on the transaction object (transaction.status) that the application code must handle. If successful (transaction.status === 'SUCCESS'), you make a call to the setCookieAndRedirect method to retrieve a sessionToken.

Note: The setCookieAndRedirect method requires access to third-party cookies and is deprecated in the Identity Engine SDK.

See the following code snippet for this example:

authClient.signInWithCredentials({
  username: 'some-username',
  password: 'some-password'
})
.then(function(transaction) {
  if (transaction.status === 'SUCCESS') {
    authClient.session.setCookieAndRedirect(transaction.sessionToken); // Sets a cookie on redirect
  } else {
    throw 'We cannot handle the ' + transaction.status + ' status';
  }
})
.catch(function(err) {
  console.error(err);
});

To migrate your code to the Identity Engine SDK, the authentication flow is very similar, but you must replace the method calls to those in the new SDK and update your code to handle the different transaction object statuses that are returned.

Identity Engine SDK authentication flow

For the Identity Engine SDK, you generally start the authentication flow with a call to the idx.authenticate method on an OktaAuth object (for example, authClient), using the parameters of username and password, or no parameters at all (see Identity Engine code options). This call returns a status on the transaction object (transaction.status) that the application code must handle. If successful (transaction.status === IdxStatus.SUCCESS), your application receives access and ID tokens with the success response.

See the following code snippet for this example:

const transaction = await authClient.idx.authenticate({
  username: 'some-username',
  password: 'some-password',
});

if (transaction.status === IdxStatus.SUCCESS) {
  authClient.tokenManager.setTokens(transaction.tokens); // App receives tokens directly
}

For further details and reference material, see Migrating from authn to IDX (opens new window) in the Okta Auth JavaScript SDK.

For further details on the password authentication flow using Identity Engine and a sample application, see Basic sign-in flow with the password factor (opens new window).

Identity Engine SDK code options

The Identity Engine SDK methods provide an opportunity to mirror the code styles used in the Classic Engine Authentication SDK, which can facilitate an easier migration path. It also provides an opportunity to use a more open, flexible code style that takes advantage of the recursive nature of the SDK. These styles are respectively referenced in the Identity Engine SDK as Up-Front and On-Demand. See Approaches (opens new window) in the Identity Engine SDK.

Map Classic Engine Authentication APIs to the Identity Engine SDK

If your app uses direct APIs for an authentication flow, your code may call the following Okta APIs:

• /api/v1/authn: Begin the primary authentication, which validates the password credentials and evaluates org policies
• If successful, call the /api/v1/sessions API with a sessionToken returned from the first call to create a session

See the following sample calls and responses for this Basic Authentication flow:

Call /api/v1/authn

curl --location --request POST 'https://{yourOktaDomain}/api/v1/authn' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "username": "john.doe@example.com",
  "password": "password123",
  "options": {
    "multiOptionalFactorEnroll": false,
    "warnBeforePasswordExpired": false
  }
}'

Receive a successful response with a sessionToken

{
    "expiresAt": "2021-10-07T18:19:36.000Z",
    "status": "SUCCESS",
    "sessionToken": "20111KWCKiTgnNgeaFjw760VitvCy7y-9cYl8lvN65754GmBuo_PPE6",
    "_embedded": {
        "user": {
            "id": "00u8eyowx5GiJhqvj1d6",
            "passwordChanged": "2020-12-21T19:39:06.000Z",
            "profile": {
                "login": "john.doe@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "locale": "en_US",
                "timeZone": "America/Los_Angeles"
            }
        }
    },
    "_links": {
        "cancel": {
            "href": "https://example.okta.com/api/v1/authn/cancel",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Use the sessionToken from the response to create a session

curl --location --request POST 'https://{yourOktaDomain}/api/v1/sessions' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: SSWS 00igKrTNyNLHCw0wYSIsoDF28cN4B3KZPETBz9pqz0' \
--header 'Cookie: JSESSIONID=16DC4838820F919032FC7BF01A8FE3E8' \
--data-raw '{
  "sessionToken": "20111MzxECyRs8sqQ8WG93-ftVtXQ_uBUbOqVt7RYbNFsZBAs1mw-Vl"
}'

Receive a successful authentication response from the call

{
    "id": "102XV1tNvxsTm69-StW_BCU-Q",
    "userId": "00u8eyowx5GiJhqvj1d6",
    "login": "john.doe@example.com",
    "createdAt": "2021-10-07T18:22:07.000Z",
    "expiresAt": "2021-10-07T20:22:07.000Z",
    "status": "ACTIVE",
    "lastPasswordVerification": "2021-10-07T18:22:07.000Z",
    "lastFactorVerification": null,
    "amr": [
        "pwd"
    ],
    "idp": {
        "id": "00o2di92cuwsnS0PS1d6",
        "type": "OKTA"
    },
    "mfaActive": true,
    "_links": {
        "self": {
            "href": "https://example.okta.com/api/v1/sessions/me",
            "hints": {
                "allow": [
                    "GET",
                    "DELETE"
                ]
            }
        },
        "refresh": {
            "href": "https://example.okta.com/api/v1/sessions/me/lifecycle/refresh",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "user": {
            "name": "John Doe",
            "href": "https://example.okta.com/api/v1/users/me",
            "hints":
                "allow": [
                    "GET"
                ]
            }
        }
    }
}

If your app implements these API calls and handles the responses shown, update your code to use Identity Engine SDK methods. These methods encapsulate the authentication flow using recursive calls to Identity Engine. A successful response returns with access and ID tokens.

See Identity Engine SDK authentication flow.

Map MFA code to the Identity Engine SDK

The following sections highlight the Classic Engine Authentication SDK method calls and back-end Authentication APIs that require migration to the Identity Engine SDK. The Identity Engine SDK methods can perform multifactor authentication using Identity Engine's new features and workflows.

Map the Authentication SDK to Identity Engine SDK

If your application uses the Classic Engine Authentication SDK methods to authenticate through Okta with an org configured for MFA, you generally start the authentication flow with a call to the signInWithCredentials method on an OktaAuth object (for example, authClient), using the parameters of username and password. This call returns a status on the transaction object (transaction.status === 'MFA_REQUIRED') that the application code must handle to identify the factor and start the challenge by calling (transaction.factors). This call returns a new status on the transaction object: (transaction.status === 'MFA_CHALLENGE'), which is then handled by your code to verify the factor challenge, for example, sending an SMS code parameter back to Okta to successfully validate the user. If successful (transaction.status === 'SUCCESS'), you make a call to the setCookieAndRedirect method to retrieve a sessionToken.

Note: The setCookieAndRedirect method requires access to third-party cookies and is deprecated in the Identity Engine SDK.

See the following code snippet for a function that moves through MFA status:

  function showMfaAuthn() {
  const transaction = appState.transaction;
  // MFA_ENROLL https://github.com/okta/okta-auth-js/blob/master/docs/authn.md#mfa_enroll
  if (transaction.status === 'MFA_ENROLL') {
    return showMfaEnrollFactors();
  }
  // MFA_ENROLL_ACTIVATE https://github.com/okta/okta-auth-js/blob/master/docs/authn.md#mfa_enroll_activate
  if (transaction.status === 'MFA_ENROLL_ACTIVATE') {
    return showMfaEnrollActivate();
  }
    // MFA_REQUIRED https://github.com/okta/okta-auth-js/blob/master/docs/authn.md#mfa_required
  if (transaction.status === 'MFA_REQUIRED') {
    return showMfaRequired();
  }
  // MFA_CHALLENGE https://github.com/okta/okta-auth-js/blob/master/docs/authn.md#mfa_challenge
  if (transaction.status === 'MFA_CHALLENGE') {
    return showMfaChallenge();
  }
  throw new Error(`TODO: showMfaAuthn: handle transaction status ${appState.transaction.status}`);
}

To migrate your code to the Identity Engine SDK, the authentication flow is very similar, but you must replace the method calls to those in the new SDK and update your code to handle the different transaction object statuses that are returned.

Identity Engine SDK authentication flow for MFA

For the Identity Engine SDK, you generally start the authentication flow with a call to the idx.authenticate method on an OktaAuth object (for example, authClient), using the parameters of username and password, or no parameters at all (see Identity Engine code options). This call returns a status on the transaction object (transaction.status) of Idx.status.PENDING that the application must handle. The nextStep parameter included in the response provides details on what data the next must include. In the MFA instance, recursive calls to the same idx.authenticate method require a call with a factor type (for example, email or SMS) that initiates the challenge, and then a follow-up call to verify the challenge.

If successful (transaction.status === IdxStatus.SUCCESS), your application receives access and ID tokens with the success response.

See the following code snippet for this example:

const transaction = await authClient.idx.authenticate({
  username: 'some-username',
  password: 'some-password',
});
if (transaction.status === IdxStatus.PENDING) { } = await authClient.idx.authenticate();
// gather user inputs (this call should happen in a separated request)
const {
  status, // IdxStatus.PENDING
  nextStep: {
    inputs, // [{ name: 'authenticator', ... }]
    options // [{ name: 'email', ... }, ...]
  }
}
} = await authClient.idx.authenticate({ authenticator: 'email' });
// gather verification code from email (this call should happen in a separated request)
const {
  status, // IdxStatus.SUCCESS
  tokens
} = await authClient.idx.authenticate({ verificationCode: 'xxx' });

if (transaction.status === IdxStatus.SUCCESS) {
  authClient.tokenManager.setTokens(transaction.tokens); // App receives tokens directly
}

For further details on MFA, see idx.authenticate (opens new window) in the Okta Auth JavaScript SDK.

For further details on the password and email multifactor authentication flow using Identity Engine, see Sign-in with email and password factors and the sample application.

Map Classic Engine Authn APIs to the Identity Engine SDK

If your app uses direct APIs for a multifactor authentication flow, your code may call the following Okta APIs:

• /api/v1/authn: Begin the MFA authentication with the password credentials, which sets the transaction state to MFA_REQUIRED
• /api/authn/factors/{emailFactorId}/verify: Send the user an email with a sign-in code
• /api/authn/factors/{$emailFactorId}/verify: Call this a second time with the sign-in code from the email challenge

Note: If you call the direct /api/v1/policies API to manage or update MFA enrollment policies, you need to update these calls to use Identity Engine policies. See Authentication policy (opens new window) and User profile policy (opens new window).

See the following sample calls and responses for the MFA authentication flow using the email factor:

Call the /api/v1/authn endpoint

curl --location --request POST 'https://{yourOktaDomain}/api/v1/authn' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "username": "john.doe@example.com",
  "password": "password123",
  "options": {
    "multiOptionalFactorEnroll": false,
    "warnBeforePasswordExpired": false
  }
}'

Receive a successful response that requires MFA

{
    "stateToken": "00kYBC0MrmG2kHSqYHrSzw7Y99_u9-MOcjEf-_B9Fa",
    "expiresAt": "2021-10-12T14:38:30.000Z",
    "status": "MFA_REQUIRED",
    "_embedded": {
        "user": {
            "id": "00u1ehs07qD6MhWk85d7",
            "passwordChanged": "2021-10-08T19:36:48.000Z",
            "profile": {
                "login": "michael.john.smith27@gmail.com",
                "firstName": "Michael",
                "lastName": "Smith",
                "locale": "en",
                "timeZone": "America/Los_Angeles"
            }
        },
        "factors": [
            {
                "id": "emf1ehtcpaFA0cQg95d7",
                "factorType": "email",
                "provider": "OKTA",
                "vendorName": "OKTA",
                "profile": {
                    "email": "m...7@gmail.com"
                },
                "_links": {
                    "verify": {
                        "href": "https://example.okta.com/api/v1/authn/factors/emf1ehtcpaFA0cQg95d7/verify",
                        "hints": {
                            "allow": [
                                "POST"
                            ]
                        }
                    }
                }
            },
            {
                "id": "sms1ehtiv4lzDd0MW5d7",
                "factorType": "sms",
                "provider": "OKTA",
                "vendorName": "OKTA",
                "profile": {
                    "phoneNumber": "+1 XXX-XXX-1502"
                },
                "_links": {
                    "verify": {
                        "href": "https://example.okta.com/api/v1/authn/factors/sms1ehtiv4lzDd0MW5d7/verify",
                        "hints": {
                            "allow": [
                                "POST"
                            ]
                        }
                    }
                }
            }
        ],
        "policy": {
            "allowRememberDevice": true,
            "rememberDeviceLifetimeInMinutes": 15,
            "rememberDeviceByDefault": false,
            "factorsPolicyInfo": {}
        }
    },
    "_links": {
        "cancel": {
            "href": "https://example.okta.com/api/v1/authn/cancel",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Send email challenge (/api/v1/authn/factors/{emailFactorId}/verify)

curl --location --request POST 'https://{yourOktaDomain}/api/v1/authn/factors/emf276bb2dP3no7Da5d7/verify' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Cookie: JSESSIONID=6B93EFE5B529BB1CCC437F33996F04AB' \
--data-raw '{
  "stateToken": "00K3WvIsn4-P64LNEt5NW3yoXx-V6Kgi7H18yamJMi"
}'

Receive a response to challenge the factor

{
    "stateToken": "00kYBC0MrmG2kHSqYHrSzw7Y99_u9-MOcjEf-_B9Fa",
    "expiresAt": "2021-10-12T14:40:23.000Z",
    "status": "MFA_CHALLENGE",
    "factorResult": "CHALLENGE",
    "challengeType": "FACTOR",
    "_embedded": {
        "user": {
            "id": "00u1ehs07qD6MhWk85d7",
            "passwordChanged": "2021-10-08T19:36:48.000Z",
            "profile": {
                "login": "michael.john.smith27@gmail.com",
                "firstName": "Michael",
                "lastName": "Smith",
                "locale": "en",
                "timeZone": "America/Los_Angeles"
            }
        },
        "factor": {
            "id": "emf1ehtcpaFA0cQg95d7",
            "factorType": "email",
            "provider": "OKTA",
            "vendorName": "OKTA",
            "profile": {
                "email": "m...7@gmail.com"
            }
        },
        "policy": {
            "allowRememberDevice": true,
            "rememberDeviceLifetimeInMinutes": 15,
            "rememberDeviceByDefault": false,
            "factorsPolicyInfo": {}
        }
    },
    "_links": {
        "next": {
            "name": "verify",
            "href": "https://example.okta.com/api/v1/authn/factors/emf1ehtcpaFA0cQg95d7/verify",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "resend": [
            {
                "name": "email",
                "href": "https://example.okta.com/api/v1/authn/factors/emf1ehtcpaFA0cQg95d7/verify/resend",
                "hints": {
                    "allow": [
                        "POST"
                    ]
                }
            }
        ],
        "prev": {
            "href": "https://example.okta.com/api/v1/authn/previous",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "cancel": {
            "href": "https://example.okta.com/api/v1/authn/cancel",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Verify code from challenge email (/api/v1/authn/factors/{emailFactorId}/verify)

curl --location --request POST 'https://{yourOktaDomain}/api/v1/authn/factors/emf276bb2dP3no7Da5d7/verify' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Cookie: JSESSIONID=6B93EFE5B529BB1CCC437F33996F04AB' \
--data-raw '{
  "stateToken": "00K3WvIsn4-P64LNEt5NW3yoXx-V6Kgi7H18yamJMi",
  "passCode": "477420"
}'

Receive a success response after confirming the email code

{
    "expiresAt": "2021-10-12T14:43:04.000Z",
    "status": "SUCCESS",
    "sessionToken": "20111BkbGDWXbtv6_qe0NeDzuIYfWttZu5m4xszO4LQPqrmQfUA3pqc",
    "_embedded": {
        "user": {
            "id": "00u1ehs07qD6MhWk85d7",
            "passwordChanged": "2021-10-08T19:36:48.000Z",
            "profile": {
                "login": "john.doe@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "locale": "en",
                "timeZone": "America/Los_Angeles"
            }
        }
    },
    "_links": {
        "cancel": {
            "href": "https://example.okta.com/api/v1/authn/cancel",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

If your app uses these API calls and handles the responses shown, update your code to use Identity Engine SDK methods. These methods use the authentication flow with recursive calls to Identity Engine. A successful response includes access and ID tokens.

See Identity Engine SDK authentication flow for MFA.

Map password recovery code to the Identity Engine SDK

The following sections highlight the Classic Engine Authentication SDK method calls and back-end Authentication APIs that require migration to the Identity Engine SDK. The Identity Engine SDK methods can perform a password reset by using Identity Engine's new features and workflows.

Map the Authentication SDK password recovery methods to Identity Engine SDK

If your application uses the Classic Engine Authentication SDK methods to recover a password through Okta, you generally start the flow by calling a method (authClient.forgotPassword) and then calling verify on the returned transaction (transaction.verify) with a passcode. After this call, you check for a successful status (transaction.status), which completes the transaction. You then need to redirect back to Okta to get tokens (session.setCookieAndRedirect).

Note: The setCookieAndRedirect method requires access to third-party cookies and is deprecated in the Identity Engine SDK.

See the following code snippet for this example:

authClient.forgotPassword({
  username: 'john.doe@example.com',
  factorType: 'SMS',
})
.then(function(transaction) {
  return transaction.verify({
    passCode: '123456' // The passCode from the SMS or CALL
  });
})
.then(function(transaction) {
  if (transaction.status === 'SUCCESS') {
    authClient.session.setCookieAndRedirect(transaction.sessionToken);
  } else {
    throw 'We cannot handle the ' + transaction.status + ' status';
  }
})
.catch(function(err) {
  console.error(err);
});

Identity Engine SDK authentication flow for password recovery

For the Identity Engine SDK, you generally start the password recovery flow with a call to the idx.recoverPassword method on an OktaAuth object (for example, authClient), using the parameters of username and authenticators or no parameters at all (although these parameters are required in subsequent calls). This call returns a status on the transaction object (Idx.Status) that the application code must handle. When finally successful (IdxStatus.SUCCESS), your application receives access and ID tokens with the success response. There are other calls prior to that based on the password policy.

See the following code snippet for this example that shows the last call that includes the user's confirmed new (recovered) password:

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 });

if (transaction.status === IdxStatus.SUCCESS) {
  authClient.tokenManager.setTokens(transaction.tokens);
}

For further details and reference material, see Migrating from authn to IDX (opens new window).

For further details on the password recovery flow using Identity Engine, see User password recovery and the sample application.

Map password recovery APIs to Identity Engine

If your app uses direct APIs for a password recovery flow, your code may call the following APIs:

• /api/v1/authn/recovery/password: Initiate the password recovery process and set the transaction state to RECOVERY_CHALLENGE
• /api/v1/authn/recovery/token: Challenge the factor code
• /api/v1/authn/credentials/reset_password: Reset the password if the challenge is successful

See the following sample calls and responses for the password recovery flow using SMS as a factor:

User clicks link to recover password (/api/v1/authn/recovery/password with factorType)

curl --location --request POST 'https://{yourOktaDomain}/api/v1/authn/recovery/password' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Cookie: JSESSIONID=567D81F8C70A8F601AD0EF3A551FB53D' \
--data-raw '{
  "username": "{username}",
  "factorType": "SMS",
  "relayState": "/myapp/some/deep/link/i/want/to/return/to"
}'

The response requires an SMS code challenge

{
    "stateToken": "00hdMzIhfXCfUeRYVjmiP9O6_l0A-ScgdiyucNw3e_",
    "expiresAt": "2021-10-12T19:05:34.000Z",
    "status": "RECOVERY_CHALLENGE",
    "relayState": "/myapp/some/deep/link/i/want/to/return/to",
    "factorType": "SMS",
    "recoveryType": "PASSWORD",
    "_links": {
        "next": {
            "name": "verify",
            "href": "https://example.okta.com/api/v1/authn/recovery/factors/SMS/verify",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "cancel": {
            "href": "https://example.okta.com/api/v1/authn/cancel",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "resend": {
            "name": "SMS",
            "href": "https://example.okta.com/api/v1/authn/recovery/factors/SMS/resend",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

The user verifies the SMS challenge (/api/v1/authn/recovery/factors/sms/verify)

curl --location --request POST 'https://{yourOktaDomain}/api/v1/authn/recovery/factors/sms/verify' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Cookie: JSESSIONID=567D81F8C70A8F601AD0EF3A551FB53D' \
--data-raw '{
  "stateToken": "00hdMzIhfXCfUeRYVjmiP9O6_l0A-ScgdiyucNw3e_",
  "passCode": "926187"
}'

If successful, the transaction status moves to Password_Reset

{
    "stateToken": "00hdMzIhfXCfUeRYVjmiP9O6_l0A-ScgdiyucNw3e_",
    "expiresAt": "2021-10-12T18:11:27.000Z",
    "status": "PASSWORD_RESET",
    "relayState": "/myapp/some/deep/link/i/want/to/return/to",
    "recoveryType": "PASSWORD",
    "_embedded": {
        "user": {
            "id": "00u276bb2cmQuiFhU5d7",
            "passwordChanged": "2021-10-12T17:12:45.000Z",
            "profile": {
                "login": "john.doe@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "locale": "en",
                "timeZone": "America/Los_Angeles"
            }
        },
        "policy": {
            "complexity": {
                "minLength": 8,
                "minLowerCase": 1,
                "minUpperCase": 1,
                "minNumber": 1,
                "minSymbol": 0,
                "excludeUsername": true
            },
            "age": {
                "minAgeMinutes": 0,
                "historyCount": 4
            }
        }
    },
    "_links": {
        "next": {
            "name": "resetPassword",
            "href": "https://example.okta.com/api/v1/authn/credentials/reset_password",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "cancel": {
            "href": "https://example.okta.com/api/v1/authn/cancel",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Prompt the user to reset the password (/api/v1/authn/credentials/reset_password)

curl --location --request POST 'https://{yourOktaDomain}/api/v1/authn/credentials/reset_password' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Cookie: JSESSIONID=567D81F8C70A8F601AD0EF3A551FB53D' \
--data-raw '{
  "stateToken": "00hdMzIhfXCfUeRYVjmiP9O6_l0A-ScgdiyucNw3e_",
  "newPassword": "new_password!"
}'

The app receives the response and the user can sign in

{
    "stateToken": "00K3WvIsn4-P64LNEt5NW3yoXx-V6Kgi7H18yamJMi",
    "expiresAt": "2021-10-12T18:13:17.000Z",
    "status": "MFA_REQUIRED",
    "relayState": "/myapp/some/deep/link/i/want/to/return/to?type_hint=PASSWORD_RECOVERY&session_hint=AUTHENTICATED&login_hint=john.doe%40example.com",
    "_embedded": {
        "user": {
            "id": "00u276bb2cmQuiFhU5d7",
            "passwordChanged": "2021-10-12T18:08:17.000Z",
            "profile": {
                "login": "john.doe@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "locale": "en",
                "timeZone": "America/Los_Angeles"
            }
        },
        "factors": [
            {
                "id": "sms276bje00iCLqHY5d7",
                "factorType": "sms",
                "provider": "OKTA",
                "vendorName": "OKTA",
                "profile": {
                    "phoneNumber": "+1 XXX-XXX-1502"
                },
                "_links": {
                    "verify": {
                        "href": "https://example.okta.com/api/v1/authn/factors/sms276bje00iCLqHY5d7/verify",
                        "hints": {
                            "allow": [
                                "POST"
                            ]
                        }
                    }
                }
            },
            {
                "id": "emf276bb2dP3no7Da5d7",
                "factorType": "email",
                "provider": "OKTA",
                "vendorName": "OKTA",
                "profile": {
                    "email": "m...7@gmail.com"
                },
                "_links": {
                    "verify": {
                        "href": "https://example.okta.com/api/v1/authn/factors/emf276bb2dP3no7Da5d7/verify",
                        "hints": {
                            "allow": [
                                "POST"
                            ]
                        }
                    }
                }
            }
        ],
        "policy": {
            "allowRememberDevice": true,
            "rememberDeviceLifetimeInMinutes": 15,
            "rememberDeviceByDefault": false,
            "factorsPolicyInfo": {}
        }
    },
    "_links": {
        "cancel": {
            "href": "https://example.okta.com/api/v1/authn/cancel",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

If your code implements these API calls and handles the responses shown, you need to update your app to use Identity Engine SDK methods.

These methods encapsulate the password recovery flow using recursive calls to Identity Engine. A success response returns with access and ID tokens.

See Identity Engine SDK authentication flow for password recovery.

Map basic sign-out code to the Identity Engine SDK

The Identity Engine SDK included with the Classic Engine Authentication SDK doesn't have a new method for the basic sign-out flow. See the previous sign-out method (signOut (opens new window)) for implementation details for both Classic Engine and Identity Engine.

See also User sign-out (local app).