Instructions for

Sign in to your SPA with the embedded Okta Sign-In Widget

Instructions for

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

This guide walks you through how to build a password-only sign-in flow React app that uses the Okta Sign-In Widget for Okta embedded authentication.

Learning outcomes

Understand the sequence of steps required to add the Okta Sign-In Widget to a React app for embedded authentication.
Understand how to run the React sample app.

What you need

Note: Use the latest versions of the Okta SDKs and Sign-In Widget for your React app.

Sample code

Embedded React sample app with the Okta Sign-In Widget (opens new window) — See Run the sample React app.

If you want to deploy a React single-page app (SPA) in the embedded authentication model, where your app retains authentication control without redirection to Okta, then you can use the Okta Sign-In Widget to quickly add authentication. The Sign-In Widget is a JavaScript library that includes full sign-in features with Okta so the amount of authentication code you have to write for your app is minimal.

This guide explains how to build a password-only sign-in flow for your React app. Before you build or integrate your React app, ensure that you:

enable the Interaction Code grant on your default Custom Authorization Server
register your React app in Okta by creating an app integration

If you don't have an existing React app, you can create a new basic React app from the Create React App command.

Integrate the Sign-In Widget to your React app to add Okta authentication with the following steps:

Install dependencies: Install the Okta libraries for the integration.
Load the Sign-In Widget: Create the Sign-In Widget wrapper for the widget to be rendered as a React component.
Create the routes: Create the route components for your app.
Connect the routes: Connect your routes to the appropriate components.
When you are done integrating the Sign-In Widget to your React app, start your app to test your creation. Sign in with an existing user from your Okta org.

See Run the sample React app for an example of a simple embedded authentication React app that uses the Okta Sign-In Widget and libraries.

Create an Okta app integration

Before integrating Okta authentication into your React app, obtain the OpenID Connect client ID from your Okta org by creating an app integration. You can create an app integration through the Okta CLI (opens new window), the Okta Apps API, or through the Admin Console.

To create an Okta app integration that represents your React app, sign in to your Admin Console (opens new window).
From the side navigation, select Applications > Applications, and then click Create App Integration.
In the dialog that appears, select OIDC - OpenID Connect as the Sign-in method, Single-Page Application as the Application type, and then click Next.

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	Select Authorization Code, Interaction Code, and Refresh Token.
Sign-in redirect URIs	Specify your app URI for the callback redirect from Okta. For example: `http://localhost:8080/login/callback` for the sample app, or `http://localhost:3000/login/callback` for the default React app
Sign-out redirect URIs	Specify your app sign-out redirect URI. For example: `http://localhost:8080` for the sample app, or `http://localhost:3000` for the default React app
Trusted Origins > Base URIs	Specify your app base URI for CORS. For example: `http://localhost:8080` for the sample app, or `http://localhost:3000` for the default React app
Assignments	Assign users for your app.

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.
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.
Click Save.

Note: Be sure to also update the password authenticator policy rule 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 Okta app 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.

Okta org app integration configuration 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 that represents the authorization server. Use https://${yourOktaDomain}/oauth2/default as the issuer for your app if you're using an Okta Developer Edition org. See Issuer configuration if you want to use another Okta custom authorization server.

Install the SDK

Create a React app (optional)

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

npx create-react-app okta-app
cd okta-app

Install dependencies

Add the latest version of the Okta Sign-In Widget (opens new window) and the latest version of the Okta Auth JS SDK (opens new window) libraries to your React app. You can install them by using npm from your root app directory:

npm install @okta/okta-signin-widget@latest @okta/okta-auth-js@latest

Then install the latest version of the Okta React SDK (opens new window) (@okta/okta-react) and react-router-dom to manage the routes:

npm install @okta/okta-react@latest 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.

Set up the Okta configuration settings

Use the required configuration settings to initialize your Sign-In Widget and your Auth JS instance:

