@credocentral/e-identity-react

React SDK for e-identity — OAuth2/OIDC authentication with PKCE, MFA gates, and forced-password-change support.

Features

• OAuth2 Authorization Code + PKCE login (browser redirect)
• Automatic token refresh (scheduled 60 s before expiry)
• localStorage or in-memory token storage
• MFA-aware context: mfaRequired, mfaVerified
• Forced password-change flag: forcePasswordChange
• Pre-built guard components (navigation-agnostic, fallback prop)
• Full TypeScript support

Installation

npm install @credocentral/e-identity-react @credocentral/e-identity-core

Peer dependencies: react >=18, react-dom >=18.

Quick Start

import { EIdentityProvider, useEIdentity, EIdentityGuard } from '@credocentral/e-identity-react';

const config = {
  issuerUrl: 'https://id.example.com',
  appId: '550e8400-e29b-41d4-a716-446655440000',
  redirectUri: 'https://app.example.com/auth/callback',
};

// 1. Wrap your app
export function App() {
  return (
    <EIdentityProvider config={config}>
      <EIdentityGuard fallback={<p>Redirecting to login…</p>}>
        <Dashboard />
      </EIdentityGuard>
    </EIdentityProvider>
  );
}

// 2. Access auth state anywhere
function Dashboard() {
  const { user, logout } = useEIdentity();
  return (
    <div>
      <p>Welcome, {user?.name}</p>
      <button onClick={logout}>Sign out</button>
    </div>
  );
}

Callback Page

Mount EIdentityCallback at your redirectUri path to complete the PKCE exchange:

import { EIdentityCallback } from '@credocentral/e-identity-react';
import { useNavigate } from 'react-router-dom';

export function CallbackPage() {
  const navigate = useNavigate();
  return (
    <EIdentityCallback
      onSuccess={() => navigate('/')}
      onError={(err) => navigate(`/login?error=${err.message}`)}
    />
  );
}

Configuration

| Option | Type | Required | Description | |---|---|---|---| | issuerUrl | string | ✅ | Base URL of the e-identity server (e.g. https://id.example.com) | | appId | string | ✅ | Your application UUID (appAId) | | redirectUri | string | ✅ | Must be registered as an allowed redirect URI | | scopes | string[] | — | Defaults to ['openid', 'profile', 'email'] | | tokenStorage | 'localStorage' \| 'memory' | — | Defaults to 'memory' |

useEIdentity Hook

const {
  user,              // User | null — parsed JWT claims
  accessToken,       // string | null
  isAuthenticated,   // boolean
  isLoading,         // boolean
  error,             // Error | null
  mfaRequired,       // boolean — user has MFA enabled but hasn't verified this session
  mfaVerified,       // boolean — token is AAL2
  forcePasswordChange, // boolean — user must change password before accessing resources
  login,             // () => Promise<void> — redirects to authorization server
  logout,            // () => Promise<void> — revokes tokens + clears storage
  getAccessToken,    // () => Promise<string | null> — returns fresh token (auto-refreshes if needed)
  setTokens,         // (tokens: TokenSet) => void — manually inject tokens (e.g. after server-side exchange)
} = useEIdentity();

Guard Components

EIdentityGuard

Redirects unauthenticated users to the authorization server. Renders fallback while loading or during redirect.

<EIdentityGuard fallback={<Spinner />}>
  <ProtectedPage />
</EIdentityGuard>

MfaChallengeGate

Renders fallback when the user is authenticated but has not completed MFA this session (mfaRequired && !mfaVerified).

<MfaChallengeGate fallback={<Navigate to="/mfa/challenge" />}>
  <SecurePage />
</MfaChallengeGate>

ForcedPasswordChangeGate

Renders fallback when the authenticated user has a forced-password-change pending.

<ForcedPasswordChangeGate fallback={<Navigate to="/change-password" />}>
  <App />
</ForcedPasswordChangeGate>

EIdentityCallback Props

| Prop | Type | Description | |---|---|---| | onSuccess | (tokens: TokenSet) => void | Called after a successful code exchange | | onError | (error: Error) => void | Called on any failure (state mismatch, exchange error, etc.) |

User Object

Claims parsed from the access token JWT:

interface User {
  sub: string;
  email: string;
  name?: string;
  given_name?: string;
  family_name?: string;
  picture?: string;
  roles?: string[];
  twoFaEnabledAuth?: number;   // 1 = MFA enabled
  mfa_verified?: boolean;       // true = AAL2
  forcePasswordChange?: number; // 1 = must change password
  amr?: string[];
  acr?: string;
  [key: string]: unknown;
}

Token Storage

| Option | Persistence | Use case | |---|---|---| | 'memory' (default) | Tab lifetime | SPAs that re-auth on reload; most secure | | 'localStorage' | Browser storage | SPAs that need to survive page refreshes |

Requirements

• React 18+
• @credocentral/e-identity-core (installed automatically as a dependency)