On this page

    Identity Engine upgrade overview

    Identity Engine

    To apply the power of Okta Identity Engine and to easily adopt new features, update your apps from Okta Classic Engine to Identity Engine. Upgrading to Identity Engine allows you to implement many new capabilities in Okta access management products.

    Upgrading also provides more flexibility to manage your user authentication. This document provides an overview of the upgrade process for customer identity & developer use cases.

    Note: If your app integration with Okta is standards-based redirection (SAML/OIDC) to the default Okta domain, then no development changes are needed during your upgrade.

    The upgrade is a multi-phase journey. The first phase is the org upgrade itself, covered on this page. The second phase is modernizing your authentication implementation to get the most out of your Identity Engine investment.

    Plan your upgrade

    IAM administrators can generate a list of action items. These action items are acknowledgments or configurations that you must complete before you can schedule your upgrade to Identity Engine.

    View action items for your org in the Identity Engine Upgrade Hub in the Admin Console or click Upgrade to Okta Identity Engine on your Admin Dashboard. The Identity Engine Upgrade Hub lists the items that you need to address. It also identifies any customizations and testing that you need to do before your upgrade.

    As the developer, identify the integrations that have been applied to the following use cases. Make sure that you test the end-to-end flow before and after the upgrade.

    • Account creation & activation (including self-service registration)
    • User authentication and user sign-in flows
    • Password recovery
    • Session management

    Caution: Custom integrations using the Sessions API use v1/sessions/{sessionid} for back-channel session management.

    Org upgrade process

    Access the Identity Engine Upgrade Hub in the Admin Console and review any outstanding tasks. If there are any remediation tasks required, those remediation guides appear in the Identity Engine Upgrade Hub. If there are no remediations required, then your upgrade is easier.

    For detailed org upgrade instructions, see the Self-service upgrade process (opens new window).

    Consider the following:

    • After upgrading to Identity Engine, your auth experience may continue to mimic Classic Engine. However, your admin experience changes and all Okta objects from Classic Engine are now compatible with Identity Engine.
    • After you upgrade, the existing Okta-hosted Sign-In Widget works as-is.

    The rest of the upgrade process is defined in the next section. The steps that you take are related to your deployment model. Okta has carefully considered how you can break up the upgrade steps to ensure that you maintain the best user experience across your apps.

    Okta doesn't recommend doing this upgrade all at once, but rather in sections with breaks for testing. This process is non-disruptive and iterative over time. Make the upgrade steps part of your normal product development process.

    Post-org upgrade steps

    After you complete the prerequisites, your data migration is finished. You then have access to your Identity Engine org.

    The following content outlines the next steps that you may take as you upgrade your apps.

    For a more detailed look at the upgrade steps, see the Plan embedded auth application upgrades guide. This guide also contains useful troubleshooting information, including common issues and errors you may encounter during your upgrade and likely causes.

    1. Test your new environment to make sure that your experience and functionality are preserved.

    2. What’s your Deployment Model?

      Are you redirecting to the Okta-hosted Sign-In Widget?

      Note: See Deployment Model - Customized Okta Hosted SIW (opens new window) if you have a custom domain and are redirecting to the Okta-hosted Sign-In Widget.

      Are you embedding the Okta Sign-In Widget? (Gen2 only - the Gen3 Sign-In Widget is delivered as the Okta-hosted sign-in experience and isn't supported for self-hosted embedding.)

      Are you embedding your authentication with an Okta SDK?

    3. Test all of your user experiences.

      • Authentication: Make sure that your users can sign in and sign out for the workflows that you support.

      • Self-service & admin-initiated password recovery: Make sure that users can recover their factors with no impact to the user experience.

      • New account activation: Make sure that the account onboarding experience works as expected end-to-end to ensure that users have a smooth start.

      • Self-service registration: Make sure that users can sign up (including Factor enrollment if you support that) and that there are no interruptions during that process.

      • Session management: If you’re using the Sessions API, some methods for the Sessions API aren't supported in Identity Engine (opens new window).

    After the upgrade: modernize your authentication flows

    Completing the upgrade is the first phase. Your app may still be using Classic Engine authentication patterns, such as the Classic Engine Authn API, Factors API, Sessions API, or an older embedded Sign-In Widget. These patterns continue to work, but don't unlock the capabilities of Identity Engine.

    To fully take advantage of Identity Engine, replace Classic Engine authentication patterns with Identity Engine-supported flows:

    If your app is staying on its current deployment model and the org upgrade alone is sufficient, you can stop here. Most teams benefit from continuing into modernization. This unlocks Identity Engine capabilities such as flexible authenticator policies, passwordless sign-in flows, and AI agent authentication.

    More Resources

    Edit This Page On GitHub