Upgrade your application to the Identity Engine SDK

Identity Engine

After your project is updated to the latest Okta Identity Engine SDK, and you have an enabled Identity Engine org, you can begin the incremental process of upgrading your application to use the Identity Engine SDK methods.

Review the following sections to understand the concepts behind the Identity Engine SDK, and the differences between the Okta Classic Engine Authentication SDK and APIs and the Identity Engine approach to authentication. The mappings of Classic Engine Authentication SDK method calls, as well as backend APIs, to the Identity Engine SDK methods are provided for some sample use cases.

---

Learning outcomes

• Understand why you should upgrade your application 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 enabled Okta org
• The Interaction Code grant enabled
• The latest Classic Engine Authentication SDK installed
• An application that uses the Classic Engine Authentication SDK or backend 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 application 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

At a high level, the classic authentication flow for the Classic Engine Authentication SDK methods and their backend API calls function similarly to the new 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 has the ability to 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, and 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. Since there are a variety of combinations to achieve classic authentication flows, 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	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 basic sign-in code to the Identity Engine SDK

The following sections highlight the Classic Engine Authentication SDK method calls and backend Authentication APIs that require migration to the Identity Engine SDK, which 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 application uses direct APIs for an authentication flow, your application code may call the following Okta APIs:

• /api/v1/authn to 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 new session

See the following sample calls and responses for this basic authentication flow:

1. 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
  }
}'

2. 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"
                ]
            }
        }
    }
}

3. Use sessionToken from the response to call api/v1/sessions and 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"
}'

4. 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 application code implements these API calls and handles the responses shown, you need to update your code to use Identity Engine SDK methods. These methods encapsulate the authentication flow using recursive calls to Identity Engine, and 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 backend Authentication APIs that require migration to the Identity Engine SDK, which 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 Authentication APIs to the Identity Engine SDK

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

• /api/v1/authn to begin the MFA authentication, with the password credentials, which sets the transaction state to MFA_REQUIRED
• /api/authn/factors/${emailFactorId}/verify to send the user an email with a sign-in code
• /api/authn/factors/${$emailFactorId}/verify again 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 and Profile enrollment policy.

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

1. 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
  }
}'

2. Receive a successful response requiring 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"
                ]
            }
        }
    }
}

3. 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"
}'

4. 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"
                ]
            }
        }
    }
}

5. Verify the code from the 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"
}'

6. Receive a successful 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 application code implements these API calls and handles the responses shown, you need to update your code to use Identity Engine SDK methods. These methods encapsulate the authentication flow using recursive calls to Identity Engine, and a successful response returns with 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 backend Authentication APIs that require migration to the Identity Engine SDK, which can perform a password reset 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 application uses direct APIs for a password recovery flow, your application code may call the following APIs:

• /api/v1/authn/recovery/password to initiate the password recovery process and set the transaction state to RECOVERY_CHALLENGE
• /api/v1/authn/recovery/token to challenge the factor code
• /api/v1/authn/credentials/reset_password to 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:

1. 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"
}'

2. The response requires a challenge of the SMS code

{
    "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"
                ]
            }
        }
    }
}

3. 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"
}'

4. 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"
                ]
            }
        }
    }
}

5. Prompt user to reset 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!"
}’

6. The application receives a response that the password changed and the user is able to 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 application code implements these API calls and handles the responses shown, you need to update your code to use Identity Engine SDK methods. These methods encapsulate the password recovery flow using recursive calls to Identity Engine, and a successful 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).