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

Identity Engine

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

• Okta Developer Edition organization

• Okta Auth Javascript SDK (opens new window)

• Software requirements

---

Software requirements

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

• Latest npm (opens new window) version
• Latest Yarn (opens new window) version

Download the repository

Clone the Okta Auth JavaScript SDK (opens new window) repository to your local directory.

git clone https://github.com/okta/okta-auth-js.git

Important files, directories, and projects located in the okta/okta-auth-js repository include:

• /docs/idx.md (opens new window): Identity Engine introduction and reference
• /samples/generated (opens new window): Directory of sample apps
• /samples/generated/express-embedded-auth-with-sdk (opens new window): Express sample app using the Embedded SDK
• /samples/generated/express-embedded-sign-in-widget (opens new window): Express sample app using the Embedded Okta Sign-In Widget
• /samples/generated/react-embedded-auth-with-sdk (opens new window): React sample app using the Embedded SDK and MyAccountAPI methods
• /samples/generated/express-web-no-oidc (opens new window): Express sample app using the SDK's Okta Classic Engine methods (authN)
• /samples/generated/express-web-with-oidc (opens new window): Express sample app using the SDK's Classic Engine authentication methods and the OIDC API

Configure the SDK, Sign-In Widget, and sample app

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 starting your first app or if you're running a sample app, use the issuer URI of your default custom authorization server. To find this value:

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

Client ID

For the sample app, use the client ID for the app 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 app 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.

Use a redirect URI that is appropriate for your app or http://localhost:8080/login/callback if you're using the sample app.

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 (opens new window) for more information on OIDC scopes associated with access tokens.

Set the configuration values

There are many different ways to store these configuration values. Wherever you place them, ultimately, you need to create an object with the following properties:

const appConfig = {
    "clientId": "0oa1kelclsb...",
    "issuer": "https://{yourOktaDomain}/oauth2/default",
    "redirectUri": "http://app.example.com/login/callback",
    "scopes": [
        "openid",
        "profile",
        ...
    ],
    "pkce": true
 };

And pass this object to OktaAuth during initialization.

const oktaAuth = (() => {
  return new OktaAuth(appConfig);
})();

You have several options on where to locate your app's configuration settings. They are:

Directly in code

Set the configuration values directly in your code. For example, create a configuration file in your project with the name config.js. Add the settings to the default object.

export default {
  clientId: `0oa1kelclsb...`,
  issuer: `https://{yourOktaDomain}/oauth2/default`,
  redirectUri: `{window.location.origin}/login/callback`,
  scopes: [
    'openid',
    'profile',
    ...
  ],
  pkce: true
};

Import the file as a module in another file where you are instantiating OktaAuth. Pass its default object into OktaAuth's constructor.

import appConfig from './config';

const oktaAuth = (() => {
  return new OktaAuth(appConfig);
})();

Environment variables

Add environment variables on the server for each of the settings. Use names such as:

• ISSUER
• CLIENT_ID

Access these values using the global process.env object. For example, use process.env.ISSUER to access the issuer setting. Use webpack (opens new window), vite (opens new window), or another bundler to access these environment variables from the browser.

External configuration file

Read the settings from a configuration file located on the server. For example, use the dotenv (opens new window) package and create an external configuration file that defines each setting.

ISSUER=https://{yourOktaDomain}/oauth2/default
CLIENT_ID=0oa1kelclsb...
...

With dotenv you can access these values through process.env. As mentioned in the previous option, use webpack, vite, or another bundler to access these same environment variables from the browser.

Note: These configuration locations are also supported in the React sample app (opens new window).

Order of the configuration options

When multiple configurations are used simultaneously, the sample app (opens new window) selects the configuration based on the following order:

1. Directly in code
2. Environment variables
3. External configuration file

Note: Use only one configuration option in your solution to avoid confusion with setting overrides.

Set up the SDK for your own app

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

Set up the SDK in your app with the following steps:

1: Install the Okta Auth JavaScript (JS) SDK

Install the SDK in your project by using npm or yarn.

# Run this command in your project root folder.
# yarn
yarn add @okta/okta-auth-js

# npm
npm install --save @okta/okta-auth-js

2: Set the configuration settings

Set the SDK's configuration values described in Set the configuration values.

3: Initialize the SDK

const oktaAuth = new OktaAuth({
  // config
})

4: Review the SDK methods

Start integrating the available authentication workflows by reviewing the Auth JS SDK methods. See Usage (opens new window).

Note: For additional details setting up the SDK, see the npm Get Started guide (opens new window) and the SDK's yarn site (opens new window).

Set up the Sign-In Widget and SDK for your own app

See Install the SDK and Load the Sign-In Widget in the Sign in to your SPA with the embedded Okta Sign-In Widget guide to learn how to set up the Sign-In Widget in your React SPA app.