Instructions for

Download and set up the SDK, Sign-In Widget, and sample apps

This guide shows you how to download and configure the Identity Engine SDKs, Sign-In Widget, and accompanying samples after you create and set up your Okta org.

Learning outcomes

Download the SDK, Sign-In Widget, sample apps, and prerequisites required for your language.
Configure the settings that you require for the SDK and the Sign-In Widget.

What you need

Software requirements

Before you download the SDK, widget, and sample apps, you need the following:

Download the repository

There are two main repositories for the Golang embedded SDK and sample applications:

okta-idx-golang (opens new window) — enables Golang projects to use Okta as an OAuth 2.0 and OpenID Connect provider. The SDK communicates with the Okta Identity Engine to authenticate and register users.
samples-golang (opens new window) — contains sample applications that demonstrate the various use cases supported by the embedded SDK:
- samples-golang/identity-engine/embedded-auth-with-sdk — sample application that uses the embedded SDK to authenticate the user
- samples-golang/identity-engine/embedded-sign-in-widget — sample application that uses the embedded Sign-In Widget to authenticate the user

To use the sample applications, clone the samples-golang (opens new window) repository to your local directory.

To check out or contribute to the SDK source code, clone the okta-idx-golang (opens new window) repository to your local directory, make your changes, and submit the pull request.

Before you integrate the SDK or widget into your app, you must understand the configuration settings required to initialize the SDK and/or the Sign-In Widget.

Configuration settings

Issuer

There are two main types of authorization servers in Okta: Org and Custom. To understand which type to use, see Authorization servers.

Note: Okta's Developer Edition makes most key developer features available by default for testing purposes. Okta's API Access Management product — a requirement to use Custom Authorization Servers — is an optional add-on in production environments.

The issuer URI format depends on which authorization server that you decide to use:

Org—If you use the org authorization server, the issuer URI format is https://{yourOktaDomain} (for example, https://dev-example.okta.com).
Custom—You can either use the default custom authorization server or create your own.
- If you use the default custom authorization server, the issuer URI format is https://{yourOktaDomain}/oauth2/default.
- If you use your own custom authorization server, the issuer URI format is https://{yourOktaDomain}/oauth2/{authServerId}, where {authServerId} is your custom authorization server's unique ID.

If you're getting started with your first app or if you're running an Okta sample app, use the issuer URI of your default custom authorization server. To find this value:

