Upgrade your widget

Identity Engine

This guide covers how to upgrade the Okta Sign-In Widget, which depends on whether your user authentication deployment model is a redirect authentication or an embedded authentication.

---

Learning outcomes

• Update your 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 widget release (opens new window)

---

About the widget

The widget is a JavaScript library that gives you a full-featured and customizable sign-in experience that you can use to authenticate users of web and mobile applications.

The widget is used on Okta's default sign-in page to start an Okta SSO session and to set the Okta session cookie in the web browser. The widget can also perform a complete OpenID Connect (OIDC) flow and/or integrate with external Identity Providers.

This article teaches you how to upgrade the widget when it is used in any of the following ways:

• Okta-hosted sign-in page (default): Okta provides a sign-in page that is available at your org's URL. By default, a user who signs in on this page is redirected to the Okta user dashboard.
• Okta-hosted sign-in page (customizable): Okta provides a sign-in page that you can customize and make available under a custom domain that is a subdomain of your company's top-level domain.
• Embedded (self-hosted): You can embed the widget directly into your application.

After you've completed the widget upgrade, review Okta Identity Engine overview to take advantage of new features in Identity Engine.

Best practice for widget maintenance

For best practices, keep your widget (opens new window) up to date. This maintenance is essential so that you can use the latest Identity Engine features and benefit from ongoing improvements to the codebase.

The specific steps to upgrade your widget depend on your user authentication deployment model, which can be one of the following:

• Redirect authentication: Okta-hosted with no custom URL domain
• Redirect authentication: Okta-hosted with custom URL domain
• Embedded authentication: Self-hosted. The embedded widget is able to perform the OIDC flow and return OAuth tokens directly within the application.

Upgrade process for a redirect sign-in flow

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

• If you haven't configured a custom domain and don't have customizations outside of simple branding styles, your widget is automatically upgraded to the latest version when it's loaded from the content delivery network (CDN).
• If you've configured a custom domain and have other customizations, admins must update the widget version in the Admin Console.

To update the widget:

1. In the Admin Console, go to Customizations > Sign-in page code editor.

   In the Okta Sign-In Widget Version section, check that the Major Version is the highest version available and Minor Version is latest. The widget is always the latest version if you're not using a custom URL domain.

2. If you're using the custom domain feature and the version isn't correct, you can change the widget's version. Click Edit in the Okta Sign-In Widget Version section and then select the Major Version and Minor Version fields.

3. Click Save at the bottom of the page.

4. Test your app's supported authentication sign-up and recovery flows to ensure that they still work.

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

Upgrade process for an embedded widget

Upgrade your embedded widget by referencing the Okta CDN in your sign-in page. Replace ${widgetVersion} with the latest version (opens new window) of the widget:

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

See also Using the Okta CDN (opens new window). The latest version of the widget is 7.4.1.

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

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).

Changes to widget configuration for Identity Engine

For Identity Engine, the widget is configured differently. You can remove some specific objects that were previously in the 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 are 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 are using version 7+ and you want to use Okta 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 widget. You can add registration into your application by configuring your Okta admin settings for profile enrollment (opens new window). This process allows users to self register into your application.

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 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 additional 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 application context.

Remove the idpDiscovery property:

features: {
  idpDiscovery: true
}

OpenID Connect/social authentication

You no longer require the idps JavaScript object in the widget and 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.

Bootstrapping from a recovery token

If you're initializing the widget with a recovery token, the recoveryToken setting appears, for example:

recoveryToken: 'x0whAcR02i0leKtWMZVc'

The recovery token is dynamic and is automatically passed into the initialization of the widget. A value in the recoveryToken setting currently doesn't have any effect on 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 configure a redirect to the Okta Identity Cloud, create an Okta session, and then open a URL specified in the 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 is supported when you upgrade the widget is features.hideSignOutLinkInMFA, which hides the sign-out link for a MFA challenge.

The following specific features are no longer supported, and you can't configure them in the widget. You must 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 the password recovery policy (opens new window) topic in the Okta product documentation 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 the password recovery policy (opens new window) topic in the Okta product documentation to enable and configure a possession (for example, a phone) authenticator.

• features.webauthn: Prevented the widget from invoking the legacy Windows Hello factor. See the sign-on policy (opens new window) in the Okta product documentation 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 profile enrollment 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 toggle visibility of their password on the Okta sign-in page so that they could 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 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 have the ability to skip by default.

I18n properties

After you upgrade your org to Identity Engine, you can override existing text strings in the interface with Identity Engine i18n strings so that you can create localized widgets. See Updates to the widget i18n properties.

Changes to 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).

processCreds hook

Developers can't subscribe to the processCreds hook in the 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 application may require code updates to consume the new request format properly.

In the Admin Console, the enablement of a registration inline hook has changed from the former Self-Service Registration page (Self-service Directory > Self-Service Registration) to the Profile Enrollment Rules page (Security > Profile Enrollment). 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 and Manage Profile Enrollment 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. Additionally, existing users who may have already registered a security image won't see that image when they sign in.

See also

Deprecated JavaScript methods in the widget