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 JavaScript SDK 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 Integrator Free Plan org

• Okta Auth JavaScript 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 (opens new window) 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 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 app sign-in 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. 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 Integrator Free Plan org. See Issuer configuration if you want to use another Okta custom authorization server.

Install the SDK

Download the sample React application

Clone the Auth JS repository and follow the setup procedure below to confirm your org and environment work end-to-end.

Note: The generated sample still uses Auth JS's Legacy Mode internally, so its App.jsx and GeneralForm.jsx source don't match the Step Mode code shown later in this guide. Use the sample only to verify your app integration settings and environment; use this guide's own code snippets as the reference for how to build the sign-in logic.

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}

Run the sample application

Navigate to the project folder and run the sample app. 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 samples/generated/react-embedded-auth-with-sdk
  yarn start

Create a React app (optional)

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

npm create vite@latest okta-app -- --template react

Go into your app directory and install the base dependencies:

cd okta-app
npm install

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 react-router-dom version 6.x or later. Okta's own reference sample app is also still on react-router-dom version 5.x, so there's no version 6+ equivalent to switch to yet.

Add environment variables

Vite only exposes environment variables to your app code when they're prefixed with VITE_ and read through import.meta.env, unlike some other React tooling. Create a .env file in your app's root folder with your app integration settings:

VITE_ISSUER=https://{yourOktaDomain}/oauth2/default
VITE_CLIENT_ID={clientId}

Note: Add .env to your .gitignore file so you don't commit it to source control.

Basic sign-in flow

Build a sign-in page that renders whichever fields the current step needs. This password-only flow asks for username first and password second. See the test application's main.jsx file, which renders the sign-in form using formTransformer.js:

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

const root = createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <Router>
      <App />
    </Router>
  </React.StrictMode>
);

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.

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 .env file.

const CLIENT_ID = import.meta.env.VITE_CLIENT_ID || '{clientId}';
const ISSUER = import.meta.env.VITE_ISSUER || 'https://{yourOktaDomain}/oauth2/default';
const REDIRECT_URI = `${window.location.origin}/login/callback`;

export default {
  clientId: CLIENT_ID,
  issuer: ISSUER,
  redirectUri: REDIRECT_URI,
  scopes: ['openid', 'offline_access', 'profile', 'email'],
  pkce: true
};

Note: Okta Auth JS 8.x requires every idx.proceed() call to name the remediation step it's submitting. This guide uses that Step Mode pattern throughout. See Step Mode vs Legacy Mode (opens new window) in the Auth JS SDK docs if you're migrating an older app that relies on the deprecated, generic remediation-driven pattern.

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. Wrap your app in the Security component from the Okta React SDK so it can manage the Auth JS instance for you.

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

const oktaAuth = new OktaAuth(oidcConfig);

...

function App() {
  const history = useHistory();
  const restoreOriginalUri = async (_oktaAuth, originalUri) => {
    history.replace(toRelativeUrl(originalUri || '/', window.location.origin));
  };

  return (
    <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
      ...
    </Security>
  );
}

Note: This guide's simplified example doesn't cover redirect callbacks (for example, social IdP sign-in or email magic links). If your app needs them, see Redirect callbacks (opens new window) in the Auth JS SDK docs and the LoginCallback component in Okta's reference sample app (opens new window).

Start the sign-in transaction

Before you can render a sign-in form, you need an in-progress IDX transaction to drive it. Start one when your component mounts by calling idx.start(). idx.start() begins the transaction. It doesn't resolve a step's field data until you name that step. Call idx.proceed() with only a step name and no other values. The SDK then returns that step's inputs for rendering. For this password-only use case, the sign-in flow always begins with the identify step, which asks for username:

const [transaction, setTransaction] = useState(null);

useEffect(() => {
  const startTransaction = async () => {
    await oktaAuth.idx.start();
    const newTransaction = await oktaAuth.idx.proceed({ step: 'identify' });
    setTransaction(newTransaction);
  };
  startTransaction();
}, []);

Pass transaction.nextStep into formTransformer to render the form fields for the current step. See Basic sign-in flow for the full form code. Okta's Identity Engine collects the username first. It then challenges for the password on a separate step. This password-only flow therefore renders two forms in sequence, not one combined form.

Handle the password authentication

Name the step you're submitting on every idx.proceed() call. transaction.nextStep.name holds that name. It matches the step the form already rendered. Submitting a step's values reveals the name of the next step. It does not reveal that step's renderable field data. Call idx.proceed() again with just the step name to prime the next form before you render it. Review the app.js file for details on handling a successful password authentication. It receives the SUCCESS status and stores the returned tokens:

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

  const submittedTransaction = await oktaAuth.idx.proceed({ step: transaction.nextStep.name, ...inputValues });
  console.log('Transaction:', submittedTransaction);
  setInputValues({});

  if (submittedTransaction.status === IdxStatus.SUCCESS) {
    oktaAuth.tokenManager.setTokens(submittedTransaction.tokens);
    return;
  }

  const newTransaction = await oktaAuth.idx.proceed({ step: submittedTransaction.nextStep.name });
  setTransaction(newTransaction);
};

For this password-only use case, handleSubmit runs twice. The first run submits username from the identify step and primes the challenge-authenticator step. The second run submits password from that step and reaches IdxStatus.SUCCESS.

The full sign-in component code

With the pieces above in place, here's the complete App.jsx for the password-only sign-in flow, with everything shown together:

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

const oktaAuth = new OktaAuth(oidcConfig);

function SignInForm() {
  const [transaction, setTransaction] = useState(null);
  const [inputValues, setInputValues] = useState({});

  useEffect(() => {
    const startTransaction = async () => {
      await oktaAuth.idx.start();
      const newTransaction = await oktaAuth.idx.proceed({ step: 'identify' });
      setTransaction(newTransaction);
    };
    startTransaction();
  }, []);

  const handleChange = ({ target: { name, value } }) => {
    setInputValues({ ...inputValues, [name]: value });
  };

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

    const submittedTransaction = await oktaAuth.idx.proceed({ step: transaction.nextStep.name, ...inputValues });
    console.log('Transaction:', submittedTransaction);
    setInputValues({});

    if (submittedTransaction.status === IdxStatus.SUCCESS) {
      oktaAuth.tokenManager.setTokens(submittedTransaction.tokens);
      return;
    }

    const newTransaction = await oktaAuth.idx.proceed({ step: submittedTransaction.nextStep.name });
    setTransaction(newTransaction);
  };

  if (!transaction?.nextStep) {
    return null;
  }

  const { inputs } = formTransformer(transaction.nextStep)({});

  return (
    <form onSubmit={handleSubmit}>
      {inputs.map(({ label, name, type, required }) => (
        <label key={name}>
          {label}
          <input
            name={name}
            type={type}
            required={required}
            value={inputValues[name] || ''}
            onChange={handleChange}
          />
        </label>
      ))}
      <button type="submit">Sign in</button>
    </form>
  );
}

function App() {
  const history = useHistory();
  const restoreOriginalUri = async (_oktaAuth, originalUri) => {
    history.replace(toRelativeUrl(originalUri || '/', window.location.origin));
  };

  return (
    <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
      <SignInForm />
    </Security>
  );
}

export default App;

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)