clientId: Your client ID — ${yourClientId}
issuer: The authorization server in your Okta org (for example, https://${yourOktaDomain}/oauth2/default)
useInteractionCodeFlow: Set this option to true to enable the Interaction Code flow in the widget for embedded authentication.
scopes: Set the OAuth 2.0 scopes that your app requires. For example, ['openid', 'profile', 'email'] are commonly used scopes. See Scopes for details on additional supported scopes.
redirectUri: Set your callback redirect URI. This value must be configured in your Okta app Sign-in redirect URIs and the URI host must be in the Trusted Origins list.

You can create a src/config.js file to define your configuration settings. For example:

export default {
  oidc: {
    issuer: 'https://${yourOktaDomain}/oauth2/default',
    clientId: '${clientId}',
    scopes: ['openid', 'profile', 'email'],
    redirectUri: `${window.location.origin}/login/callback`
  },
  widget: {
    issuer: 'https://${yourOktaDomain}/oauth2/default',
    clientId: '${clientId}',
    redirectUri: `${window.location.origin}/login/callback`,
    scopes: ['openid', 'profile', 'email'],
    useInteractionCodeFlow: true
  }
};

Note: The baseUrl configuration setting is required in the Sign-In Widget for OIDC applications prior to version 5.15.0 (opens new window). See Okta Sign-In Widget basic configuration options (opens new window) for additional widget configurations.

Note: See the Okta Auth JS configuration reference (opens new window) for additional Auth JS client configurations.

To render the Sign-In Widget in React, you must create a wrapper that allows your app to treat it as a React component. For example, create a src/OktaSignInWidget.jsx file with the following content:

import React, { useEffect, useRef } from 'react';
import OktaSignIn from '@okta/okta-signin-widget';
import '@okta/okta-signin-widget/dist/css/okta-sign-in.min.css';
import config from './config';

const OktaSignInWidget = ({ onSuccess, onError }) => {
  const widgetRef = useRef();
  useEffect(() => {
    if (!widgetRef.current) {
      return false;
    }

    const widget = new OktaSignIn(config.widget);
    widget.showSignInToGetTokens({
      el: widgetRef.current,
    }).then(onSuccess).catch(onError);

    return () => widget.remove();
  }, [onSuccess, onError]);

  return (<div ref={widgetRef} />);
};

export default OktaSignInWidget;

Note: Use the Auth JS showSignInToGetTokens() (opens new window) function to call the widget for OIDC single-page embedded apps.

Create the routes

Typically, an app contains routes that require authentication in order to render. Use the <SecureRoute> component from Okta React SDK (opens new window) to define authenticated routes for your app. The following are some basic routes that you need to configure for your app:

A default page to handle basic control of the app
A login route to show the Sign-In Widget
A callback route to parse tokens after a redirect from Okta
A protected route for authenticated users to access protected content

Default page route

For the default / page, create a src/Home.jsx file to provide links to relevant locations in your app.

You need to provide a Login link to render the Sign-In Widget, a Logout link to sign-out of your authenticated session, and links to authenticated pages by using the authState object (see authStateManager in the Auth JS SDK (opens new window)). The useOktaAuth() method is a React hook (opens new window) that returns an object containing the authState and the oktaAuth instance. This hook triggers the page to rerender whenever authState is updated.

import React from 'react';
import { Link, useHistory } from 'react-router-dom';
import { useOktaAuth } from '@okta/okta-react';

const Home = () => {
  const { oktaAuth, authState } = useOktaAuth();
  const history = useHistory();

  if (!authState) {
    return <div>Loading ...</div>;
  }

  const handleLogin = async () => history.push('/login');

  const handleLogout = async () => oktaAuth.signOut();

  return (
    <div id="home">
      <Link to="/">Home</Link> | &nbsp;
      <Link id="protected" to="/protected">Protected</Link> | &nbsp;
      {
        authState.isAuthenticated
          ? <button id="logout-button" type="button" onClick={handleLogout}>Logout</button>
          : <button id="login-button" type="button" onClick={handleLogin}>Login</button>
      }
    </div>
  );
};

export default Home;

This route hosts the Sign-In Widget and redirects the user to the default home page if the user is already signed in.

For example, create a src/Login.jsx file with the Login route component:

import React from 'react';
import { Redirect } from 'react-router-dom';
import OktaSignInWidget from './OktaSignInWidget';
import { useOktaAuth } from '@okta/okta-react';

const Login = ({ config }) => {
  const { oktaAuth, authState } = useOktaAuth();
  const onSuccess = (tokens) => {
    oktaAuth.handleLoginRedirect(tokens);
  };

  const onError = (err) => {
    console.log('Sign in error:', err);
  };

  if (!authState) {
    return <div>Loading ... </div>;
  }

  return authState.isAuthenticated ?
    <Redirect to={{ pathname: '/' }}/> :
    <OktaSignInWidget config={config} onSuccess={onSuccess} onError={onError}/>;
};

export default Login;

Callback route

The Okta React SDK (opens new window) provides the LoginCallback (opens new window) component for the callback route. It handles token parsing, token storage, and redirects the user to the / path. If a <SecureRoute> triggered the redirect, then the callback is directed to the secured route. See how the callback route component is called from the route definition file (src/App.jsx) in the Connect the routes section.

Protected route

Create a protected route that is only available to users with a valid accessToken.

In this /protected component example, a src/Protected.jsx file is created to show a basic protected page:

import React, { useState, useEffect } from 'react';
import { useOktaAuth } from '@okta/okta-react';

const Protected = () => {
  <h3 id="protected">Protected</h3>
  const { authState, oktaAuth } = useOktaAuth();
  const [userInfo, setUserInfo] = useState(null);

  useEffect(() => {
    if (!authState || !authState.isAuthenticated) {
      // When user isn't authenticated, forget any user info
      setUserInfo(null);
    } else {
      oktaAuth.getUser().then((info) => {
        setUserInfo(info);
      }).catch((err) => {
        console.error(err);
      });
    }
  }, [authState, oktaAuth]); // Update if authState changes

  if (!userInfo) {
    return (
      <div>
        <p>Fetching user info ...</p>
      </div>
    );
  }

  return (
    <div>
      <div>
        <p id="welcome">
          Welcome, &nbsp;{userInfo.name}!
        </p>
        <p>You have successfully authenticated against your Okta org, and have been redirected back to this application.</p>
      </div>
    </div>
  );
};

export default Protected;

Connect the routes

Rename the src/App.js file to src/App.jsx, and include components and routes for your app. The <Security> component controls the authentication flows, so it requires your OpenID Connect configuration. By default, the @okta/okta-react library redirects the user to Okta's sign-in page when the user isn't authenticated. In this example, onAuthRequired is overridden to redirect to the custom sign-in route instead.

Note: This example uses version 5.x of the react-router-dom module for the useHistory and Route objects.

import React from 'react';
import { Route, useHistory } from 'react-router-dom';
import { Security, SecureRoute, LoginCallback } from '@okta/okta-react';
import { OktaAuth, toRelativeUrl } from '@okta/okta-auth-js';
import Home from './Home';
import Login from './Login';
import Protected from './Protected';
import config from './config';

import logo from './logo.svg';
import './App.css';

const oktaAuth = new OktaAuth(config.oidc);

const App = () => {
  const history = useHistory();

  const customAuthHandler = () => {
    history.push('/login');
  };

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

  return (
    <div className="App">
      <header className="App-header">
        <p>My Okta-React app</p>
        <img src={logo} className="App-logo" alt="logo" />
      <Security
        oktaAuth={oktaAuth}
        onAuthRequired={customAuthHandler}
        restoreOriginalUri={restoreOriginalUri}
      >
        <Route path="/" exact component={Home} />
        <SecureRoute path="/protected" component={Protected} />
        <Route path="/login" render={() => <Login />} />
        <Route path="/login/callback" component={LoginCallback} />
    </Security>
    </header>
    </div>
  );
};

export default App;

Rename the src/index.js file to src/index.jsx and edit the file to call the app within the React DOM.

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

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

Start your app

To run and test your app, execute:

npm start

Open a browser and navigate to your app.

Run the sample application

You can run the sample embedded SIW React app (opens new window) to quickly view a sample working React app with the Sign-In Widget.

Ensure that you set up your Okta org for a password factor only use case and create an app integration in Okta for your sample app.
Download the sample app: git clone https://github.com/okta/samples-js-react.git
Go to the custom-login directory: cd samples-js-react/custom-login
Install the dependencies: npm install

Set the environment variables with your Okta org app integration configuration settings:

export ISSUER=https://${yourOktaDomain}/oauth2/default
export CLIENT_ID=${yourAppClientId}
export USE_INTERACTION_CODE=true

Alternatively, you can set the samples-js-react/testenv file with the configuration settings before you run the app:

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

Run the app server: npm start
Open a browser window and navigate to the app's home page: http://localhost:8080. Try to sign in to the sample app with an existing user from your Okta org.

On this page

Sign in to your SPA with the embedded Okta Sign-In Widget

Create an Okta app integration

Install the SDK

Run the sample application

Next steps

See also

On this page

Sign in to your SPA with the embedded Okta Sign-In Widget

About using the Sign-In Widget with your SPA app

Create an Okta app integration

Install the SDK

Load the Sign-In Widget

Basic sign-in flow

Run the sample application

Next steps

See also