Upgrade the Okta Sign-In Widget

Identity Engine

This guide explains how to upgrade the Okta Sign-In Widget. The upgrade depends on whether your deployment model is redirect authentication or embedded authentication.

---

Learning outcome

Update your Sign-In Widget based on your user deployment model.

What you need

• An Identity Engine-upgraded Okta org
• An existing app that uses the Sign-In Widget
• Latest available Sign-In Widget release (opens new window)

---

Before you begin

You only need to upgrade the Sign-In Widget before your Identity Engine upgrade if either of the following applies:

• Your Sign-In Widget version is older than 5.11.0.
• You’re using the Classic Server-Side Rendering (SSR) flow. You must upgrade to the latest version of the Sign-In Widget.

If neither condition applies, you can skip this guide and proceed with your Identity Engine upgrade.

If you do need to upgrade, the steps depend on your user authentication deployment model:

• Redirect authentication: Okta-hosted sign-in page, with or without a custom URL domain
• Embedded authentication: Self-hosted Sign-In Widget embedded directly in your app

Note: Some browsers block third-party cookies by default, which disrupts Okta functionality in certain flows. See Mitigate the impact of third-party cookie deprecation (opens new window).

Upgrade process for a redirect sign-in flow

The Sign-In Widget upgrade for a redirect sign-in flow depends on whether you configured a custom URL domain:

• Custom domain and customizations outside of simple branding styles aren't configured: the Sign-In Widget is automatically upgraded to the latest version when it's loaded from the content delivery network (CDN).

• Custom domain and other customizations are configured: Admins must update the Sign-In Widget version in the Admin Console.

To update the Sign-In Widget:

1. In the Admin Console, go to Customizations > Brands, and then select the brand you want.

2. On the Pages tab, click Configure in the Sign-in page section. Go to the Settings tab.

   • In the Sign-In Widget Version section, check that the Version is the highest version available. The Sign-In Widget is always the latest version if you're not using a custom URL domain.
   • If you're using the custom domain feature and the version isn't correct, you can pin the Sign-In Widget's version. Click Edit in the Sign-In Widget Version section, and then select the Version field.
   • If you enable multibrand customization, you can't customize the Sign-In Widget for the Okta default brand. See Branding (opens new window).
   • If you enable the third generation of the Sign-In Widget, you can pin the version. See Pin a specific third generation Sign-In Widget (opens new window).

3. Click Save to draft.

4. Go to the Page Design tab to preview the draft of your sign-in page.

5. Verify the CSS and localization changes that you made are reflected in the new version.

Note: The third generation of the Okta Sign-In Widget doesn’t guarantee the stability of CSS selectors. Instead, customization in the third generation gets better support through branding. See Style the Sign-In Widget (third generation).

Upgrade process for an embedded Sign-In Widget

Upgrade your embedded Sign-In Widget by referencing the Okta CDN in your sign-in page. Use the latest version (opens new window) of the Sign-In Widget: 7.47.1

<script src="https://global.oktacdn.com/okta-signin-widget/7.47.1/js/okta-sign-in.min.js" type="text/javascript"></script>
<link href="https://global.oktacdn.com/okta-signin-widget/7.47.1/css/okta-sign-in.min.css" type="text/css" rel="stylesheet"/>

See also Using the Okta CDN (opens new window).

In addition to version upgrade, you need to adjust your Sign-In Widget configuration for new or deprecated settings. See the next section.

Note: The third generation of the Okta Sign-In Widget doesn’t support embedded authentication. See Sign-In Widget, third generation (opens new window).

Note: If you're currently using the Sign-In Widget major version 4 or earlier, consult the Okta Sign-In Widget migration guide (opens new window).

Upgrade if you're using the Classic SSR flow

If you're using the Sign-In Widget's Classic SSR flow, you must upgrade to the latest version of the Sign-In Widget before you upgrade. After the Identity Engine upgrade, the Classic SSR flow is no longer supported for embedded authentication. You must migrate to the Interaction Code flow, which requires the latest version of the Sign-In Widget.

