Prepare your customizations for upgrade

Evaluate all customizations before you attempt a self-service upgrade. Custom sign-in pages that you configure in Classic Engine may not work after you upgrade to Identity Engine.

The OIE Upgrade Hub displays an acknowledgment item if it detects customizations in your sign-in experience. However, this doesn't mean that the customizations are problematic (for example, a modified UI string is a customization). If you see a customization acknowledgment item, locate it in your Okta org, and then follow the preparation steps.

Before you begin

Determine which deployment model your org uses to implement the Okta authentication experience.

Redirection: the user is redirected from an app to the Okta-hosted Sign-In Widget for authentication. When authentication is complete, they're redirected back to the app. Preparation is straightforward for redirection models.

Embedded: the user never leaves the app. Instead, APIs broker the authentication flow with a customer-hosted Sign-In Widget or with server-side code. If your org hosts the Sign-In Widget, preparing for upgrade is relatively straightforward. If you use APIs or SDKs, the preparation is more involved.

Orgs with multiple brands may use different deployment models for each one. Refer to the following scenarios to learn how to prepare each model.

Okta-hosted Sign-In Widget (default)

If your org's sign-in URL includes okta.com or oktapreview.com, you're using the Okta-hosted Sign-In Widget. This is the default configuration, and you don't have any customizations. No changes are required.

Okta-hosted Sign-In Widget with custom domain

Orgs with custom domains use the Okta-hosted Sign-In Widget but don't have okta.com or oktapreview.com in the sign-in URL. To locate and test customizations in your Sign-In Widget, complete the following steps.

In the Admin Console, go to CustomizationsBrands.
Select a brand that has a custom domain, and then open its Pages tab.
In the Sign-in page panel, click Configure.
In the Code editor, look for deprecated JavaScript methods. If you find any, make the changes recommended in the guide.
Look for custom CSS scripts or modified language. If you find any, you can test it by copying the code and pasting it in the code editor of an Identity Engine org.

After resolving your issues, you can upgrade the Sign-In Widget version and proceed with testing.

Upgrade the Sign-In Widget.
Test the sign-in flow in an app and verify that the updated Sign-In Widget works as intended.

Customer-hosted Sign-In Widget

The OIE Upgrade Hub displays an acknowledgment item if it detects an embedded Sign-In Widget. Complete the following steps to find out where the Sign-In Widget is embedded.

In the Admin Console, go to SecurityAPI.
Open the Trusted Origins tab.
Filter the list type by CORS.
Inspect each URL that is registered for CORS. CORS is a requirement for client-side authentication flows (like the Sign-In Widget or JavaScript AuthJS SDK), so any URL that appears is a possible implementation.

After you identify where the Sign-In Widget is embedded, you can upgrade its version and proceed with testing.

Upgrade the Sign-In Widget.
Test the sign-in flow in an app and verify that the updated Sign-In Widget works as intended.
Style your sign-in page and update i18n properties.
Review Deployment Model - Embedded Okta Sign-In Widget.

Customer-hosted SDK or custom sign-in page with server-side code

Okta recommends switching to one of the other deployment models before you upgrade. Identity Engine offers advanced Branding, Inline hooks, and Event hooks that reduce the need for hosted SDK or server-side code.

This is the most complex scenario. The OIE Upgrade Hub doesn't always display an acknowledgment item for embedded or server-side implementations (it's currently limited to session API usage). Work with your developers to ensure that all teams that handle custom authentication or recovery flows can test their code before the upgrade. These steps can help you identify where the code exists.

In the Admin Console, go to ReportsSystem Log.
In the Search field, enter this query:
client.userAgent.rawUserAgent pr and (debugContext.debugData.requestUri sw "/api/v1/authn" or debugContext.debugData.requestUri sw "/api/v1/sessions" or debugContext.debugData.requestUri sw "/api/v1/factors")
Download the results to CSV.
Search the CSV for any raw.UserAgent value that isn't a common browser.
Search System Logs for trusted application API tokens (System.Transaction.Detail.RequestApiToken).

After you identify where the Sign-In Widget is embedded, work with your developers to prepare for the upgrade: