React OIDC Context

Common errors

• TypeError: crypto.subtle is undefined

  cause The application is running in an insecure context (HTTP) where the Web Cryptography API (`crypto.subtle`) is not available.
  fix Serve your application over HTTPS. For local development, configure your server to use SSL/TLS or use a tool like `mkcert`.

• Token renewal (signinSilent) is not working after a successful login and subsequent page refresh.

  cause The OIDC response payload remains in the URL after a successful login, preventing `oidc-client-ts` from correctly initiating silent renewals.
  fix Implement the `onSigninCallback` function in your `oidcConfig` to clear the URL parameters, e.g., `onSigninCallback: () => { window.history.replaceState({}, document.title, window.location.pathname); }`.

• Error: require() not supported for ESM module 'react-oidc-context'

  cause Attempting to use CommonJS `require()` syntax to import `react-oidc-context`, which is an ESM-only module since version 3.0.0.
  fix Update your import statements to use ESM `import` syntax (e.g., `import { AuthProvider } from 'react-oidc-context';`) and ensure your build configuration supports ESM.

Warnings

• breaking Version 3.0.0 introduced a breaking change by upgrading its peer dependency `oidc-client-ts` to v3.x. This change requires Node.js version >=18 and uses `crypto.subtle` instead of `crypto-js` for cryptographic operations.
  Fix: Ensure your Node.js environment is version 18 or higher. Update `oidc-client-ts` to a compatible v3.x version (`^3.1.0` or later).
• gotcha Since v3.0.0, the library relies on the Web Cryptography API (`crypto.subtle`), which is only available in secure contexts (HTTPS). Running your application over plain HTTP will cause runtime errors related to undefined `crypto.subtle`.
  Fix: Always run your application under HTTPS, even during local development (e.g., via `mkcert` or a reverse proxy like `nginx`).
• gotcha It is crucial to implement the `onSigninCallback` function within your `oidcConfig` to clear the OIDC payload from the URL upon successful login. Failure to do so will prevent `signinSilent` (automatic token renewal) from working correctly after a page refresh.
  Fix: Add an `onSigninCallback` to your `oidcConfig` that uses `window.history.replaceState({}, document.title, window.location.pathname);` to clean the URL.
• breaking The library transitioned to being an ESM-only module since v3.0.0. Direct `require()` statements for `react-oidc-context` will fail.
  Fix: Ensure your project is configured for ESM and use `import` statements for all `react-oidc-context` imports.

Install

• npm install react-oidc-context npm
• yarn add react-oidc-context yarn
• pnpm add react-oidc-context pnpm

Imports

• AuthProvider
  wrong:

  const { AuthProvider } = require('react-oidc-context');

  correct:

  import { AuthProvider } from 'react-oidc-context';

  The library is ESM-only since v3.0.0. Use named imports for `AuthProvider` to wrap your React application.
• useAuth
  wrong:

  const { useAuth } = require('react-oidc-context');

  correct:

  import { useAuth } from 'react-oidc-context';

  This hook provides access to the authentication state and methods within function components. The library ships with TypeScript types.
• withAuthenticationRequired
  wrong:

  const { withAuthenticationRequired } = require('react-oidc-context');

  correct:

  import { withAuthenticationRequired } from 'react-oidc-context';

  A higher-order component (HOC) to secure routes or components by redirecting unauthenticated users to the login page. Introduced in v3.0.0-rc.0.

Quickstart

This quickstart demonstrates how to set up `AuthProvider` to configure OpenID Connect and use the `useAuth` hook within a functional component to manage authentication state (loading, authenticated, user info) and trigger authentication actions like login and logout. It highlights the critical `onSigninCallback` for proper token renewal.

import React from 'react';
import ReactDOM from 'react-dom/client';
import { AuthProvider, useAuth } from 'react-oidc-context';

// Your OIDC configuration
const oidcConfig = {
  authority: 'https://your-identity-provider.com',
  client_id: 'your-client-id',
  redirect_uri: window.location.origin + '/authentication/callback',
  onSigninCallback: () => {
    // IMPORTANT: Clear URL payload upon successful login to prevent issues with silent renew
    window.history.replaceState({}, document.title, window.location.pathname);
  },
  // automaticSilentRenew: true, // Enable automatic token renewal
  // scope: 'openid profile email',
  // ... other oidc-client-ts UserManagerSettings
};

function App() {
    const auth = useAuth();

    switch (auth.activeNavigator) {
        case 'signinSilent':
            return <div>Signing you in silently...</div>;
        case 'signoutRedirect':
            return <div>Signing you out...</div>;
    }

    if (auth.isLoading) {
        return <div>Loading authentication status...</div>;
    }

    if (auth.error) {
        return <div>Authentication error: {auth.error.message}</div>;
    }

    if (auth.isAuthenticated) {
        return (
        <div>
            Hello, {auth.user?.profile.name || auth.user?.profile.sub}{' '}
            <button onClick={() => void auth.removeUser()}>Log out locally</button>
            <button onClick={() => void auth.signoutRedirect()}>Log out from IdP</button>
        </div>
        );
    }

    return (
      <div>
        <p>You are not authenticated.</p>
        <button onClick={() => void auth.signinRedirect()}>Log in</button>
      </div>
    );
}

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <AuthProvider {...oidcConfig}>
      <App />
    </AuthProvider>
  </React.StrictMode>
);