React Ghost Auth

React library for authentication and authorization based on OpenID Connect (OIDC). It supports multiple providers (Google, Keycloak, Microsoft, etc.), Authorization Code flow with PKCE, in-memory token storage, and automatic token refresh.

Installation

npm install @iad-os/react-ghost-auth react

Peer dependency: react >= 16.14.0

Configuration

OIDC Provider

Each provider is a ProviderOptions object:

| Field | Type | Description | |-------|------|-------------| | issuer | string | OIDC issuer URL (e.g. https://auth.example.com/realms/my-realm) | | name | string | Provider name (e.g. "Keycloak") | | client_id | string | Application client ID | | client_secret | string | (optional) Client secret (for confidential clients) | | redirect_uri | string | Redirect URI after login | | redirect_logout_uri | string | Redirect URI after logout | | requested_scopes | string | Requested scopes (e.g. openid profile email) | | pkce | boolean | (optional) Use PKCE (recommended for SPAs) | | defualt | boolean | (optional) Default provider when issuer is not passed | | access_type | string | (optional) e.g. offline for refresh token | | kc_idp_hint | string | (optional) Keycloak identity provider hint |

App config

import type { AuthenticationConfig } from '@iad-os/react-ghost-auth';

const config: AuthenticationConfig = {
  providers: [
    {
      issuer: 'https://keycloak.example.com/realms/my-realm',
      name: 'Keycloak',
      client_id: 'my-app',
      redirect_uri: 'https://my-app.example.com/callback',
      redirect_logout_uri: 'https://my-app.example.com',
      requested_scopes: 'openid profile email',
      pkce: true,
      defualt: true,
    },
  ],
};

Usage

1. AuthenticationProvider

Wrap your app (or the part that uses auth) with the provider and pass the config and callbacks.

import AuthenticationProvider from '@iad-os/react-ghost-auth';

function App() {
  const config = { providers: [/* ... */] };

  return (
    <AuthenticationProvider
      config={config}
      onRoute={(route, overrided) => {
        // Called after login/logout with the URL to use (e.g. for the router)
        window.history.replaceState({}, '', route);
      }}
      onError={(message) => console.error(message)}
      refreshTokenBeforeExp={60}
      overrideRedirectUri={(loc) => `${loc.origin}${loc.pathname}`}
      enableLog={process.env.NODE_ENV === 'development'}
    >
      <YourApp />
    </AuthenticationProvider>
  );
}

AuthenticationProvider props:

| Prop | Type | Default | Description | |------|------|--------|-------------| | config | AuthenticationConfig | required | Config with the list of providers | | children | ReactNode | required | App content | | onRoute | (route, overrided) => void | required | Callback with the route to use after login/logout | | onError | (message: string) => void | optional | Callback for errors (e.g. from provider) | | refreshTokenBeforeExp | number | 0 | Seconds before token expiry to trigger automatic refresh (0 = disabled) | | overrideRedirectUri | (location) => string | optional | Override for redirect_uri (e.g. for hash-based SPA) | | enableLog | boolean | false | Enable debug logging in console |

2. Components

RequireAuth

Renders children only when the user is authenticated; otherwise renders loggedOut. Optionally triggers autologin.

import { RequireAuth } from '@iad-os/react-ghost-auth';

<RequireAuth
  loggedOut={<div>Please log in</div>}
  autologin={true}
>
  <Dashboard />
</RequireAuth>

| Prop | Type | Default | Description | |------|------|--------|-------------| | children | ReactNode | required | Content when logged in | | loggedOut | ReactNode | optional | Content when not logged in | | autologin | boolean | false | If true, in LOGGED-OUT state calls autologin() (starts login flow) |

Logged

Renders one content when logged in and another when not (no redirect, UI only).

import { Logged } from '@iad-os/react-ghost-auth';

<Logged
  in={<p>Welcome</p>}
  out={<p>Not authenticated</p>}
/>

| Prop | Type | Description | |------|------|-------------| | in | ReactNode | Content when logged in | | out | ReactNode | optional – Content when not logged in |

Logging

Renders content only during the “logging” phase (return from provider with code, token exchange in progress).

import { Logging } from '@iad-os/react-ghost-auth';

<Logging in={<Spinner />} />

| Prop | Type | Description | |------|------|-------------| | in | ReactNode | Content shown during token exchange |

AutoLogin

When in LOGGED-OUT state and a “current” provider exists (e.g. from a previous session), calls login(issuer); when status is LOGIN, can render children (e.g. “Redirecting to login…” screen).

import { AutoLogin } from '@iad-os/react-ghost-auth';

<AutoLogin>
  <p>Redirecting to login...</p>
</AutoLogin>

| Prop | Type | Description | |------|------|-------------| | children | ReactNode | optional – Content shown when in LOGIN phase (e.g. redirect message) |

3. Hooks

useAuthentication()

Exposes auth state and actions.

import { useAuthentication } from '@iad-os/react-ghost-auth';

function MyComponent() {
  const {
    login,           // (issuer?: string) => Promise<void>
    logout,          // () => Promise<void>
    autologin,       // () => void – sets status to LOGIN
    isAuthenticated, // () => boolean
    status,          // 'INIT' | 'LOGIN' | 'LOGGING' | 'LOGGED-IN' | 'LOGGED-OUT' | 'LOGOUT'
    refreshToken,    // () => Promise<TokenResponse>
    token,           // TokenResponse | undefined
    getCurrentProvider, // () => ProviderOptions | undefined
    providers,       // ProviderOptions[]
  } = useAuthentication();

  return (
    <div>
      {status === 'LOGGED-IN' ? (
        <button onClick={logout}>Logout</button>
      ) : (
        <button onClick={() => login()}>Login</button>
      )}
    </div>
  );
}

useToken()

Returns token and refreshToken only when the user is authenticated; otherwise throws.

import { useToken } from '@iad-os/react-ghost-auth';

function ProtectedApi() {
  const { token, refreshToken } = useToken();
  // token: TokenResponse, refreshToken: () => Promise<TokenResponse>
  return <div>Access token: {token.access_token.slice(0, 20)}…</div>;
}

Use it only inside a protected tree (e.g. under RequireAuth or after checking isAuthenticated()).

useUserInfo<T>()

Decodes the id_token (JWT) payload and returns it typed. Throws if not authenticated or no id_token.

import { useUserInfo } from '@iad-os/react-ghost-auth';

type MyClaims = { sub: string; email?: string; name?: string };

function Profile() {
  const user = useUserInfo<MyClaims>();
  return <div>{user.name ?? user.sub}</div>;
}

4. tokenService

Use when you need to handle login/logout/refresh outside React components (e.g. from services or after mount):

import { tokenService } from '@iad-os/react-ghost-auth';

// Login (redirects to provider)
await tokenService.login({ issuer: 'https://...' });
await tokenService.login(); // uses default provider

// Logout (redirects to provider end session)
await tokenService.logout();

// Refresh token
const newToken = await tokenService.refreshToken();

// Current token (from store)
const token = tokenService.getToken();

• login({ issuer?, overrideRedirectUri? }) – starts the OIDC flow.
• logout() – clears state and redirects to provider logout.
• refreshToken() – refreshes the token using the refresh token.
• getToken() – returns the current TokenResponse or undefined.

The code-to-token exchange (after redirect) is handled internally by AuthenticationProvider via tokenService.retriveToken; you typically do not need to call it yourself.

Exported types

• AuthenticationConfig – { providers: ProviderOptions[] }
• TokenResponse – access_token, refresh_token, id_token, expires_in, etc.
• ProviderOptions – see table above.

Flow overview

1. User clicks “Login” → login() (or tokenService.login()) is called.
2. The app stores in session state, code_verifier, redirect_uri, current_provider_issuer and redirects to the provider’s authorization endpoint.
3. User authenticates at the provider and is redirected back to your redirect_uri with ?code=...&state=....
4. AuthenticationProvider detects code and state, calls tokenService.retriveToken({ code, code_verifier }), stores the token in the store, and calls onRoute.
5. If refreshTokenBeforeExp > 0, an automatic refresh is scheduled before token expiry after login.
6. To sign out: logout() clears state and redirects to the provider’s end session.

Build

npm run build

Output in dist/ (CommonJS and ESM).