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

Identity Engine

Instructions for

React

Loading...

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

• Okta Developer Edition organization
• Okta Auth JavaScript SDK (opens new window)
• Okta React SDK (opens new window)
• Okta Sign-In Widget (opens new window)
• Create React App (opens new window)

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.

---

About using the Sign-In Widget with your SPA 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.

Integrate the Sign-In Widget with your SPA app

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:

1. Install dependencies: Install the Okta libraries for the integration.
2. Load the Sign-In Widget: Create the Sign-In Widget wrapper for the widget to be rendered as a React component.
3. Create the routes: Create the route components for your app.
4. Connect the routes: Connect your routes to the appropriate components.
5. 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 CLI (opens new window), the Okta Apps API, or through the Admin Console with the following steps.

1. In the Admin Console, go to Applications > Applications.

2. Click Create App Integration.

3. Select OIDC - OpenID Connect as the Sign-in method.

4. Select Single-Page Application for the Application Type, and then click Next.

5. On the New Single-Page App Integration page:

   • Enter an application name.

   • 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. Early Access

   • Select the Refresh Token checkbox.

   • Set Sign-in redirect URIs to a URI that is appropriate for your app. For example, http://localhost:8080/login/callback if you're using the sample app.

   • Set Sign-out redirect URIs to a URI that is appropriate for your app. For example, http://localhost:8080 if you're using the sample app.

6. In the Assignments section, select Allow everyone in your organization to access, and click Save.

7. In the General Settings section on the General tab, click Edit.

8. Under EMAIL VERIFICATION EXPERIENCE set Callback URI to a URI that is appropriate for your app. For example, http://localhost:8080/login/callback if you're using the sample app.

9. Click Save.

10. 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.

11. 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.

12. Click Save.

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

13. In the Security > API > Authorization Servers section, verify that the custom authorization server uses the Interaction Code grant type by selecting the default server, clicking Access Policies, and then editing the Default Policy Rule. Review the If Grant type is section to 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. Early Access

14. In the Security > API > Trusted Origins page, ensure that there is 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 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

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.

Load the Sign-In Widget

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 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'],
  }
};

Important: In Okta Sign-In Widget version 7+, Identity Engine is enabled by default. If you are 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 are using version 7+ and you want to use Okta 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 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.

Create a Sign-In Widget wrapper

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);

   // 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 widget for OIDC single-page embedded apps.

Basic sign-in flow

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;

Login route

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.

1. 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.

2. Download the sample app: git clone https://github.com/okta/samples-js-react.git

3. Go to the custom-login directory: cd samples-js-react/custom-login

4. Install the dependencies: npm install

5. 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
   

6. Run the app server: npm start

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

Next steps

After you complete a basic-sign flow for your React app with the Sign-In Widget, you can extend your app's sign-in experience by adding features such as multifactor or social IdP authentication. There is almost no code required in your app to add these features because the Sign-In Widget provides the mechanism to handle these use cases. These features are enabled by configuring Okta authenticators and authentication policies for your app. See:

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

Note: Okta org configuration is supported by the Admin Console and by the Okta API.

See also

• Sign-In Widget guide
• Sign users in to your SPA using the redirect model for the redirect authentication deployment model
• Use redirect auth with the sample apps for multiple use case sample apps that use the redirect authentication deployment model
• Load the widget for web apps that use the embedded authentication deployment model
• Basic sign-in flow using the password factor for a web app that uses the embedded authentication deployment model
• Blog: A Quick Guide to React Login Options (opens new window) for React app authentication options with the Okta Classic Engine