Plan your upgrade rollout

Plan how to sequence your Identity Engine upgrade across orgs, roll out to user segments, and prepare for feature replacements.

Before scheduling your Production org upgrade from Classic Engine to Identity Engine, plan how to sequence the upgrade across orgs, roll out changes to user segments, and replace features that are deprecated in Identity Engine. Okta recommends a gradual, iterative approach rather than upgrading everything at once.

Org upgrade sequence

If you have more than one Okta org, plan the upgrade order.

  1. Preview org. Rehearse the upgrade, validate configuration changes, and run your test matrix.
  2. Non-production or sandbox orgs. Validate app-specific flows and integrations in a real Identity Engine environment.
  3. Production org. Apply only after Preview org and sandbox org validation passes.
  • Each org is upgraded independently using the self-service upgrade in the Identity Engine Upgrade Hub. See Self-service upgrade process.
  • Complete all Identity Engine Upgrade Hub action items in each org before scheduling. See Complete action items in the Identity Engine Upgrade Hub.
  • Wait at least one week after upgrading Preview orgs before upgrading Production orgs.
  • The upgrade takes only a few minutes per org and has no downtime.

User segment rollout

After your org is upgraded, you can migrate users to Identity Engine flows gradually rather than all at once. This is especially important for orgs with embedded Sign-In Widget or SDK-based apps.

Table 1. User segment rollout strategies
Strategy How it works Best for
Code-based routing Implement conditional logic to direct users to Classic Engine or Identity Engine flows based on a flag, group, or attribute. Embedded Sign-In Widget or SDK apps
Network load balancing Route traffic across separate app instances running Classic Engine and Identity Engine code paths. Large-scale apps with multiple servers
Incremental scaling Progressively increase the percentage of users on Identity Engine flows. Controlled risk reduction in production

To roll out the upgrade to user segments, do the following:

  1. Start with internal or test users in a small group.
  2. Validate sign-in, registration, MFA enrollment, and password recovery flows.
  3. Monitor for issues using System Log and user reports.
  4. Gradually increase the user percentage.
  5. Remove legacy Classic Engine flow code after full validation.

Features to replace before upgrading

Device Trust

Classic Engine Device Trust isn't supported in Identity Engine. Plan how to replace it before or after the upgrade. See Device Trust upgrade considerations.

Okta Mobile

Okta Mobile is deprecated and unavailable after the Identity Engine upgrade. Transition users to Okta Verify before upgrading. See Prepare Okta Mobile users for upgrade.

Integrated Windows Authentication (IWA)

Delete IWA routing rules before the Identity Engine upgrade. Plan your replacement authentication method before you upgrade.

  • Identify all IWA routing rules in your org.
  • Delete IWA routing rules before scheduling the upgrade.
  • Plan your replacement: Desktop SSO with Okta FastPass or certificate-based authentication.
  • Decommission IWA agents and servers after the upgrade and Okta FastPass migration.

See Delete Integrated Windows Authentication routing rules.

Post-upgrade authenticator changes

After the upgrade, Identity Engine uses an authenticator model that replaces Classic Engine MFA factors. Some policy changes are needed immediately, and others can wait until after the one-week validation period.

Table 2. Post-upgrade timing for authenticator changes
Timing Action Details
Immediately after upgrade Verify global session policy settings If Any factor used to meet the Authentication Policy requirements is selected but Require secondary factor is cleared, apps calling Okta APIs may expect a secondary factor that's no longer enforced.
Immediately after upgrade Validate that MFA works Confirm that email, phone, and other authenticators function as expected.
After one-week validation Add or remove authenticators Configure new Identity Engine authenticators as needed.
After one-week validation Modify the authenticator enrollment policy Update enrollment rules for the new authenticator model.
After one-week validation Enable new Identity Engine features Enable only after validation confirms stability.
Table 3. Classic Engine to Identity Engine policy mapping
Classic Engine concept Identity Engine replacement Action needed
MFA enrollment policy Authenticator enrollment policy Review and reconfigure authenticator settings.
Sign-on policy factors Authentication policy authenticator constraints Map Classic Engine factors to Identity Engine authenticators.
Factor Sequencing Authenticator possession and verification Update policy rules for the new authenticator model.

See Post-upgrade checklist.

Rollout timeline checklist

Use this checklist to confirm that your rollout plan is complete before scheduling the upgrade.

Before upgrade

  • Identify all orgs that need to be upgraded and define their order.
  • Plan your user segment rollout strategy if you're using embedded apps.
  • Identify Device Trust use and plan the replacement path.
  • Delete IWA routing rules from all orgs being upgraded.
  • Communicate Okta Mobile deprecation to affected users and deploy Okta Verify.
  • Complete all Identity Engine Upgrade Hub action items in each org.

After upgrade

  • Verify global session policy settings immediately.
  • Validate MFA and authenticator enrollment for test users.
  • Refrain from modifying other settings for at least one week.
  • After one week, update authenticator enrollment policies.
  • After one week, enable new Identity Engine features as needed.
  • Remove legacy Classic Engine flow code from embedded apps after full user migration.