@batoanng/oidc

@batoanng/oidc wraps react-oidc-context with router-aware callback routes, a shared authorisation context, post-login enrichment helpers, and ready-made authentication status screens for React single-page applications.

Features

• Wraps react-oidc-context with login, logout, and expired-password routing.
• Exposes a shared authorisation context through useOidcAuthorisationContext, useChallenge, and useChallengeResult.
• Provides OidcAuthorisationCallback for post-login profile and privilege loading.
• Can wire an axios client with Authorization headers and a single silent-refresh retry on 401.
• Ships reset-password, error, and status screens built on @batoanng/mui-components.

Installation

pnpm add @batoanng/oidc

Peer dependencies include react, react-router-dom, react-oidc-context, oidc-client-ts, axios, @mui/material, @emotion/react, react-hook-form, react-use, and @batoanng/mui-components.

If you use the built-in screens from @batoanng/mui-components, install any additional peers required by that package as well.

Usage

Wrap the routed part of your app with OidcAuthorisationProvider. The provider must live inside a React Router <Router> because it injects callback routes with <Routes>.

import { OidcAuthorisationProvider } from '@batoanng/oidc';

export function AppShell() {
  return (
    <OidcAuthorisationProvider
      userManagerSettings={{
        authority: 'https://your-idp.example.com',
        client_id: 'web-app',
        redirect_uri: 'http://localhost:3000/oidc/callback',
        post_logout_redirect_uri: 'http://localhost:3000/oidc/logout',
      }}
    >
      <AppRoutes />
    </OidcAuthorisationProvider>
  );
}

After the login callback completes, load the user profile and privileges, then hand them to OidcAuthorisationCallback so the shared authorisation context is populated before your protected UI renders.

import axios from 'axios';
import {
  OidcAuthorisationCallback,
  useOidcAuthorisationContext,
  useEnsureOidcLoginToken,
} from '@batoanng/oidc';

const apiClient = axios.create({
  baseURL: '/api',
});

export function PostLoginGate() {
  const userInformation = {
    shortName: 'T. User',
    fullName: 'Test User',
    email: '[email protected]',
  };

  const privileges = {
    'activityLog.read': true,
  };

  return (
    <OidcAuthorisationCallback apiClient={apiClient} userInformation={userInformation} privileges={privileges}>
      <ProtectedApp />
    </OidcAuthorisationCallback>
  );
}

export function ProtectedPage() {
  useEnsureOidcLoginToken();
  const { isAuthenticated, onLogout, token } = useOidcAuthorisationContext();

  return (
    <section>
      <div>{isAuthenticated ? 'Signed in' : 'Signed out'}</div>
      <div>{token}</div>
      <button onClick={() => void onLogout()}>Logout</button>
    </section>
  );
}

Auth Flow

flowchart TD
  A["App Router"] --> B["OidcAuthorisationProvider"]
  B --> C["react-oidc-context AuthProvider"]
  B --> D["/oidc/callback -> OidcLoginCallback"]
  B --> E["/oidc/logout -> OidcLogoutCallback"]
  B --> F["* -> OidcAuthorisationContextProvider"]
  D --> G{"Expired password response?"}
  G -- "Yes" --> H["/expired -> OidcResetPasswordPage"]
  G -- "No" --> I["Navigate to postLoginUrl or /"]
  F --> J["AuthorisationContext"]
  J --> K["useOidcAuthorisationContext / useChallenge"]
  I --> L["Load user profile and privileges"]
  L --> M["OidcAuthorisationCallback"]
  M --> N["Update user information and privilege state"]
  M --> O["Optional axios header + 401 retry wiring"]
  N --> P["Protected application UI"]
  O --> P

Props

OidcAuthorisationProvider

OidcAuthorisationCallback

Integration Notes

Default routes

Axios behavior

• setBearerToken stores the current access token on the axios instance and keeps defaults.headers.common.Authorization in sync.
• OidcAuthorisationCallback installs one response interceptor for the provided apiClient.
• A 401 triggers one signinSilent() attempt. If a new token is returned, the failed request is retried once with a refreshed Authorization header.

Related packages

• @batoanng/mui-components supplies the status, notification, and form primitives used by the built-in screens.
• @batoanng/utils is a related workspace utility package, but @batoanng/oidc now uses react-use directly for its local hook helpers.

Development

pnpm --dir packages/oidc lint
pnpm --dir packages/oidc type-check
pnpm --dir packages/oidc test
pnpm --dir packages/oidc build

Key files:

• src/OidcAuthorisationProvider.tsx
• src/OidcAuthorisationContextProvider.tsx
• src/OidcAuthorisationCallback.tsx
• src/hooks.ts
• src/types.ts