Registry / auth-security / react-oidc-context

react-oidc-context

JSON →
library3.3.1jsnpmunverified

react-oidc-context is a lightweight authentication library for React Single Page Applications (SPAs) that leverages the React Context API for state management, built on top of the `oidc-client-ts` library. The current stable version is 3.3.1. The package maintains a fairly active release cadence, with frequent bugfix and minor releases, and significant major versions introducing breaking changes as the underlying `oidc-client-ts` library evolves. It differentiates itself by providing convenient React hooks (`useAuth`) and Higher-Order Components (`withAuthenticationRequired`) to integrate OpenID Connect and OAuth2 authentication flows seamlessly into React components, handling aspects like token renewal and redirect callbacks without requiring manual route setup. It ships with full TypeScript support, making it suitable for modern React development.

npm install react-oidc-context
INSTALL
IMPORT
SIG · REACT-OIDC-CONTEXT
R
react-oidc-context
auth-securityjavascriptv3.3.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AuthProvider
import { AuthProvider } from 'react-oidc-context';
const { AuthProvider } = require('react-oidc-context');
The library is ESM-only since v3.0.0. Use named imports for `AuthProvider` to wrap your React application.
useAuth
import { useAuth } from 'react-oidc-context';
const { useAuth } = require('react-oidc-context');
This hook provides access to the authentication state and methods within function components. The library ships with TypeScript types.
withAuthenticationRequired
import { withAuthenticationRequired } from 'react-oidc-context';
const { withAuthenticationRequired } = require('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.

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> );
Debug
Known issues
breakingVersion 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).
affects: >=3.0.0
gotchaSince 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`).
affects: >=3.0.0
gotchaIt 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.
affects: >=2.x
breakingThe 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.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: crypto.subtle is undefined
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.
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'
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.
Upgrade
Version history
3.3.1latest on npm
Audit
Dependencies
oidc-client-tsrequiredCore OpenID Connect client library that handles the OIDC protocol details.
reactrequiredThe core React library for building user interfaces.
Agent activity
16 hits · last 30 days
node
15
OpenAI (training)
1
Resources
react-oidc-context — npm install react-oidc-context · libregistry