Instructions for

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

Instructions for

Note: This document is only for Identity Engine. See Identify your Okta solution (opens new window) to determine your Okta version.

This guide discusses 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 you integrate Okta authentication to your app, register your app in your Okta org. This provides you with the OpenID Connect client ID for authentication requests from your app. Register your app by creating an Okta app integration through the Okta Apps API (opens new window) or through the Admin Console with the following steps.

In the Admin Console, go to Applications > Applications.
Click Create App Integration.
Select OIDC - OpenID Connect as the Sign-in method.
Select Single-Page Application for the Application Type, and then click Next.
On the New Single-Page App Integration page, enter the following information:
- Enter an app name.
- Select the Refresh Token checkbox.
- Select Advanced in the Grant type section, and then select the Interaction Code checkbox.
  
  Note: If the Interaction Code checkbox doesn’t appear, the Interaction Code grant type isn’t enabled for your org. To enable it, go to Settings > Account > Embedded widget sign-in support. See Verify that the Interaction Code grant type is enabled.
- Set Sign-in redirect URIs to a URI that’s appropriate for your app. For example, http://localhost:3000/login/callback if you're using the sample app.
- Set Sign-out redirect URIs to a URI that’s appropriate for your app. For example, http://localhost:3000 if you're using the sample app.
In the Assignments section, select Allow everyone in your organization to access, and then click Save.
In the General Settings section on the General tab, click Edit.
Under EMAIL VERIFICATION EXPERIENCE, set the Callback URI to a URI that’s appropriate for your app. For example, http://localhost:3000/login/callback if you're using the sample app.
Click Save.
Select the Sign On tab and scroll 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, you 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: Remember to update the password authenticator policy rule to not require any additional verification.
Verify that the custom authorization server uses the Interaction Code grant type.

Go to Security > API > Authorization Servers.
Select the default server.
Edit the Default Policy Rule.
Click Advanced in the IF Grant type is section and ensure that the Interaction Code checkbox is selected.

Note: If the Interaction Code checkbox doesn’t appear, the Interaction Code grant type isn’t enabled for your org. To enable it, go to Settings > Account > Embedded widget sign-in support. See Verify that the Interaction Code grant type is enabled.

In the Security > API > Trusted Origins page, ensure that there’s an entry for your sign-in redirect URI. See Enable CORS.

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 Integrator Free Plan 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

To install 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) locally through npm, run the following command in your project root folder:

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)
scopes: Set the OAuth 2.0 scopes that your app requires. For example, ['openid', 'profile', 'email'] are commonly used scopes. See Scopes (opens new window) for details on more 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'],
  }
};

Important: In Okta Sign-In Widget version 7+, Identity Engine is enabled by default. If you’re using an earlier version than 7, you must explicitly enable Identity Engine features by setting useInteractionCodeFlow: true in the configuration settings shown above. If you’re using version 7+ and you want to use Classic Engine rather than Identity Engine, specify useClassicEngine: true in the configuration settings.

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

Note: See the Okta Auth JS configuration reference (opens new window) for more 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/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);

   // 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;
   widget.otp = searchParams.get('otp');
   widget.state = searchParams.get('state');
   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 Sign-In 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 = () => {
  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 { 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(
  <Router>
    <App />
  </Router>,
);

Start your app

To run and test your app, execute:

npm start

Open a browser and navigate to your app.

Run the sample app

You can run the sample embedded Sign-In Widget 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

Okta org app integration configuration settings

Install the SDK

Run the sample app

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

Okta org app integration configuration settings

Install the SDK

Load the Sign-In Widget

Basic sign-in flow

Run the sample app

Next steps

See also