To prepare for post-OIE Sign-In Widget updates:

1. Upgrade to the latest Sign-In Widget version using the CDN instructions above.
2. After your Identity Engine upgrade is complete, update your Sign-In Widget configuration to use the Interaction Code flow. See Interaction Code flow.

Changes to Sign-In Widget configuration for Identity Engine

For Identity Engine, the Sign-In Widget is configured differently. You can remove some specific objects that were previously in the Sign-In Widget configuration from the JavaScript, as described in the following sections.

Interaction Code flow

Identity Engine uses the Interaction Code grant type to manage user interactions, such as registration or multifactor authentication. For embedded Sign-In Widget (self-hosted) deployments, the Interaction Code flow is the only supported authentication flow with Identity Engine.

In Okta Sign-In Widget version 7+, Identity Engine is enabled by default. If you’re using an earlier version than 7, you must explicitly enable Identity Engine features by setting useInteractionCodeFlow: true in the config object:

var config = {
  issuer: '{{authServerUri}}',
  clientId: '{{oidcAppClientId}}',
  redirectUri: '{{oidcAppRedirectUri}}',
  useInteractionCodeFlow: true
}

If you’re using version 7+ and you want to use Classic Engine rather than Identity Engine, specify useClassicEngine: true in your config object:

var config = {
  issuer: '{{authServerUri}}',
  clientId: '{{oidcAppClientId}}',
  redirectUri: '{{oidcAppRedirectUri}}',
  useClassicEngine: true
}

Registration

You no longer need the registration (opens new window) JavaScript objects in the Sign-In Widget. You can add registration into your app by configuring your Okta admin settings for profile enrollment (opens new window). This process allows users to self-register into your app.

Remove the registration object and features.registration property that are shown in the following snippet:

var signIn = new OktaSignIn({
  baseUrl: 'https://{yourOktaDomain}',
  registration: {
    preSubmit: (postData, onSuccess, onFailure) => {
        // handle preSubmit callback
        onSuccess(postData);
    },
    postSubmit: (response, onSuccess, onFailure) => {
        // handle postsubmit callback
        onSuccess(response);
    }
  },
  features: {
    // Used to enable registration feature on the Sign-In Widget
    // https://github.com/okta/okta-signin-widget#feature-flags
    registration: true
  }
})

Note: The parseSchema method isn't included in the above registration object because the ability to include more schemas is no longer supported.

IdP Discovery

IdP Discovery enables you to route users to different third-party IdPs that are connected to your Okta org. Users can federate back into the primary org after authenticating at the IdP. This feature still functions, but you no longer need to enable the link for users to initialize the route. Instead, you can configure a routing rule with the app context.

Remove the idpDiscovery property:

features: {
  idpDiscovery: true
}

OpenID Connect/social authentication

The Sign-In Widget no longer requires the idps JavaScript object, so you can remove it.

idps: [
  { type: 'GOOGLE', id: '0oagjkh' },
  { type: 'FACEBOOK', id: '0oagjkh' },
    ...
]

This is now optional as the Sign-In Widget automatically includes IdPs based on Identity Engine routing rules.

Bootstrap from a recovery token

If you're initializing Sign-In Widget with a recovery token, the recoveryToken setting appears:

recoveryToken: 'x0whAcR02i0leKtWMZVc'

The recovery token is dynamic and is automatically passed into the initialization of the Sign-In Widget. A value in the recoveryToken setting currently doesn't impact Sign-In Widget function, though the setting takes effect in the future.

Okta dashboard or custom dashboard sign-in flow

For an Okta dashboard sign-in flow, you no longer need to do the following:

• Configure a redirect to the Okta Identity Cloud
• Create an Okta session
• Open a URL specified in the Sign-In Widget

Remove the redirect configuration (setCookieAndRedirect()) line shown in the following snippet:

