Sign in to your SPA with Auth JS

Identity Engine

Note: This document is only for Identity Engine. If you’re using Classic Engine, see Sign in to SPA with Auth JS. See Identify your Okta solution (opens new window) to determine your Okta version.

This guide discusses building a password sign-in React app that uses the Okta Auth JS and React libraries for Okta embedded authentication.

---

Learning outcomes

Understand the sequence of steps required to implement Okta embedded authentication with the Auth JS and React libraries for your React app.

What you need

• Okta Developer Edition organization

• Okta Auth SDK (opens new window) (@okta/okta-auth-js)

• Okta React SDK (opens new window) (@okta/okta-react)

  Note: Use the latest version of the Okta libraries for your React app.

---

About using Okta Auth JS with your SPA app

You can retain authentication control of your React single-page app (SPA) without redirection to Okta by implementing embedded authentication. Use embedded authentication with the help of the Auth JS and React libraries. These libraries provide you with common, reusable OAuth 2.0 methods and properties to handle the interaction between the authorization server and your client app.

You can customize the sign-in experience for your app with minimal use of low-level Okta Authentication and Okta OpenID Connect (OIDC) & OAuth 2.0 APIs.

The authentication interaction between the authorization server and your client app follows the Interaction Code flow. This flow is an extension to the OAuth 2.0 and OIDC standard. It allows you to customize the user authentication experience for your app without redirecting to an authentication component outside of your app. See Implement authorization by Interaction Code grant type to understand the Interaction Code flow and necessary interactions between the authorization server and your app.

Note: You can use the Okta Sign-In Widget to embed authentication if you don't need full customization capabilities for your sign-in user experience. The Sign-In Widget handles the Interaction Code flow in authentication use cases offered by Okta. See Sign in to your SPA with the embedded Okta Sign-In Widget.

Create an Okta app integration

Before you integrate authentication into your React app, you need to register your app in your org. This provides you with the OpenID Connect client ID for authentication requests from your app. Register your app by creating an app integration through the Okta CLI (opens new window), the Okta Apps API (opens new window), or the Admin Console with the following steps:

1. To create an app integration for your React app, sign in to your Admin Console (opens new window).

2. Select Applications > Applications, and then click Create App Integration.

3. In the dialog that appears, select OIDC - OpenID Connect as the Sign-on method, Single-Page Application as the Application type, and then click Next.

4. Fill in the following new app integration settings, and then click Save:

   Setting	Value/Description
   App integration name	Specify a unique name for your app
   Grant types	Leave Authorization Code selected, and then select Refresh Token. Click Advanced and select Interaction Code.
   Sign-in redirect URIs	Specify your app URI for the callback redirect from Okta. For example, http://localhost:8080/login/callback.
   Sign-out redirect URIs	Specify your app sign-out redirect URI. For example: http://localhost:8080. Ensure that you add all your deployment URIs.
   Trusted Origins > Base URIs	Specify your app base URI for CORS. For example: http://localhost:8080. Ensure that you add trusted origins for all base URIs.
   Assignments	Assign users to your app

5. Select the Sign On tab and scroll down to the User authentication section. New apps are automatically assigned the shared default authentication policy (opens new window). This policy has a catch-all rule that allows a user access to the app using either one or two factors, depending on your org setup.

6. For this use case, we want to use only the password factor. Click Edit and select the Password only preset policy (opens new window) to assign it to your app.

7. Click Save.

   Note: Be sure to also update the policy rule of the password authenticator to not require any additional verification.

Note: Cross-Origin Resource Sharing (CORS) is automatically enabled for the Trusted Origins base URI that you specified in the Admin Console. If you're using the Okta CLI (opens new window) to create your SPA integration, CORS is also automatically enabled for your base URI. You can verify that both CORS and redirect are enabled for your app by reviewing the Security > API > Trusted Origins page in the Admin Console.

App integration settings

You need two pieces of information from your org and app integration for your React app:

• Client ID: From the General tab of your app integration, save the generated Client ID value.
• Issuer: From the General tab of your app integration, save the Okta domain value. Use your Okta domain value for the issuer setting, which represents the authorization server. Use https://{yourOktaDomain}/oauth2/default as the issuer for your app if you're using the Okta Developer Edition org. See Issuer configuration if you want to use another Okta custom authorization server.

Install the SDK

Download the sample React application

To view a simple example of a React app, clone the Auth JS repository and follow the setup procedure:

Clone the Auth JS repository

Clone the Auth JS repository and navigate to the top-level folder.

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

Install the dependencies

Install the dependencies in the okta-auth-js folder:

yarn install

Add a configuration file

Create and add a configuration file (testenv) to the okta-auth-js root folder. The testenv file contains the configuration values for your app integration. See Create an Okta app integration for details on these values.