In the Admin Console, go to Security > API.
On the Authorization Servers tab, use the Issuer URI value from the default custom authorization server row (for example, https://{yourOktaDomain}/oauth2/default).

Client ID

For the sample app, use the client ID for the application that you created in Create a new application. To find this value, go to Applications > Applications in the Admin Console. Select your app, and then on the General tab, copy the Client ID.

Redirect URI

This is the same value as the Redirect URI for the application that you created in Create a new application. To find this value, go to Applications > Applications in the Admin Console. Select your app, and then on the General tab copy the Sign-in redirect URI.

Scopes

The sample app uses the default scopes provided in the SDK, which include openid, profile, and others. See OpenID Connect & OAuth 2.0 API for more information on OIDC scopes associated with access tokens.

Set the configuration values

You have several options for setting the configuration values for your app.

Option 1: Create a configuration file

Create a YAML file named okta.yaml in one of the following directories:

Current user's home directory.
- Unix/Linux: ~/.okta/okta.yaml
- Windows: %userprofile%\.okta\okta.yaml
Application or project root directory

Add your configuration values to the file, using the following format:

okta:
  idx:
    issuer: "https://{yourOktaDomain}/oauth2/default"
    clientId: "{clientId}"
    clientSecret: "{clientSecret}"
    scopes:
      - "{scope1}"
      - "{scope2}"
    redirectUri: "{redirectUri}"

Option 2: Set the values as environment variables

Set the following environment variables with the configuration values:

OKTA_IDX_ISSUER
OKTA_IDX_CLIENTID
OKTA_IDX_CLIENTSECRET
OKTA_IDX_REDIRECTURI
OKTA_IDX_SCOPES

Option 3: Add the values as parameters to the SDK's client constructor

Add the values as parameters to the constructor for the IdxClient:

idx, err := idx.NewClient(
        idx.WithClientID(c.Okta.IDX.ClientID),
        idx.WithClientSecret(c.Okta.IDX.ClientSecret),
        idx.WithIssuer(c.Okta.IDX.Issuer),
        idx.WithScopes(c.Okta.IDX.Scopes),
        idx.WithRedirectURI(c.Okta.IDX.RedirectURI))

Order of the configuration options

When multiple configuration options are used simultaneously, the SDK selects the configuration to use based on the following order:

SDK Client constructor
Configuration file in the application or project root directory
Configuration file in the user's home directory
Environment variables

The values set in the SDK Client constructor are preferred to the configuration files, which in turn are preferred to those set in the environment variables. If setting values are missing from higher order locations, then the SDK attempts to find the setting values at a lower order location. For example, consider an application that runs on a machine where settings are stored in a configuration file (in the home directory) and also in environment variables. When the application loads, it first looks for the setting in the configuration file. Using the Client ID as an example, if the clientId setting is missing from the configuration file but the OKTA_IDX_CLIENTID environment variable is found, then the Client ID is set to the environment variable value.

Note: To avoid confusion as to which configuration values are used by the SDK, you should use only one configuration option in your solution.

Set up the SDK for your own app

Note: Try to run the embedded SDK sample app and explore the available embedded authentication use cases to get familiar with the SDK before you start to integrate your own embedded app.

Begin to integrate the SDK into your own app by following these steps:

1: Install the Golang SDK

Create a module file by running the following command:

go mod init

Run the following command to add the SDK to your go.mod file:

go get github.com/okta/okta-idx-golang.

Import the package in your project with import "github.com/okta/okta-idx-golang".

2: Create the IDX Client object

Create the IDX Client object by using the NewClient() method and optionally passing in a ConfigSetter object. Client is the main object that is used to initiate the various use cases with the SDK and Widget.

idx, err := idx.NewClient(
  os.Getenv("OKTA_IDX_CLIENTID"),
  os.Getenv("OKTA_IDX_CLIENT_SECRET"),
  os.Getenv("OKTA_IDX_ISSUER"),
  os.Getenv("OKTA_IDX_SCOPES"),
  os.Getenv("OKTA_IDX_REDIRECT_URI"))

Note: Run the embedded Widget sample app and explore the available embedded Widget use cases to get familiar with the Identity Engine and Sign-In Widget flow.

Begin to integrate the Sign-In Widget into your own embedded app by following these steps:

Install the Golang SDK, similar to the SDK embedded app.
Ensure that you're using the latest release of the Sign-In Widget (opens new window).
Source the Sign-In Widget from the Okta CDN.
Configure and initialize the Sign-In Widget.

Add the Sign-In Widget source to your sign-in page by referencing the Okta CDN, replacing {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.21.1.

When you initialize the Sign-In Widget on your sign-in page, you must configure it with all the required configuration settings for your app.

Initialize the Sign-In Widget with OktaSignIn() and the required Widget configurations (config). Call showSignInAndRedirect() to render the Widget on the sign-in page.

<div id="okta-signin-widget-container"></div>
<script type="text/javascript">
  var config = {};
  config.baseUrl = "{{ .BaseUrl }}";
  config.clientId = "{{ .ClientId }}";
  config.redirectUri = "http://localhost:8000/login/callback";
  config.interactionHandle = "{{ .InteractionHandle }}";
  config.codeChallenge = "{{ .Pkce.CodeChallenge }}";
  config.codeChallengeMethod = "{{ .Pkce.CodeChallengeMethod }}";
  config.debug = true;
  config.authParams = {
    issuer: "{{ .Issuer }}",
    scopes: ['openid', 'profile', 'email'],
  };
  const signIn = new OktaSignIn({
       el: '#okta-signin-widget-container',
       ...config
  });

   // 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>

Important: 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 config.useInteractionCodeFlow = true; in the configuration settings shown above. If you are using version 7+ and you want to use Okta Classic Engine rather than Identity Engine, specify config.useClassicEngine = true; in the configuration settings.

See Load the Widget for further details on integrating the Sign-In Widget into your app.

Edit This Page On GitHub