Instructions for

Load the widget

This guide covers the use case to load the Sign-In Widget, and provides a flow diagram and a sequence of integration steps.

Learning outcomes

Understand the sequence of steps to load the Sign-In Widget.

What you need

An app that uses the embedded Sign-In Widget and Identity Engine SDK
An Okta org already set up for your use case
A Sign-In Widget and SDK set up for your own app

Sample code

Configuration updates

Make sure to complete the steps to download and configure the SDK, Sign-In Widget, and sample app. These steps guide you to the appropriate repository and location of the embedded Sign-In Widget sample app. They also identify the packages to install and describe other changes to the Okta org that are required for the widget.

Summary of steps

Integration steps

The first step is to call the StartWidgetSigninAsync method when the page that contains the embedded widget is loaded. The IdxClient contains the configuration information (either from the okta.yaml file, env variables, or passed in from the constructor) to establish a connection to the Okta org and application.

The following sample code shows the instantiation of the IdxClient and the StartWidgetSignInAsync call.

public async Task<ActionResult> Index()
{
     var idxClient = new IdxClient(new IdxConfiguration()
     {
           Issuer = "https://dev-12345678.okta.com/oauth2/default",
           ClientId = "${clientId}",
           ClientSecret = "${clientSecret}",
           RedirectUri = "https://localhost:44314/interactioncode/callback/",
           Scopes = new List<string>{"openid","profile", "offline_access"}
     });

     var widgetSignInResponse = await idxClient.StartWidgetSignInAsync(default);
     var idxContext = widgetSignInResponse.IdxContext;
     var signInWidgetConfiguration = widgetSignInResponse.SignInWidgetConfiguration;

     return View(signInWidgetConfiguration);
}

Note: In the preceding MVC setup, the response's SignInWidgetConfiguration property is passed to the view as a model.

The StartWidgetSigninAsync call returns a WidgetSigninResponse response object. The SignInWidgetConfiguration property of this response object contains information that needs to be passed to the Sign-In Widget to initialize the page. The following example shows the object structure in JSON format. Replace ${widgetVersion} with the latest version (opens new window) of the widget (7.17.1).

{
   "interactionHandle":"epXgGYZHsYErPLfw8aLpCvWZOgVtYx25_OYCmQc0z2s",
   "version":"${widgetVersion}",
   "baseUrl":"https://dev-12345678.okta.com",
   "clientId":"${clientId}",
   "redirectUri":"https://localhost:44314/interactioncode/callback/",
   "authParams":{
      "issuer":"https://dev-122345678.okta.com/oauth2/default",
      "scopes":[
         "openid",
         "profile",
         "offline_access"
      ]
   },
   "state":"${state}",
   "otp":"${otp}",
   "codeChallenge":"${codechallenge}",
   "codeChallengeMethod":"S256"
}

Important: 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 configuration settings shown in the previous example. If you’re using version 7+ and you want to use Okta Classic Engine rather than Identity Engine, specify "useClassicEngine" = true in the configuration settings.

2a: Add namespaces and model

If using an MVC setup (as in the sample), the namespaces and model need to be defined in the page.

@using Newtonsoft.Json
@using Okta.Idx.Sdk

@model SignInWidgetConfiguration

2b: Add the Okta CDN link

Add the Sign-In Widget source to your page by referencing the Okta CDN, replacing ${widgetVersion} with the latest version (opens new window) of the widget:

@section head
{
   <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.17.1.

The next step includes the following activities:

Create a JavaScript object from the model.
Initialize the JavaScript model object and the widget object that passes in the div id (for example, okta-signin-widget-container) on the page.
Call the showSignInAndRedirect method on the widget object to display the sign-in page.

The div id that you passed into the widget needs to match a div on the page that you’re going to create in the next step. See the following sample code.

<script type="text/javascript">
   const widgetConfig = @Html.Raw(JsonConvert.SerializeObject(Model));

   console.log(widgetConfig.interactionHandle);

   const signIn = new OktaSignIn({
       el: '#okta-signin-widget-container',
       ...widgetConfig
   });

   // Search for URL Parameters to see if a user is being routed to the application to recover password
   var searchParams = new URL(window.location.href).searchParams;
   signIn.otp = searchParams.get('otp');
   signIn.state = searchParams.get('state');

   signIn.showSignInAndRedirect()
       .catch(err => {
           console.log('Error happen in showSignInAndRedirect: ', err);
       });
</script>

2d: Add div tag

The final step is to add a div element with the id (for example, okta-signin-widget-container). The id needs to match the id that you passed into the widget object in the previous step.

<div id="okta-signin-widget-container"></div>

The final step is to run your app. If the widget and Okta org are properly configured, the Sign-In Widget loads and appears, similar to the following image.

Basic Okta Sign-In Widget

Note: The Forgot password? and Sign Up links are configurable elements in your Okta org and may not appear on the page.

Edit This Page On GitHub