API reference

provideAuth(config, ...features)

Configures OIDC authentication. Call once in app.config.ts.

interface AuthConfig {
  issuerUrl: string; // Required: auth server base URL
  clientId: string; // Required: OIDC client ID
  scopes?: string[]; // Default: openid profile email offline_access phone address pl:extended_profile
  redirectUri?: string; // Default: ${origin}/auth/callback
  postLogoutRedirectUri?: string; // Default: ${origin}/auth/logged-out
  silentRefresh?: boolean; // Default: true
  refreshBeforeExpiry?: number; // Default: 30 (seconds before expiry to refresh)
  secureRoutes?: string[]; // URL prefixes that receive the Authorization header (default: all)
}

withAuthInterceptor()

Pass to provideHttpClient(). Attaches the Bearer token to requests matching secureRoutes. Triggers logout on 401.

provideHttpClient(withAuthInterceptor());

AuthService

class AuthService {
  readonly isAuthenticated: Signal<boolean>;
  readonly currentUser: Signal<User | null>;
  readonly accessToken: Signal<string | null>;

  login(returnUrl?: string): void;
  logout(localOnly?: boolean): void;
  handleCallback(): Promise<void>;
  checkAuth(): Promise<boolean>;
  refreshToken(): Promise<string | null>;
  isTokenExpired(thresholdSeconds?: number): boolean;
}

createAuthCallbackRoute(overrides?)

Returns a pre-configured Route for the OAuth callback. The auth guard processes the callback and navigates to the stored return URL (or /).

// Default path: auth/callback
createAuthCallbackRoute();

// Custom path or additional guards
createAuthCallbackRoute({ path: 'callback' });

Guards

authGuard

Pre-built guard using defaults: saves the return URL and triggers auto-login.

{ path: 'dashboard', canActivate: [authGuard], component: DashboardComponent }

createAuthGuard(config?)

interface AuthGuardConfig {
  redirectUrl?: string; // Default: '/auth/logged-out' (when autoLogin is false)
  saveReturnUrl?: boolean; // Default: true
  autoLogin?: boolean; // Default: true
}

createAuthGuard({ autoLogin: false, redirectUrl: '/login' });

createGroupsGuard(config)

interface GroupsGuardConfig {
  groups: string | string[];
  mode?: 'any' | 'all'; // Default: 'any'
  redirectUrl?: string; // Default: '/403'
}

canActivate: [authGuard, createGroupsGuard({ groups: ['admin', 'superuser'] })];

Group utilities

import { hasGroup, hasAnyGroups, hasAllGroups } from '@presencelearning/auth';

hasGroup(user, 'admin');
hasAnyGroups(user, ['admin', 'superuser']);
hasAllGroups(user, ['editor', 'publisher']);

Token utilities

import {
  parseToken,
  isTokenExpired,
  validateToken,
  getTokenExpiry,
  getTokenExpiryMs,
} from '@presencelearning/auth';

parseToken(token); // → TokenClaims | null
isTokenExpired(token); // → boolean
validateToken(token); // → { valid: boolean; claims?: TokenClaims; error?: string }
getTokenExpiry(token); // → number | null (seconds since epoch)
getTokenExpiryMs(token); // → number | null (milliseconds since epoch)

Storage

SSR-safe wrappers for localStorage and sessionStorage with JSON helpers.

import { localStorage, sessionStorage } from '@presencelearning/auth';

localStorage.setItem('key', 'value');
localStorage.setJSON('key', { foo: 'bar' });
localStorage.getJSON<{ foo: string }>('key'); // → { foo: 'bar' } | null