Set up your test environment

Create a test environment to validate your Identity Engine upgrade before upgrading production. Use a Preview org, free trial, or automation tools.

Before upgrading your Production org from Classic Engine to Identity Engine, set up a test environment where you can rehearse the upgrade safely. This lets you identify issues, validate configurations, and confirm that user flows work correctly without risk to production.

Why you need a test environment

  • Validate that your current policies, sign-in flows, MFA, and app integrations work after upgrade.
  • Identify breaking changes in custom code, embedded Sign-In Widget, or API use.
  • Test remediation steps before applying them to production.
  • Confirm that the end-user experience meets expectations.
  • Build confidence before scheduling the production upgrade.

Test environment approaches

Approach Best for Limitations
Preview org (recommended) Full dress rehearsal of the upgrade process Requires an existing Preview org or purchasing one. It must mirror the production config.
Free trial or Integrator Free Plan org App and developer testing (Sign-In Widget, SDKs, API flows) Not a true migration rehearsal. It doesn't test the upgrade process itself.
Terraform or automation-based copy Repeatable, large-scale org replication Requires Terraform expertise. Okta doesn't fully document this process.
Manual org creation Simple configurations and small orgs Time-consuming. Difficult to keep in sync with production.
Preview org (recommended)

A Preview org is the closest match to a production upgrade rehearsal. You upgrade the Preview org first, using the same self-service upgrade process, then validate the results.

  • The Preview org should match your production configuration as closely as possible.
  • You can use Bookmark Apps instead of replicating every SAML app in Preview.
  • If you don't have a Preview org, contact Okta to purchase one.

See Test plan for self-service upgrade.

Free trial or Integrator Free Plan org

Use this as a secondary sandbox for testing app code, Sign-In Widget behavior, and SDK flows against an Identity Engine environment. This is useful for developer testing, but doesn't replicate the upgrade process.

Terraform or automation-based approach
  1. Export your Production org configuration using the Okta Terraform provider.
  2. Import it into a new Classic Engine org.
  3. Apply the upgrade preparation changes.
  4. Upgrade the test org.
  5. Validate.
  6. Repeat as needed.

What to bring into your test environment

Category What to replicate Notes
Policies Global session policies, MFA enrollment policies, app sign-on policies Create at least one test user per policy path.
Sign-In Widget Custom branding, CSS, JavaScript customizations Critical if using an embedded widget
Custom domains Custom URLs, Trusted Origins, CORS settings Needed for custom sign-in page testing
Apps High-risk apps (SAML, OIDC, SCIM, embedded auth) Use Bookmark Apps for low-risk SAML apps.
Authentication code Embedded Sign-In Widget, AuthJS, server-side auth code Search Trusted Origins and System Log for /api/v1/authn, /api/v1/sessions, and /api/v1/factors.
Device Trust Okta Verify, managed certificates, IWA routing rules Delete IWA routing rules before the upgrade.
Third-party tools AWS CLI, Jamf Connect, Snowflake, or other integrations Legacy tools that use Classic auth methods may break.

Steps to set up and test

  1. Inventory your Production org

    Use the Identity Engine Upgrade Hub in the Admin Console to identify action items, customizations, and testing needs.

  2. Create test users

    Create at least one test user per policy path. Record how the following behave in Classic Engine:

    • Okta sign-on policies
    • MFA enrollment policies
    • App sign-in policies
    • Password recovery flows

    See Validation tests.

  3. Mirror high-risk configuration into your test environment

    • Global session policies
    • MFA and enrollment policies
    • App sign-in policies
    • Custom domains and branding
    • Embedded Sign-In Widget apps
    • Device Trust configuration
    • SCIM apps
    • Apps using Okta APIs or SDKs

  4. Find the custom or embedded authentication code

    Search Trusted Origins/CORS and System Log for:

    • /api/v1/authn
    • /api/v1/sessions
    • /api/v1/factors

    See Custom sign-in page upgrade guidance.

  5. Upgrade the test environment

    In your Preview org, run the self-service upgrade:

    1. Complete all action items in the Upgrade Hub.
    2. Follow remediation guides.
    3. Schedule the upgrade.
    4. Test the upgraded org.

    Most upgrades take only a few minutes.

    See the Self-service upgrade process.

  6. Run your tests after upgrade

    • Global session policy behavior
    • Authenticator enrollment
    • App sign-in policies
    • Password recovery
    • Device Trust and Okta FastPass
    • Self-Service Registration and Profile Enrollment
    • SDKs and third-party tools
    • End-user sign-in experience

    See Test your upgrade.

  7. Test app code in an Identity Engine sandbox

    This step is especially important for embedded Sign-In Widget and SDK use cases. Embedded deployments need the Interaction Code flow in Identity Engine. Sign-In Widget v7+ enables Identity Engine by default.

    See Upgrade the Okta Sign-In Widget to Identity Engine.

Repeatable testing practices

  • Document every configuration change you make in the test environment.
  • Use Terraform or scripts to automate org provisioning where possible.
  • Maintain a checklist of test scenarios that you run before and after upgrade.
  • Keep test users and policy paths consistent across test runs.
  • Store results so you can compare across iterations.

High-risk areas to test

Focus on areas where Identity Engine changes authentication behavior:

Area Why it matters
Sign-In Widget Identity Engine changes the Sign-In Widget configuration and removes some Classic options.
Custom domain / custom login page Classic custom sign-in pages may not work after upgrade.
Embedded auth / AuthJS / /authn API The Classic Engine /authn API doesn't work with Identity Engine.
Device Trust Identity Engine uses Okta Verify and managed certificates. Delete IWA routing rules.
Third-party tools (AWS CLI, Jamf Connect) Older tools using Classic Engine auth methods may break.
End-user sign-in flow Identity Engine may introduce identifier-first flows and different recovery behavior.

After the upgrade

After the production upgrade, validate specific features and avoid unrelated setting changes for at least one week. See Post-upgrade checklist.