@axa-fr/react-oidc 7.29.3 → 7.29.5

package/README.md

@@ -1,749 +1,374 @@
 # @axa-fr/react-oidc
 
-[![Continuous Integration](https://github.com/AxaFrance/react-oidc/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/AxaFrance/react-oidc/actions/workflows/npm-publish.yml)
-[![npm downloads](https://img.shields.io/npm/dw/@axa-fr/react-oidc)](https://www.npmjs.com/package/@axa-fr/react-oidc)
+React components and hooks for OpenID Connect (OIDC), built on [`@axa-fr/oidc-client`](../oidc-client/README.md). The provider handles browser authentication callbacks, session restoration, and token renewal; your components use hooks to sign in, read user information, and call protected APIs.
 
-**@axa-fr/oidc-client** the lightest and securest library to manage authentication with OpenID Connect (OIDC) and OAuth2 protocol. It is compatible with all OIDC providers.
-**@axa-fr/oidc-client** is a pure javascript library. It works with any JavaScript framework or library.
+The library supports Authorization Code Flow with PKCE, multiple named configurations, optional service-worker token isolation, PAR, and DPoP. It is a browser-side authentication library, not a server-side session or authorization system.
 
-We provide a wrapper **@axa-fr/react-oidc** for **React** (compatible next.js) and we expect soon to provide one for **Vue**, **Angular** and **Svelte**.
+- [Quick start](#quick-start)
+- [Protect components](#protect-components)
+- [Call protected APIs](#call-protected-apis)
+- [User information and token hooks](#user-information-and-token-hooks)
+- [Service worker](#service-worker)
+- [Configuration, renewal, PAR, and DPoP](#configuration-renewal-par-and-dpop)
+- [Custom components and provider options](#custom-components-and-provider-options)
+- [Routing and Next.js](#routing-and-nextjs)
+- [Named configurations](#named-configurations)
+- [Errors and missing providers](#errors-and-missing-providers)
+- [Examples and further reading](#examples-and-further-reading)
 
-- Try the React demo at https://black-rock-0dc6b0d03.1.azurestaticapps.net/ (most advanced)
-- Try the pure javascript demo at https://icy-glacier-004ab4303.2.azurestaticapps.net/
+<a id="getting-started"></a>
 
-<img src="https://raw.githubusercontent.com/AxaFrance/oidc-client/main/docs/img/introduction.gif" alt="Sample React Oicd"/>
-
-- [About](#about)
-- [Getting Started](#getting-started)
-- [Run The Demo](#run-the-demo)
-- [Examples](#examples)
-- [How It Works](#how-it-works)
-- [NextJS](#NextJS)
-- [Hash route](#Hash-route)
-- [Service Worker Support](#service-worker-support)
-
-## About
-
-@axa-fr/react is:
-
-- **Secure** :
-  - With Demonstrating Proof of Possession (DPoP), your access_token and refresh_token are not usable outside your browser context (big protection)
-  - With the use of Service Worker, your tokens (refresh_token and/or access_token) are not accessible to the JavaScript client code (if you follow good practices from [`FAQ`](https://github.com/AxaFrance/oidc-client/blob/main/FAQ.md) section)
-  - OIDC using client side Code Credential Grant with pkce only
-- **Lightweight** : Unpacked Size on npm is **274 kB**
-- **Simple**
-  - refresh_token and access_token are auto refreshed in background
-  - with the use of the Service Worker, you do not need to inject the access_token in every fetch, you have only to configure OidcTrustedDomains.js file
-- **Multiple Authentication** :
-  - You can authenticate many times to the same provider with different scope (for example you can acquire a new 'payment' scope for a payment)
-  - You can authenticate to multiple different providers inside the same SPA (single page application) website
-- **Flexible** :
-  - Work with Service Worker (more secure) and without for older browser (less secure).
-  - You can disable Service Worker if you want (but less secure) and just use SessionStorage or LocalStorage mode.
-
-![](https://github.com/AxaGuilDEv/react-oidc/blob/master/docs/img/schema_pcke_client_side_with_service_worker.png?raw=true)
-
-The service worker catch **access_token** and **refresh_token** that will never be accessible to the client.
-
-## Getting Started
-
-```sh
-npm install @axa-fr/react-oidc --save
-
-# To install or update OidcServiceWorker.js file, you can run
-node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public
-
-# If you have a "public" folder, the 2 files will be created :
-# ./public/OidcServiceWorker.js <-- will be updated at each "npm install"
-# ./public/OidcTrustedDomains.js <-- won't be updated if already exist
-```
-
-WARNING : If you use Service Worker mode, the OidcServiceWorker.js file should always be up to date with the version of the library. You may setup a postinstall script in your package.json file to update it at each npm install. For example :
+## Quick start
 
 ```sh
-  "scripts": {
-    ...
-    "postinstall": "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public"
-  },
+npm install @axa-fr/react-oidc
 ```
 
-If you need a very secure mode where refresh_token and access_token will be hide behind a service worker that will proxify requests.
-The only file you should edit is "OidcTrustedDomains.js".
-
-```javascript
-// OidcTrustedDomains.js
+Register a public browser client with your identity provider using Authorization Code Flow with PKCE. Register the exact callback URL and post-logout URL, and allow the application's origin through CORS. Never embed a client secret in a browser application.
 
-// Add bellow trusted domains, access tokens will automatically injected to be send to
-// trusted domain can also be a path like https://www.myapi.com/users,
-// then all subroute like https://www.myapi.com/useers/1 will be authorized to send access_token to.
+Replace the issuer and client ID below with your own settings. This example assumes a client-rendered React application with an HTML element named `root`. Your web server must serve the application on `/authentication/callback` as well as `/`.
 
-// Domains used by OIDC server must be also declared here
-const trustedDomains = {
-  default: {
-    oidcDomains: ['https://demo.duendesoftware.com'],
-    accessTokenDomains: ['https://www.myapi.com/users'],
-  },
-};
-
-// Service worker will continue to give access token to the JavaScript client
-// Ideal to hide refresh token from client JavaScript, but to retrieve access_token for some
-// scenarios which require it. For example, to send it via websocket connection.
-trustedDomains.config_show_access_token = {
-  oidcDomains: ['https://demo.duendesoftware.com'],
-  accessTokenDomains: ['https://www.myapi.com/users'],
-  showAccessToken: true,
-  // convertAllRequestsToCorsExceptNavigate: false, // default value is false
-  // setAccessTokenToNavigateRequests: true, // default value is true
-  // bypassAllNonOidcRequests: false, // default value is false; when true, requests outside OIDC and accessTokenDomains are handled by the browser
-};
-
-// DPoP (Demonstrating Proof of Possession) will be activated for the following domains
-trustedDomains.config_with_dpop = {
-  domains: ['https://demo.duendesoftware.com'],
-  demonstratingProofOfPossession: true,
-  demonstratingProofOfPossessionOnlyWhenDpopHeaderPresent: true, // default value is false, inject DPOP token only when DPOP header is present
-  // Optional, more details bellow
-  /*demonstratingProofOfPossessionConfiguration: {  
-   importKeyAlgorithm: {
-     name: 'ECDSA',
-     namedCurve: 'P-256',
-     hash: {name: 'ES256'}
-   },
-   signAlgorithm: {name: 'ECDSA', hash: {name: 'SHA-256'}},
-   generateKeyAlgorithm: {
-     name: 'ECDSA',
-     namedCurve: 'P-256'
-   },
-   digestAlgorithm: { name: 'SHA-256' },
-   jwtHeaderAlgorithm : 'ES256'
- }*/
-};
+```tsx
+import { useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { OidcProvider, useOidc, type OidcConfiguration } from '@axa-fr/react-oidc';
 
-// Setting allowMultiTabLogin to true will enable storing login-specific parameters (state, nonce, code verifier)
-// separately for each tab. This will prevent errors when logins are initiated from multiple tabs.
-// IMPORTANT: When allowMultiTabLogin is true, you MUST use the OIDC fetch provided by useOidcFetch()
-// or withOidcFetch() for API requests. The service worker embeds a tab-specific token placeholder
-// in the Authorization header, which it then replaces with the real access token.
-// Using a plain fetch or axios without the OIDC fetch wrapper will result in requests being sent
-// without an Authorization header (401 errors), because the service worker cannot determine which
-// tab's token to inject without the placeholder.
-// Example with axios: configure it to use the OIDC fetch as its adapter or use the OIDC fetch directly.
-trustedDomains.config_multi_tab_login = {
-  domains: ['https://demo.duendesoftware.com'],
-  allowMultiTabLogin: true,
+const configuration: OidcConfiguration = {
+  client_id: 'your-public-client',
+  authority: 'https://issuer.example.com',
+  redirect_uri: `${window.location.origin}/authentication/callback`,
+  scope: 'openid profile',
 };
-```
-
-## Run The Demo
 
-```sh
-git clone https://github.com/AxaFrance/oidc-client.git
-cd oidc-client
-pnpm install
-cd /examples/react-oidc-demo
-pnpm install
-pnpm start
-# then navigate to http://localhost:4200
-```
-
-## Examples
-
-### Application startup
-
-The library is router agnostic and will use native History API.
+function Account(): React.JSX.Element {
+  const { login, logout, isAuthenticated } = useOidc();
+  const [hasError, setHasError] = useState(false);
+
+  const changeSession = async (): Promise<void> => {
+    setHasError(false);
+    try {
+      if (isAuthenticated) {
+        await logout('/');
+      } else {
+        await login('/');
+      }
+    } catch {
+      setHasError(true);
+    }
+  };
 
-The default routes used internally :
+  return (
+    <main>
+      <p>{isAuthenticated ? 'Signed in' : 'Not signed in'}</p>
+      <button type="button" onClick={changeSession}>
+        {isAuthenticated ? 'Sign out' : 'Sign in'}
+      </button>
+      {hasError && <p role="alert">Authentication failed. Please try again.</p>}
+    </main>
+  );
+}
 
-- www.your-app.fr/authentication/callback
+const root = document.getElementById('root');
+if (!root) throw new Error('Missing root element');
 
-```javascript
-import React from 'react';
-import { render } from 'react-dom';
-import { BrowserRouter as Router } from 'react-router-dom';
-import { OidcProvider } from '@axa-fr/react-oidc';
-import Header from './Layout/Header';
-import Routes from './Router';
-
-// This configuration use hybrid mode
-// ServiceWorker are used if available (more secure) else tokens are given to the client
-// You need to give inside your code the "access_token" when using fetch
-const configuration = {
-  client_id: 'interactive.public.short',
-  redirect_uri: window.location.origin + '/authentication/callback',
-  silent_redirect_uri: window.location.origin + '/authentication/silent-callback',
-  scope: 'openid profile email api offline_access', // offline_access scope allow your client to retrieve the refresh_token
-  authority: 'https://demo.duendesoftware.com',
-  par: 'auto',
-  service_worker_relative_url: '/OidcServiceWorker.js', // just comment that line to disable service worker mode
-  service_worker_only: false,
-  demonstrating_proof_of_possession: false,
-};
-
-const App = () => (
+createRoot(root).render(
   <OidcProvider configuration={configuration}>
-    <Router>
-      <Header />
-      <Routes />
-    </Router>
-  </OidcProvider>
+    <Account />
+  </OidcProvider>,
 );
-
-render(<App />, document.getElementById('root'));
 ```
 
-> [!WARNING]
-> If you have both `redirect_uri` and `silent_redirect_uri` configured, their value must be different.
-
-```javascript
-const configuration = {
-  loadingComponent: ReactComponent, // you can inject your own loading component
-  sessionLostComponent: ReactComponent, // you can inject your own session lost component
-  authenticating: ReactComponent, // you can inject your own authenticating component
-  authenticatingErrorComponent: ReactComponent,
-  callbackSuccessComponent: ReactComponent, // you can inject your own call back success component
-  serviceWorkerNotSupportedComponent: ReactComponent, // you can inject your page that explains you require a more modern browser
-  onSessionLost: Function, // If set, "sessionLostComponent" is not displayed, and onSessionLost callback is called instead
-  configuration: {
-    client_id: String.isRequired, // oidc client id
-    redirect_uri: String.isRequired, // oidc redirect url
-    silent_redirect_uri: String, // Optional activate silent-signin that use cookies between OIDC server and client javascript to restore sessions
-    silent_login_uri: String, // Optional, route that triggers the signin
-    silent_login_timeout: Number, // Optional, default is 12000 milliseconds
-    scope: String.isRequired, // oidc scope (you need to set "offline_access")
-    authority: String.isRequired,
-    storage: Storage, // Default sessionStorage, you can set localStorage, but it is not secure
-    login_state_storage: Storage, // Optional. Storage used only for authorization flow state (state, code_verifier, nonce, login params). Defaults to the value of `storage`. Set to sessionStorage when using storage: localStorage to prevent race conditions when multiple tabs start the login flow simultaneously.
-    authority_configuration: {
-      // Optional for providers that do not implement OIDC server auto-discovery via a .wellknown URL
-      authorization_endpoint: String,
-      token_endpoint: String,
-      userinfo_endpoint: String,
-      end_session_endpoint: String,
-      revocation_endpoint: String,
-      pushed_authorization_request_endpoint: String,
-      require_pushed_authorization_requests: Boolean,
-      check_session_iframe: String,
-      issuer: String,
-    },
-    refresh_time_before_tokens_expiration_in_second: Number, // default is 120 seconds
-    service_worker_relative_url: String,
-    service_worker_keep_alive_path: String, // default is "/"
-    service_worker_only: Boolean, // default false
-    service_worker_activate: () => boolean, // you can take the control of the service worker default activation which use user agent string
-    service_worker_register: (url: string) => Promise<ServiceWorkerRegistration>, // Optional, you can take the control of the service worker registration
-    extras: StringMap | undefined, // ex: {'prompt': 'consent', 'access_type': 'offline'} list of key/value that is sent to the OIDC server (more info: https://github.com/openid/AppAuth-JS)
-    token_request_extras: StringMap | undefined, // ex: {'prompt': 'consent', 'access_type': 'offline'} list of key/value that is sent to the OIDC server during token request (more info: https://github.com/openid/AppAuth-JS)
-    withCustomHistory: Function, // Override history modification, return an instance with replaceState(url, stateHistory) implemented (like History.replaceState())
-    authority_time_cache_wellknowurl_in_second: 60 * 60, // Time to cache in seconds of the openid well-known URL, default is 1 hour
-    authority_timeout_wellknowurl_in_millisecond: 10000, // Timeout in milliseconds of the openid well-known URL, default is 10 seconds, then an error is thrown
-    par: 'disabled' | 'auto' | 'required', // Pushed Authorization Requests mode, default is 'disabled'
-    par_request_timeout: Number, // PAR endpoint timeout in milliseconds, default is 10000
-    monitor_session: Boolean, // Add OpenID monitor session, default is false (more information https://openid.net/specs/openid-connect-session-1_0.html), if you need to set it to true consider https://infi.nl/nieuws/spa-necromancy/
-    onLogoutFromAnotherTab: Function, // Optional, can be set to override the default behavior, this function is triggered when a user with the same subject is logged out from another tab when session_monitor is active
-    onLogoutFromSameTab: Function, // Optional, can be set to override the default behavior, this function is triggered when a user is logged out from the same tab when session_monitor is active
-    token_renew_mode: String, // Optional, update tokens based on the selected token(s) lifetime: "access_token_or_id_token_invalid" (default), "access_token_invalid", "id_token_invalid"
-    token_automatic_renew_mode: TokenAutomaticRenewMode.AutomaticOnlyWhenFetchExecuted, // Optional, default is TokenAutomaticRenewMode.AutomaticBeforeTokensExpiration
-    // TokenAutomaticRenewMode.AutomaticBeforeTokensExpiration: renew tokens automatically before they expire
-    // TokenAutomaticRenewMode.AutomaticOnlyWhenFetchExecuted: renew tokens automatically only when fetch is executed
-    // It requires you to use fetch given by hook useOidcFetch(fetch) or HOC withOidcFetch(fetch)(Component)
-    logout_tokens_to_invalidate: Array<string>, // Optional tokens to invalidate during logout, default: ['access_token', 'refresh_token']
-    location: ILOidcLocation, // Optional, default is window.location, you can inject your own location object respecting the ILOidcLocation interface
-    demonstrating_proof_of_possession: Boolean, // Optional, default is false, if true, the the Demonstrating Proof of Possession will be activated //https://www.rfc-editor.org/rfc/rfc9449.html#name-protected-resource-access
-    demonstrating_proof_of_possession_configuration: DemonstratingProofOfPossessionConfiguration // Optional, more details bellow
-  },
-};
-
-demonstrating_proof_of_possession_configuration: DemonstratingProofOfPossessionConfiguration // Optional, more details bellow
-};
-
-interface DemonstratingProofOfPossessionConfiguration
-{
-  generateKeyAlgorithm:  RsaHashedKeyGenParams | EcKeyGenParams,
-          digestAlgorithm: AlgorithmIdentifier,
-          importKeyAlgorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm,
-          signAlgorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams,
-          jwtHeaderAlgorithm: string
-};
-
-// default value of demonstrating_proof_of_possession_configuration
-const defaultDemonstratingProofOfPossessionConfiguration: DemonstratingProofOfPossessionConfiguration ={
-  importKeyAlgorithm: {
-    name: 'ECDSA',
-    namedCurve: 'P-256',
-    hash: {name: 'ES256'}
-  },
-  signAlgorithm: {name: 'ECDSA', hash: {name: 'SHA-256'}},
-  generateKeyAlgorithm: {
-    name: 'ECDSA',
-    namedCurve: 'P-256'
-  },
-  digestAlgorithm: { name: 'SHA-256' },
-  jwtHeaderAlgorithm : 'ES256'
-};
+`OidcProvider` processes the callback route; do not call `loginCallbackAsync()` yourself inside this React setup. `login('/')` selects the application destination after authentication, not the registered callback URL.
 
+This example uses browser storage. For optional token isolation, follow the [service-worker setup](#service-worker).
 
+```mermaid
+flowchart LR
+    UI["React components and hooks"] --> Provider["OidcProvider"]
+    Provider --> Client["@axa-fr/oidc-client"]
+    Client --> IdP["OIDC identity provider"]
+    Client --> SW["Optional service worker"]
+    SW --> API["Trusted API"]
+    Client --> Fetch["OIDC fetch without worker"]
+    Fetch --> API
 ```
 
-### Pushed Authorization Requests (PAR)
+## Protect components
 
-PAR is configured on the nested OIDC `configuration` object:
+`OidcSecure` starts login when there is no authenticated session and renders its children only after authentication:
 
 ```tsx
-const configuration = {
-  client_id: 'spa-client',
-  redirect_uri: `${window.location.origin}/authentication/callback`,
-  scope: 'openid profile',
-  authority: 'https://issuer.example.com',
-  par: 'auto', // 'disabled' (default), 'auto', or 'required'
-};
-```
-
-`auto` uses the discovered `pushed_authorization_request_endpoint` when it is
-available. `required` fails before navigation if no endpoint is available.
-Once PAR is selected, a PAR endpoint error is surfaced and never silently
-downgraded. Browser deployments require the issuer's PAR endpoint to allow
-CORS from the application origin. See the
-[`@axa-fr/oidc-client` PAR documentation](../oidc-client/README.md#pushed-authorization-requests-par)
-for complete mode semantics, custom authority metadata, error handling, and
-security guidance.
-
-## How to consume
-
-> **Note (issue #1679):** `useOidc`, `useOidcUser`, `useOidcAccessToken` and
-> `useOidcIdToken` are safe to call **outside** of an `<OidcProvider>` (e.g.
-> in unit tests or Storybook stories). When no provider is mounted, they
-> emit a single `console.warn` per configuration name and return stable
-> default values (`isAuthenticated: false`, `oidcUser: null`,
-> `accessToken: null`, `idToken: null`, with no-op `login`/`logout`/
-> `renewTokens`/`reloadOidcUser`). Use `OidcClient.getOrThrow(name)` if you
-> prefer the previous fail-fast behaviour.
-
-"useOidc" returns all props from the Hook :
-
-```javascript
-import React from 'react';
-import { useOidc } from './oidc';
-
-export const Home = () => {
-  const { login, logout, renewTokens, isAuthenticated } = useOidc();
+import { OidcSecure } from '@axa-fr/react-oidc';
 
+export function PrivatePage(): React.JSX.Element {
   return (
-    <div className="container-fluid mt-3">
-      <div className="card">
-        <div className="card-body">
-          <h5 className="card-title">Welcome !!!</h5>
-          <p className="card-text">React Demo Application protected by OpenId Connect</p>
-          {!isAuthenticated && (
-            <button type="button" className="btn btn-primary" onClick={() => login('/profile')}>
-              Login
-            </button>
-          )}
-          {isAuthenticated && (
-            <button type="button" className="btn btn-primary" onClick={() => logout()}>
-              logout
-            </button>
-          )}
-          {isAuthenticated && (
-            <button type="button" className="btn btn-primary" onClick={() => renewTokens()}>
-              renewTokens
-            </button>
-          )}
-        </div>
-      </div>
-    </div>
+    <OidcSecure callbackPath="/account">
+      <h1>Account</h1>
+    </OidcSecure>
   );
-};
+}
 ```
 
-The Hook method exposes :
-
-- isAuthenticated : if the user is logged in or not
-- logout: logout function (return a promise)
-- login: login function 'return a promise'
-- renewTokens: renew tokens function 'return a promise'
-
-## How to secure a component
+Place it beneath `OidcProvider`. You can protect the whole application, a route element, or a smaller component. Optional props are `callbackPath`, authorization `extras`, and `configurationName`.
 
-`OidcSecure` component trigger authentication in case user is not authenticated. So, the children of that component can be accessible only once you are connected.
+The higher-order component (HOC) equivalent is:
 
-```javascript
-import React from 'react';
-import { OidcSecure } from '@axa-fr/react-oidc';
+```tsx
+import { withOidcSecure } from '@axa-fr/react-oidc';
 
-const AdminSecure = () => (
-  <OidcSecure>
-    <h1>My sub component</h1>
-  </OidcSecure>
-);
+function AccountDetails(): React.JSX.Element {
+  return <h1>Account details</h1>;
+}
 
-// adding the oidc user in the props
-export default AdminSecure;
+export const ProtectedAccountDetails = withOidcSecure(AccountDetails, '/account');
 ```
 
-## How to secure a component: HOC method
-
-`withOidcSecure` will act the same as `OidcSecure`,it will also trigger authentication in case the user is not authenticated.
-
-```javascript
-import React from 'react';
-import { Switch, Route } from 'react-router-dom';
-import { withOidcSecure } from '@axa-fr/react-oidc';
-import Home from '../Pages/Home';
-import Dashboard from '../Pages/Dashboard';
-import Admin from '../Pages/Admin';
-
-const Routes = () => (
-  <Switch>
-    <Route exact path="/" component={Home} />
-    <Route path="/dashboard" component={withOidcSecure(Dashboard)} />
-    <Route path="/admin" component={Admin} />
-    <Route path="/home" component={Home} />
-  </Switch>
-);
+Its signature is `withOidcSecure(Component, callbackPath?, extras?, configurationName?)`.
 
-export default Routes;
-```
+These components gate the UI; your APIs must independently validate tokens and enforce authorization.
 
-## How to get "Access Token": Hook method
+## Call protected APIs
 
-```javascript
-import { useOidcAccessToken } from '@axa-fr/react-oidc';
+`useOidcFetch()` returns a fetch wrapper that attaches the access token (or a service-worker placeholder) and integrates with renewal. Use it only for trusted API URLs, not arbitrary user-supplied destinations.
 
-const DisplayAccessToken = () => {
-  const { accessToken, accessTokenPayload } = useOidcAccessToken();
+```tsx
+import { useState } from 'react';
+import { useOidcFetch } from '@axa-fr/react-oidc';
+
+export function ProfileRequest(): React.JSX.Element {
+  const { fetch: oidcFetch } = useOidcFetch();
+  const [status, setStatus] = useState('Ready');
+
+  const loadProfile = async (): Promise<void> => {
+    setStatus('Loading…');
+    try {
+      const response = await oidcFetch('https://api.example.com/profile');
+      if (!response.ok) {
+        throw new Error(`API request failed with status ${response.status}`);
+      }
+      setStatus('Profile request succeeded');
+    } catch {
+      setStatus('Could not load the profile');
+    }
+  };
 
-  if (!accessToken) {
-    return <p>you are not authentified</p>;
-  }
   return (
-    <div className="card text-white bg-info mb-3">
-      <div className="card-body">
-        <h5 className="card-title">Access Token</h5>
-        <p style={{ color: 'red', backgroundColor: 'white' }}>
-          Please consider to configure the ServiceWorker in order to protect your application from
-          XSRF attacks. ""access_token" and "refresh_token" will never be accessible from your
-          client side javascript.
-        </p>
-        {<p className="card-text">{JSON.stringify(accessToken)}</p>}
-        {accessTokenPayload != null && (
-          <p className="card-text">{JSON.stringify(accessTokenPayload)}</p>
-        )}
-      </div>
-    </div>
+    <>
+      <button type="button" onClick={loadProfile}>
+        Load profile
+      </button>
+      <p role="status">{status}</p>
+    </>
   );
-};
+}
 ```
 
-## How to get IDToken: Hook method
+Render protected API consumers beneath `OidcSecure`, or wait until `useOidc().isAuthenticated` is true. Check `response.ok`: ordinary HTTP error responses do not automatically reject.
 
-```javascript
-import { useOidcIdToken } from '@axa-fr/react-oidc';
+| API                                                                                     | Arguments / result                                                            |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `useOidcFetch(fetch?, configurationName?, demonstratingProofOfPossession?)`             | Returns `{ fetch }`; defaults to browser fetch and configuration `'default'`. |
+| `withOidcFetch(fetch?, configurationName?, demonstratingProofOfPossession?)(Component)` | Injects a `fetch` prop into a component.                                      |
 
-const DisplayIdToken = () => {
-  const { idToken, idTokenPayload } = useOidcIdToken();
+For example, `withOidcFetch()(ProfileComponent)` supplies the same wrapper through props instead of a hook.
 
-  if (!idToken) {
-    return <p>you are not authentified</p>;
-  }
+## User information and token hooks
 
-  return (
-    <div className="card text-white bg-info mb-3">
-      <div className="card-body">
-        <h5 className="card-title">ID Token</h5>
-        {<p className="card-text">{JSON.stringify(idToken)}</p>}
-        {idTokenPayload != null && <p className="card-text">{JSON.stringify(idTokenPayload)}</p>}
-      </div>
-    </div>
-  );
-};
-```
+### User information
 
-## How to get User Information: Hook method
+`useOidcUser()` reads the provider's user-info endpoint and exposes loading state. The exported enum is **`OidcUserStatus`**:
 
-```javascript
-import { useOidcUser, UserStatus } from '@axa-fr/react-oidc';
+```tsx
+import { OidcUserStatus, useOidcUser } from '@axa-fr/react-oidc';
 
-const DisplayUserInfo = () => {
+export function UserGreeting(): React.JSX.Element {
   const { oidcUser, oidcUserLoadingState } = useOidcUser();
 
   switch (oidcUserLoadingState) {
-    case UserStatus.Loading:
-      return <p>User Information are loading</p>;
-    case UserStatus.Unauthenticated:
-      return <p>you are not authenticated</p>;
-    case UserStatus.LoadingError:
-      return <p>Fail to load user information</p>;
+    case OidcUserStatus.Loading:
+      return <p>Loading profile…</p>;
+    case OidcUserStatus.Unauthenticated:
+      return <p>Please sign in.</p>;
+    case OidcUserStatus.LoadingError:
+      return <p>Could not load your profile.</p>;
     default:
-      return (
-        <div className="card text-white bg-success mb-3">
-          <div className="card-body">
-            <h5 className="card-title">User information</h5>
-            <p className="card-text">{JSON.stringify(oidcUser)}</p>
-          </div>
-        </div>
-      );
+      return <p>Hello, {oidcUser?.name ?? 'there'}.</p>;
   }
-};
+}
 ```
 
-## How to get a fetch that inject Access_Token: Hook method
+The hook also returns `reloadOidcUser()`. Use `useOidcUser<MyUserInfo>(configurationName?, demonstratingProofOfPossession?)` for custom claims, where `MyUserInfo` extends `OidcUserInfo`.
 
-If you are not using the service worker. The Fetch function needs to send AccessToken.
-This hook will give you a wrapped fetch that adds the access token for you.
+### Hook reference
 
-```javascript
-import React, { useEffect, useState } from 'react';
-import { useOidcFetch, OidcSecure } from '@axa-fr/react-oidc';
+| Hook                                                                  | Return values                                                                                            |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `useOidc(configurationName?)`                                         | `isAuthenticated`, `login`, `logout`, `renewTokens`.                                                     |
+| `useOidcUser<T>(configurationName?, demonstratingProofOfPossession?)` | `oidcUser`, `oidcUserLoadingState`, `reloadOidcUser`.                                                    |
+| `useOidcAccessToken(configurationName?)`                              | `accessToken`, `accessTokenPayload`, and, when enabled, `generateDemonstrationOfProofOfPossessionAsync`. |
+| `useOidcIdToken(configurationName?)`                                  | `idToken`, `idTokenPayload`.                                                                             |
 
-const DisplayUserInfo = ({ fetch }) => {
-  const [oidcUser, setOidcUser] = useState(null);
-  const [isLoading, setLoading] = useState(true);
+`login(callbackPath?, extras?, silentLoginOnly?, scope?)`, `logout(callbackPath?, extras?)`, and `renewTokens(extras?)` return promises.
 
-  useEffect(() => {
-    const fetchUserInfoAsync = async () => {
-      const res = await fetch('https://demo.duendesoftware.com/connect/userinfo');
-      if (res.status != 200) {
-        return null;
-      }
-      return res.json();
-    };
-    let isMounted = true;
-    fetchUserInfoAsync().then(userInfo => {
-      if (isMounted) {
-        setLoading(false);
-        setOidcUser(userInfo);
-      }
-    });
-    return () => {
-      isMounted = false;
-    };
-  }, []);
-
-  if (isLoading) {
-    return <>Loading</>;
-  }
+Prefer `useOidcFetch` over manually building authorization headers. When worker token hiding is enabled, `accessToken` is a placeholder rather than the real token. Do not render or log raw tokens, and treat user claims as personal data. An ID token identifies the user to the client; it is not a replacement for an API access token.
 
-  return (
-    <div className="container mt-3">
-      <div className="card text-white bg-success mb-3">
-        <div className="card-body">
-          <h5 className="card-title">User information</h5>
-          {oidcUser != null && <p className="card-text">{JSON.stringify(oidcUser)}</p>}
-        </div>
-      </div>
-    </div>
-  );
-};
+## Service worker
 
-export const FetchUserHook = () => {
-  const { fetch } = useOidcFetch();
-  return (
-    <OidcSecure>
-      <DisplayUserInfo fetch={fetch} />
-    </OidcSecure>
-  );
-};
+Ensure your application's static-assets directory exists (`public` below), then install the worker assets:
+
+```sh
+node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public
 ```
 
-## How to get a fetch that inject Access_Token : HOC method
+Keep the generated `OidcServiceWorker.js` synchronized with package updates. For example, merge this into your application's `package.json`:
 
-If your are not using the service worker. Fetch function need to send AccessToken.
-This HOC give you a wrapped fetch that add the access token for you.
+```json
+{
+  "scripts": {
+    "postinstall": "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public"
+  }
+}
+```
 
-```javascript
-import React, { useEffect, useState } from 'react';
-import { useOidcFetch, OidcSecure } from '@axa-fr/react-oidc';
+Then:
 
-const DisplayUserInfo = ({ fetch }) => {
-  const [oidcUser, setOidcUser] = useState(null);
-  const [isLoading, setLoading] = useState(true);
+1. Configure `public/OidcTrustedDomains.js` with your provider and API destinations.
+2. Add `service_worker_relative_url: '/OidcServiceWorker.js'` to the OIDC configuration.
+3. Set `service_worker_only: true` if login must not fall back to browser token storage.
+4. Serve the worker over HTTPS (or localhost) with a scope that covers the application.
 
-  useEffect(() => {
-    const fetchUserInfoAsync = async () => {
-      const res = await fetch('https://demo.duendesoftware.com/connect/userinfo');
-      if (res.status != 200) {
-        return null;
-      }
-      return res.json();
-    };
-    let isMounted = true;
-    fetchUserInfoAsync().then(userInfo => {
-      if (isMounted) {
-        setLoading(false);
-        setOidcUser(userInfo);
-      }
-    });
-    return () => {
-      isMounted = false;
-    };
-  }, []);
-
-  if (isLoading) {
-    return <>Loading</>;
-  }
+Follow the [core service-worker guide](../oidc-client/README.md#service-worker) for a trusted-domain example, all options, token-exposure choices, and fallback behavior.
 
-  return (
-    <div className="container mt-3">
-      <div className="card text-white bg-success mb-3">
-        <div className="card-body">
-          <h5 className="card-title">User information</h5>
-          {oidcUser != null && <p className="card-text">{JSON.stringify(oidcUser)}</p>}
-        </div>
-      </div>
-    </div>
-  );
-};
+**Multi-tab login:** when `allowMultiTabLogin: true` is set in a trusted-domain entry, use `useOidcFetch()` or `withOidcFetch()` for protected API calls. Their tab-specific placeholder identifies the session to the worker. Plain fetch or a default Axios request cannot supply that marker and may result in HTTP 401.
 
-const UserInfoWithFetchHoc = withOidcFetch(fetch)(DisplayUserInfo);
-export const FetchUserHoc = () => (
-  <OidcSecure>
-    <UserInfoWithFetchHoc />
-  </OidcSecure>
-);
-```
+The worker can hide access and refresh tokens from application JavaScript, but it does **not** prevent XSS or stop injected code from making requests through your application. It does not hide all identity information. Keep normal XSS defenses and avoid broad trusted-domain rules.
 
-## Components override
+## Configuration, renewal, PAR, and DPoP
 
-You can inject your own components.
-All components definition receive props `configurationName`. Please checkout the demo for more complete example.
+`OidcProvider` accepts the same `OidcConfiguration` as the vanilla client. Keep provider props, such as custom components and routing callbacks, outside that configuration object.
 
-```javascript
-import React from 'react';
-import { render } from 'react-dom';
-import { BrowserRouter as Router } from 'react-router-dom';
-import { OidcProvider } from '@axa-fr/react-oidc';
-import Header from './Layout/Header';
-import Routes from './Router';
-
-// This configuration use hybrid mode
-// ServiceWorker are used if available (more secure) else tokens are given to the client
-// You need to give inside your code the "access_token" when using fetch
-const configuration = {
-  client_id: 'interactive.public.short',
-  redirect_uri: 'http://localhost:4200/authentication/callback',
-  silent_redirect_uri: 'http://localhost:4200/authentication/silent-callback',
-  scope: 'openid profile email api offline_access',
-  authority: 'https://demo.identityserver.io',
-  service_worker_relative_url: '/OidcServiceWorker.js',
-  service_worker_only: false,
-};
+- **Configuration:** see the [core configuration reference](../oidc-client/README.md#configuration) for required fields, storage, discovery, timeouts, logout, and session monitoring.
+- **Renewal:** automatic renewal is enabled by default. For `TokenAutomaticRenewMode.AutomaticOnlyWhenFetchExecuted`, use `useOidcFetch`/`withOidcFetch` so requests trigger renewal. See [renewal behavior and strict renewal](../oidc-client/README.md#token-renewal).
+- **Silent login:** add a distinct `silent_redirect_uri` if required. The provider handles its silent-login routes. Provider and browser cookie policies can prevent iframe login.
+- **PAR:** set `par: 'auto'` or `'required'` in `configuration`; the default is `'disabled'`. `auto` uses PAR when an endpoint is advertised; missing required endpoints fail before navigation. Once selected, PAR errors never silently downgrade. See [full PAR semantics, errors, and CORS requirements](../oidc-client/README.md#pushed-authorization-requests-par).
+- **DPoP:** enable `demonstrating_proof_of_possession` and use `useOidcFetch(undefined, 'default', true)` or `withOidcFetch(undefined, 'default', true)`. For user info, use `useOidcUser('default', true)`. See [DPoP and worker-specific settings](../oidc-client/README.md#dpop). Both the identity provider and resource server must support it.
 
-const Loading = () => <p>Loading</p>;
-const AuthenticatingError = () => <p>Authenticating error</p>;
-const Authenticating = () => <p>Authenticating</p>;
-const SessionLost = () => <p>Session Lost</p>;
-const ServiceWorkerNotSupported = () => <p>Not supported</p>;
-const CallBackSuccess = () => <p>Success</p>;
-
-//const [isSessionLost, setIsSessionLost] = useState(false);
-
-//const onSessionLost = ()=>{
-//  setIsSessionLost(true);
-//}
-
-const App = () => (
-  <OidcProvider
-    configuration={configuration}
-    loadingComponent={Loading}
-    authenticatingErrorComponent={AuthenticatingError}
-    authenticatingComponent={Authenticating}
-    sessionLostComponent={SessionLost}
-    //onSessionLost={onSessionLost} // If set "sessionLostComponent" is not displayed and onSessionLost callback is called instead
-    serviceWorkerNotSupportedComponent={ServiceWorkerNotSupported}
-    callbackSuccessComponent={CallBackSuccess}
-  >
-    {/* isSessionLost && <SessionLost />*/}
-    <Router>
-      <Header />
-      <Routes />
-    </Router>
-  </OidcProvider>
+## Custom components and provider options
+
+Replace built-in status screens with your own components. These are **provider props**, not fields inside `configuration`:
+
+```tsx
+const Loading = (): React.JSX.Element => <p>Restoring your session…</p>;
+const AuthenticationError = (): React.JSX.Element => (
+  <p role="alert">Sign-in failed. Please return to the sign-in page and try again.</p>
 );
 
-render(<App />, document.getElementById('root'));
+<OidcProvider
+  configuration={configuration}
+  loadingComponent={Loading}
+  authenticatingErrorComponent={AuthenticationError}
+>
+  <App />
+</OidcProvider>;
 ```
 
-## How It Works
+| Provider prop                                   | Purpose                                                                                                         |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `configuration`, `configurationName`            | Client configuration and its name (`'default'` by default).                                                     |
+| `loadingComponent`                              | Session restoration/loading screen.                                                                             |
+| `loadingTimeoutComponent`                       | Screen shown when the loading watchdog expires.                                                                 |
+| `authenticatingComponent`                       | Screen shown while starting login.                                                                              |
+| `authenticatingErrorComponent`                  | Login or callback failure screen.                                                                               |
+| `callbackSuccessComponent`                      | Screen shown after a successful callback.                                                                       |
+| `sessionLostComponent`                          | Session-loss screen.                                                                                            |
+| `serviceWorkerNotSupportedComponent`            | Unavailable-worker screen when worker-only mode is required.                                                    |
+| `onSessionLost`                                 | Handles session loss instead of displaying the built-in session-loss flow.                                      |
+| `onLogoutFromAnotherTab`, `onLogoutFromSameTab` | React to logout events.                                                                                         |
+| `onEvent(configurationName, eventName, data)`   | Observe client events; avoid logging complete payloads.                                                         |
+| `withCustomHistory`                             | Returns a history adapter with `replaceState(url, stateHistory?)`.                                              |
+| `navigateAfterCallback(callbackPath)`           | Async callback to perform post-login navigation; takes precedence over the history adapter for this navigation. |
+| `getFetch`                                      | Supplies a custom fetch implementation for the underlying client.                                               |
+| `location`                                      | Custom `ILOidcLocation` adapter.                                                                                |
 
-These components encapsulate the use of "@axa-fr/vanilla-oidc" in order to hide workflow complexity.
-Internally, native History API is used to be router library agnostic.
+Custom status components receive `configurationName`. Set `configuration.loading_timeout_ms` to change the default 30-second loading watchdog, or a nonpositive value to disable it. See [`OidcProviderProps`](./src/OidcProvider.tsx) for the full type.
 
-More information about OIDC
+## Routing and Next.js
 
-- [French : Augmentez la sécurité et la simplicité de votre Système d’Information OpenID Connect](https://medium.com/just-tech-it-now/augmentez-la-s%C3%A9curit%C3%A9-et-la-simplicit%C3%A9-de-votre-syst%C3%A8me-dinformation-avec-oauth-2-0-cf0732d71284)
-- [English : Increase the security and simplicity of your information system with openid connect](https://medium.com/just-tech-it-now/increase-the-security-and-simplicity-of-your-information-system-with-openid-connect-fa8c26b99d6d)
-- [English: youtube OIDC](https://www.youtube.com/watch?v=frIJfavZkUE&list=PL8EMdIH6Mzxy2kHtsVOEWqNz-OaM_D_fB&index=1)
-- [French: youtube OIDC](https://www.youtube.com/watch?v=H-mLMGzQ_y0&list=PL8EMdIH6Mzxy2kHtsVOEWqNz-OaM_D_fB&index=2)
+### Client-side routers
 
-## NextJS
+The default navigation uses the browser History API and dispatches `popstate`. Keep `OidcProvider` mounted on callback URLs. Protect route elements with `OidcSecure`; no particular router package is required.
 
-To work with NextJS you need to inject your own history surcharge like the sample below.
+For a router-specific integration, provide `navigateAfterCallback` to perform and await the router's navigation, or `withCustomHistory` to replace the default history adapter. These options belong on `OidcProvider`.
 
-**component/layout.js**
+The library retains hash-route callback matching for legacy integrations, but OAuth redirect URIs must not contain a fragment. Prefer path-based callback URLs for new deployments, even if the rest of the application uses a hash router. Existing hash-callback setups depend on provider-specific behavior. Interactive and silent callback URLs must be different.
 
-```javascript
-import { OidcProvider } from '@axa-fr/react-oidc';
-import { useRouter } from 'next/router';
+### Next.js
 
-const configuration = {
-  client_id: 'interactive.public.short',
-  redirect_uri: 'http://localhost:3001/#authentication/callback',
-  silent_redirect_uri: 'http://localhost:3001/#authentication/silent-callback', // Optional activate silent-login that use cookies between OIDC server and client javascript to restore the session
-  scope: 'openid profile email api offline_access',
-  authority: 'https://demo.duendesoftware.com',
-  par: 'auto',
-};
+Keep this browser library behind a client-only boundary: do not access `window` or initialize the OIDC client while rendering on the server. In the App Router, `'use client'` alone does not disable prerendering; use an appropriate client-only mounting or dynamic-import strategy.
 
-const onEvent = (configurationName, eventName, data) => {
-  console.log(`oidc:${configurationName}:${eventName}`, data);
-};
+The repository's [Next.js demo](../../examples/nextjs-demo/README.md) uses the **Pages Router** and a custom history adapter. For an initialized client-only provider using `next/router`, a post-login navigation adapter can look like this:
+
+```tsx
+import { useRouter } from 'next/router';
+import { OidcProvider } from '@axa-fr/react-oidc';
 
-export default function Layout({ children }) {
+function ClientAuth({ children }: React.PropsWithChildren): React.JSX.Element {
   const router = useRouter();
-  const withCustomHistory = () => {
-    return {
-      replaceState: url => {
-        router
-          .replace({
-            pathname: url,
-          })
-          .then(() => {
-            window.dispatchEvent(new Event('popstate'));
-          });
-      },
-    };
-  };
 
   return (
-    <>
-      <OidcProvider
-        configuration={configuration}
-        onEvent={onEvent}
-        withCustomHistory={withCustomHistory}
-      >
-        <main>{children}</main>
-      </OidcProvider>
-    </>
+    <OidcProvider
+      configuration={configuration}
+      navigateAfterCallback={async (path: string): Promise<void> => {
+        await router.replace(path);
+        window.dispatchEvent(new Event('popstate'));
+      }}
+    >
+      {children}
+    </OidcProvider>
   );
 }
 ```
 
-For more information checkout the [NextJS React OIDC demo](https://github.com/AxaGuilDEv/react-oidc/tree/master/packages/nextjs-demo)
+Here `configuration` is your browser-side OIDC configuration. Do not copy `next/router` into an App Router application; adapt to that router's APIs and navigation lifecycle. This package does not provide server-side route protection or a server session.
 
-## Hash route
+## Named configurations
 
-`react-oidc` work also with hash router.
+Use names to separate identity providers or sessions with different scopes. Give each configuration distinct callback URLs and, for worker mode, a matching trusted-domain entry.
 
-```javascript
-export const configurationIdentityServerWithHash = {
-  client_id: 'interactive.public.short',
-  redirect_uri: window.location.origin + '#authentication-callback',
-  silent_redirect_uri: window.location.origin + '#authentication-silent-callback',
-  scope: 'openid profile email api offline_access',
-  authority: 'https://demo.duendesoftware.com',
-  par: 'auto',
-  refresh_time_before_tokens_expiration_in_second: 70,
-  service_worker_relative_url: '/OidcServiceWorker.js',
-  service_worker_only: false,
-};
+```tsx
+<OidcProvider configuration={accountConfiguration}>
+  <OidcProvider configuration={paymentsConfiguration} configurationName="payments">
+    <App />
+  </OidcProvider>
+</OidcProvider>
+```
+
+Select the name explicitly; nesting does not change the hooks' default name:
+
+```tsx
+const { login, isAuthenticated } = useOidc('payments');
+const { fetch: paymentsFetch } = useOidcFetch(undefined, 'payments');
 ```
+
+Use `<OidcSecure configurationName="payments">` for that session's protected UI. Token and user hooks also accept a configuration name.
+
+## Errors and missing providers
+
+`OidcError`, `OidcErrorCode`, `isOidcError`, `OidcStateError`, `OidcStateErrorCode`, `isOidcStateError`, and the PAR error classes/guards are re-exported from this package. Use stable codes and phases, not string matching, for error handling.
+
+See the [core errors and events guide](../oidc-client/README.md#errors-and-events) for renewal errors, missing/mismatched state, missing nonces, retryability, and recovery. The provider's custom error/session-loss screens and `onEvent` callback are the React integration points. For strict renewal outside a hook, use `OidcClient.getOrThrow(name).renewTokensOrThrowAsync()`.
+
+When no client has been initialized for a name, `useOidc`, `useOidcUser`, `useOidcAccessToken`, and `useOidcIdToken` warn once per name and return unauthenticated/null defaults. This is useful in tests and Storybook, but does not initialize authentication.
+
+`OidcClient.get(name)` returns `null` for a missing client; `getOrThrow(name)` fails explicitly. `OidcSecure` and requests made through `useOidcFetch` require initialization and remain fail-fast. Mount a matching provider before using them.
+
+## Examples and further reading
+
+- [React demo](../../examples/react-oidc-demo/README.md) — routes, hooks, worker options, and named configurations.
+- [Next.js demo](../../examples/nextjs-demo/README.md) — Pages Router integration.
+- [Core client guide and API](../oidc-client/README.md).
+- [Service-worker protocol](../oidc-client-service-worker/PROTOCOL.md).
+- [Service-worker package guide](../oidc-client-service-worker/README.md).
+- [FAQ and deployment guidance](../../FAQ.md).
+
+The demos use the repository's pnpm workspace. Follow their READMEs for setup rather than installing each package separately.