Skip to content

Authentication Flow

PSI supports multiple authentication methods via an adapter pattern. Google Sign-In (via Firebase Auth) is the default for most silos, with full OIDC Single Sign-On support for partner identity providers.

Supported Providers

Provider key Partner / Name OIDC Mode Silos
google Google Sign-In (Firebase Auth) — Default for silos not listed below
zdfProd ZDFspaces (ZDF production) fragment zdf
zdfInt ZDF Internal fragment zdf
kika KiKA fragment kika
cbc / cbcInt CBC / CBC Integration (Azure AD B2C) fragment cbc, cbcInt
rc / rcInt Radio-Canada / Radio-Canada Internal (Azure AD B2C) fragment rc, rcInt
rtbf RTBF Login fragment rtbf
KroNcrvNpoIdTest KRO-NCRV / NPO ID code kro-ncrv
srgInt (+ per-BU srgRts/Srf/Rsi/Rtr/Swi) SRG SSR Account code srg
eo EO ("Inloggen met EO") code eo
auth0 / stubOidc Test-only providers code / fragment test

Note: Radio-Canada uses fragment mode (not code). KRO-NCRV/NPO and SRG use code mode. This differs from older documentation which reversed these.

SSO Authentication Flow

When a user logs in via an SSO provider, the following sequence occurs:

sequenceDiagram
    participant User
    participant Frontend as PSI Frontend
    participant IdP as OIDC Provider
    participant Backend as PSI Backend
    participant FBAuth as Firebase Auth

    User->>Frontend: Click login, select SSO provider
    Frontend->>IdP: Authorization request<br/>(client_id, redirect_uri, scope, response_type)
    IdP->>User: Authentication prompt
    User->>IdP: Provide credentials
    IdP->>Frontend: Redirect with ID token<br/>(in URL fragment or via code exchange)
    Frontend->>Backend: POST /api/auth/convertToken (JWT)
    Backend->>IdP: Fetch JWKS from /.well-known/jwks.json
    Backend->>Backend: Verify JWT signature and claims
    Backend->>FBAuth: Create or update Firebase user
    Backend->>FBAuth: Generate custom login token
    Backend->>Frontend: Return custom login token
    Frontend->>FBAuth: Sign in with custom token
    FBAuth->>Frontend: Firebase session established
    Frontend->>Backend: Subsequent API requests<br/>(Firebase ID token in Authorization header)
    Backend->>Frontend: Response data
    Frontend->>User: Display content

OIDC Modes

PSI supports two OIDC response modes:

Fragment mode (recommended for most providers):

  • The IdP returns the ID token directly in the URL fragment (#id_token=...)
  • The frontend extracts the token from the URL
  • Used by: ZDF, CBC, Radio-Canada, RTBF, KiKA

Code mode:

  • The IdP returns an authorization code, which is exchanged server-side for tokens
  • Used by: KRO-NCRV/NPO, SRG, EO (and test providers)

Correction: radio-canada (RC/RC Internal) uses fragment mode; only NPO, SRG, and EO use code mode.

Registration Flow

For providers that support user registration:

sequenceDiagram
    participant User
    participant Frontend as PSI Frontend
    participant IdP as OIDC Provider
    participant Backend as PSI Backend
    participant FBAuth as Firebase Auth
    participant Email as Email Service

    User->>Frontend: Open registration page
    Frontend->>User: Display registration form
    User->>Frontend: Submit registration data
    Frontend->>IdP: Create user (email, password)
    IdP->>Email: Send verification email
    Email-->>User: Verification email with code
    User->>Frontend: Submit verification code
    Frontend->>IdP: Validate verification code
    IdP->>Frontend: Verification success, return tokens
    Frontend->>Backend: POST /api/auth/convertToken (JWT)
    Backend->>FBAuth: Create Firebase user (verified email)
    Backend->>Frontend: Return custom login token
    Frontend->>FBAuth: Sign in with custom token
    Frontend-->>User: Registration complete

Auth Architecture

Client Side

The client uses an AuthAdapter interface:

interface AuthAdapter {
    getCurrentUser(): User | null;
    getIdTokenAsync(): Promise<string>;
    signOutAsync(): Promise<void>;
    signInWithGoogleAsync(): Promise<void>;
    signInWithTokenAsync(token: string): Promise<void>;
    onAuthStateChanged(callback): Unsubscribe;
}

The default implementation (FirebaseAuthAdapter) wraps the Firebase Auth SDK.

Server Side

The server uses a layered auth architecture built on better-auth (server/auth/):

  1. Database adapter -- firebaseAuthAdapter (Firebase Authentication, default via AUTH_ADAPTER=firebase) or better-auth's bundled mongodbAdapter (AUTH_ADAPTER=mongodb)
  2. firebase plugin (server/auth/plugins/firebase.ts) -- issues Firebase custom tokens and verifies Firebase ID tokens from Authorization headers
  3. genericOidc plugin (server/auth/plugins/generic-oidc/index.ts) -- verifies JWTs from any OIDC provider via JWKS, with provider-specific helpers for Azure AD B2C (azure-ad-b2c.ts) and CBC/RC (cbc-rc.ts)

Admin Roles

Admin roles are stored in Firebase RTDB at:

silo/{siloKey}/module/admin/userRoles/{email}

Roles include Owner. Admin authorization is checked before executing any adminFunctions in a server module.

Configuration

Adding a new SSO provider

  1. Define the provider in client/util/loginproviders.ts
  2. Register the OIDC config (issuer, JWKS endpoint) in server/auth/config.ts (genericOidcConfig)
  3. Configure Firebase permissions for custom token creation

JWKS consumption happens in the genericOidc plugin (server/auth/plugins/generic-oidc/) via remote JWK sets; the stub OIDC server (server/auth/stub-oidc.ts) serves /.well-known/jwks.json for testing.

See the SSO Integration Guide in psi-product for step-by-step instructions.