ISSUER=https://{yourOktaDomain}/oauth2/default
CLIENT_ID={clientId}
USE_INTERACTION_CODE=true

Run the sample application

Navigate to the project folder and run the sample application. Click Login and sign in with a user from your Okta org. After a successful authentication, the user's access token appears on the page.

cd okta-auth-js/test/apps/react-oie
yarn start

Create a React app (optional)

If you don't have an existing React app, you can quickly create an app by using Create React App (opens new window):

npx create-react-app okta-app

Go into your root app directory to view the created files:

cd okta-app

Install dependencies

Add the following dependencies to your React app:

• The latest version of Okta Auth JS (opens new window), @okta/okta-auth-js

• The latest version Okta React SDK (opens new window), @okta/okta-react

• The react-router-dom libraries.

And install the dependencies using a package manager in your root app directory:

npm install @okta/okta-auth-js@latest
npm install @okta/okta-react@latest
npm install react-router-dom@5

Note: The sample code in this use case requires react-router-dom version 5.x. Certain objects used in the sample code don't exist in reactor-router-dom version 6.x.

Basic sign-in flow

Build a sign-in page that captures both the username and password. As an example, from the test application, see the index.js file, which renders the simple sign-in for from the formtransformer.js file:

import React from 'react';
import ReactDOM from 'react-dom';
import { BrowserRouter as Router } from 'react-router-dom';
import App from './App';

ReactDOM.render(
  <React.StrictMode>
    <Router>
      <App />
    </Router>
  </React.StrictMode>,
  document.getElementById('root')
);

From the formtransformer.js file:

const inputTransformer = nextStep => form => {
  // only process UI inputs
  const inputs = nextStep.inputs?.filter(input => !!input.label);

  if (!inputs?.length) {
    return form;
  }

  return {
    ...form,
    inputs: inputs.map(({ label, name, type, secret, required }) => {
      if (secret) {
        type = 'password';
      } else if (type === 'string') {
        type = 'text';
      } else if (type === 'boolean') {
        type = 'checkbox'
      }
      return { label, name, type, required };
    })
  };
};

Note: This guide only reviews the sign-in use case of the test app.

Review the simple password-only sign-in use case from the sample app. This use case is outlined in the following sequence diagram with your single-page app (SPA) as the client:

Set up the Okta configuration settings

Review the src/config.js file that references the required app integration settings to initialize your Okta Auth JS instance. The config.js file references the values that you add to the testenv file.

const CLIENT_ID = process.env.SPA_CLIENT_ID || process.env.CLIENT_ID || '{clientId}';
const ISSUER = process.env.ISSUER || 'https://{yourOktaDomain}/oauth2/default';
const REDIRECT_URI = `{window.location.origin}/login/callback`;

// eslint-disable-next-line import/no-anonymous-default-export
export default {
  clientId: CLIENT_ID,
  issuer: ISSUER,
  redirectUri: REDIRECT_URI,
  scopes: ['openid', 'offline_access', 'profile', 'email'],
};

Instantiate the Okta Auth JS client

Review the React app.js file that imports the required libraries and instantiates the Okta Auth JS client with values from the config.js.

import { useEffect, useState } from 'react';
import { useHistory } from 'react-router-dom';
import { OktaAuth, IdxStatus, urlParamsToObject, hasErrorInUrl } from '@okta/okta-auth-js';
import { formTransformer } from './formTransformer';
import oidcConfig from './config';
import './App.css';

function createOktaAuthInstance() {
  const { state } = urlParamsToObject(window.location.search);
  return new OktaAuth(Object.assign({}, oidcConfig, {
    state
  }));
}

const oktaAuth = createOktaAuthInstance();

...

Handle the password authentication

Review the apps.js file for details on handling a successful password authentication by receiving the SUCCESS status and storing the returned tokens:

....

const handleSubmit = async e => {
    e.preventDefault();

    const newTransaction = await oktaAuth.idx.proceed(inputValues); // inputValues = username, password
    console.log('Transaction:', newTransaction);

    setInputValues({});
    if (newTransaction.status === IdxStatus.SUCCESS) {
      oktaAuth.tokenManager.setTokens(newTransaction.tokens);
    } else {
      setTransaction(newTransaction);
    }
  };

  ...

Next steps

After you create a basic sign-in flow React app with a custom sign-in experience using the SDK, you can extend your app's sign-in experience. You can add features such as multifactor or social IdP authentication.

For further details on using the SDK to implement these features, see the Okta Auth JS SDK Interaction Code reference (opens new window).

To set up your Okta org for these use cases, see:

• Set up your Okta org for a multifactor use case
• Set up your Okta org for a social IdP use case

Note: The Admin Console and the Okta API support the Identity Engine org configuration.

See also

• Basic sign-in flow example with the password factor

• Okta Auth JS SDK Interaction Code reference (opens new window)