function success(res) {
  if (res.status === 'SUCCESS') {
    res.session.setCookieAndRedirect('https://{yourOktaDomain}/app/UserHome');
  }
};

Feature flags

The only feature that's supported when you upgrade Sign-In Widget is features.hideSignOutLinkInMFA, which hides the sign-out link for an MFA challenge.

The following specific features are no longer supported, and you can't configure them in the Sign-In Widget. Remove them from features in the JSON code:

• features.rememberMe: Displayed the "Remember me" function when a user signs in. See the Organization Settings (opens new window) section in the Okta product documentation to enable this feature.

• features.autoPush: Displayed a checkbox to enable the "Send push automatically" function in the MFA challenge flow. It may be added to the policy configuration in a future release.

• features.smsRecovery: Recovered the password for users with a configured mobile phone number by using an SMS message. See password recovery policy (opens new window) to enable and configure a possession (for example, a phone) authenticator.

• features.callRecovery: Recovered the password for users with a configured mobile phone number by using a voice call. See password recovery policy (opens new window) to enable and configure a possession (for example, a phone) authenticator.

• features.webauthn: Prevented Sign-In Widget from invoking the legacy Windows Hello factor. See sign-on policy (opens new window) to enable and configure a possession authenticator.

• features.selfServiceUnlock: Displayed the "Unlock Account" link so that users could unlock their accounts. See self-service account recovery (opens new window) to enable this feature.

• features.multiOptionalFactorEnroll: Allowed users to enroll in multiple optional factors before they finished the authentication flow. The MFA enrollment and rules (opens new window) are evaluated by default when applicable.

• features.registration: Displayed the registration section in the primary auth page. The user profile policies (opens new window) are evaluated by default when applicable.

• features.idpDiscovery: Enabled IdP Discovery when the user signed in. The Identity Provider routing rules (opens new window) are evaluated by default when applicable.

• features.showPasswordToggleOnSignInPage: Provided end users with the ability to view their password on the Okta sign-in page. This allows users to check their password entry before clicking Sign In. This feature also prevented an account lockout due to exceeding their org's permitted number of failed sign-in attempts.

• features.scrollOnError: Scrolled errors into view. Errors appear inside the Sign-In Widget.

• features.skipIdpFactorVerificationBtn: Provided an automatic redirect to the selected Identity Provider when selected from the list of factors. It's no longer needed since the optional authenticators can skip by default.

i18n properties

After you upgrade your org to Identity Engine, you can override existing text strings in the interface. Use Identity Engine i18n strings so that you can create localized Sign-In Widgets. See Updates to Sign-In Widget i18n properties.

Changes to Sign-In Widget customization for Identity Engine

Help title link and Need help signing in string

The following customizations aren't supported:

• Okta-hosted widget: The Help title link in the Customized Help Links section of the Customization page has been removed and isn't supported.
• Self-hosted widget: The Need help signing in string has been removed and isn't supported.

See Okta Sign-In Widget: Help links (opens new window).

The processCreds hook

Developers can't subscribe to the processCreds hook in the Sign-In Widget.

Registration inline hooks

Existing registration inline hooks may experience compatibility issues after migrating to Identity Engine due to changes in the Okta registration inline hook request. Your app may require code updates to consume the new request format properly.

In the Admin Console, where you enable a registration inline hook has changed. Enable the hook from the Profile Enrollment Rules page (Security > User Profile Policies) instead of the Self-Service Registration page (Self-service Directory > Self-Service Registration). The creation of the registration inline hook remains the same. You can use either the Admin Console or Inline Hook management APIs.

See Registration hooks API reference (opens new window) and Configure user profile policies (opens new window).

Security image

The ability for end users to specify a security image when they first register for an account isn't supported with Identity Engine. Also, existing users who may have already registered a security image can't see that image when they sign in.

See also

• Deprecated JavaScript methods in the Sign-In Widget

• Okta Identity Engine overview