swissoid-front

SwissOID frontend helpers for relying-party applications. The package bundles the wiring we introduced in clockize-react so any React app can plug into the SwissOID session managed by a backend that exposes the swissoid-back implementation.

Features

• SwissOIDAuthProvider – context provider that keeps track of the SwissOID session, polls /auth/status, and exposes helpers to login, logout, refresh the session, and re-check status.
• useSwissOIDAuth() – hook that returns the current authentication state and helpers.
• AuthGuard – simple component that protects a subtree, optionally auto-redirecting to the backend login endpoint when the session has expired.
• AuthDebugPanel – drop-in diagnostics panel useful during integration to inspect cookies, raw payloads, and trigger session actions.
• createSwissOIDBackendClient() – utility that mimics the utils/oidc.ts helpers from clockize-react (initiateLogin, checkAuthStatus, logout) but works with any backend URL and endpoint configuration.

Quick start

import React from 'react';
import { SwissOIDAuthProvider, AuthGuard } from 'swissoid-front';

const App = () => (
  <SwissOIDAuthProvider
    config={{
      backendUrl: import.meta.env.VITE_BACKEND_URL,
      pollIntervalMs: 30_000,
    }}
  >
    <AuthGuard loadingFallback={<span>Loading session…</span>}>
      {/* protected routes */}
    </AuthGuard>
  </SwissOIDAuthProvider>
);

Inside your components you can access the session data:

import { useSwissOIDAuth } from 'swissoid-front';

const UserMenu = () => {
  const { user, logout } = useSwissOIDAuth();

  return (
    <button onClick={() => logout({ redirectTo: '/' })}>
      Sign out {user && (user as any).email}
    </button>
  );
};

To reproduce the clockize-react helpers:

import { createSwissOIDBackendClient } from 'swissoid-front';

const backend = createSwissOIDBackendClient({ backendUrl: import.meta.env.VITE_BACKEND_URL });

export const initiateLogin = backend.initiateLogin;
export const checkAuthStatus = () => backend.checkAuthStatus().then((res) => res.json());
export const logout = () => backend.logout({ redirectTo: '/' });

Configuration options

The provider accepts the following configuration:

| Option | Description | Default | | ------ | ----------- | ------- | | backendUrl | Base URL of the relying-party backend that mounted swissoid-back routes. | Required | | endpoints | Override paths for status, login, logout, refresh. | /auth/status, /login, /auth/logout, /auth/refresh | | pollIntervalMs | Interval for background /auth/status checks. | 30000 (30s) | | fetchImplementation | Custom fetch (useful in SSR/tests). | globalThis.fetch | | transformUser | Map the response payload to the user object stored in context. | identity | | loginRedirectParam | Query parameter name for continue URLs. | continue | | logoutRedirectTo | URL or callback invoked after logout. | none | | initialUser | Seed user (useful for SSR). | null | | defaultHeaders | Headers sent with backend requests. | none |

Building

npm install
npm run build

Installing dependencies can take a moment – if it times out, re-run the command locally.

The build emits dual CJS/ESM bundles with TypeScript declarations under dist/.