@batoanng/oidc

Wrap routed React apps with OIDC callbacks, shared authorisation state, post-login profile enrichment, and optional axios token wiring around react-oidc-context.

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

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

Bring the package into your project with the published npm entrypoint.

npm install @batoanng/oidc

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.

Provide the OIDC settings once, then use the callback helpers to complete profile and privilege loading after login.

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

<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',
  }}
>
  <App />
</OidcAuthorisationProvider>;

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: 'test@example.com',
  };

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

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

• main: ./dist/oidc.js
• types: ./dist/src/index.d.ts

• eslint.config.mjs
• package.json
• src/
• test/
• tsconfig.build.json
• tsconfig.eslint.json
• tsconfig.json

• @batoanng/mui-components
• @emotion/react
• @mui/material
• axios
• oidc-client-ts
• react
• react-hook-form
• react-oidc-context
• react-router-dom
• react-use

• @batoanng/eslint-config
• @batoanng/prettier-config
• @batoanng/tsconfig
• @batoanng/vite-config
• @batoanng/mui-components

• @batoanng/mui-components
• @batoanng/utils
• @batoanng/eslint-config
• @batoanng/prettier-config
• @batoanng/tsconfig
• @batoanng/vite-config

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

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

• Replace published workspace:* development dependency ranges with npm semver ranges.
• Updated dependencies
  • @batoanng/mui-components@3.5.4

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

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

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

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.

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: 'test@example.com',
  };

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

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

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

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

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