Skip to content

Auth Adapter Stack (Code Level)

C4 Level 4 detail of the PSI authentication system. Shows the better-auth setup, adapter selection, plugin system, and OIDC provider implementations.

Auth Setup and Adapter Hierarchy

classDiagram
    class createAuth {
        better-auth instance factory
        server/auth/index.ts
        AUTH_ADAPTER selection
    }

    class FirebaseAuthAdapter {
        adapterId: firebase-auth
        createAdapterFactory
        Firebase Authentication
    }

    class MongoAuthBackend {
        better-auth mongodbAdapter
        MongoDB database backend
    }

    class FirebasePlugin {
        id: firebase
        verifies Firebase ID tokens
        issues Firebase custom tokens
        sets set-firebase-token header
    }

    class GenericOidcPlugin {
        id: generic-oidc
        verifies OIDC JWTs via JWKS
        provider-specific helpers
    }

    createAuth --> FirebaseAuthAdapter : AUTH_ADAPTER=firebase (default)
    createAuth --> MongoAuthBackend : AUTH_ADAPTER=mongodb
    createAuth --> FirebasePlugin : registered when firebase
    createAuth --> GenericOidcPlugin : always registered

Note: There is no BetterAuthAdapter base class or firebaseIdToken plugin. The Firebase integration is the firebaseAuthAdapter plus the firebase plugin.

Token Verification Chain

sequenceDiagram
    participant Client as PSI Frontend
    participant Router as Hono Router
    participant Auth as Auth Handler (createAuth)
    participant Firebase as firebaseAuthAdapter (ADB)
    participant FBPlugin as firebase Plugin
    participant OIDCPlugin as genericOidc Plugin
    participant FBAdmin as Firebase Admin SDK
    participant IdP as OIDC Provider JWKS

    Client->>Router: Request with Authorization: Bearer <token>

    Router->>Auth: auth.handler (via /api/auth/*)

    Auth->>FBPlugin: Try verify as Firebase ID token
    FBPlugin->>FBAdmin: verifyIdToken(token)

    alt Firebase ID token valid
        FBAdmin-->>FBPlugin: DecodedToken {uid, email, ...}
        FBPlugin-->>Auth: Session established
    else Not a Firebase token
        FBAdmin-->>FBPlugin: Error: invalid token
        FBPlugin-->>Auth: Try next plugin

        Auth->>OIDCPlugin: Try verify as OIDC JWT
        OIDCPlugin->>IdP: Discover + fetch JWKS
        IdP-->>OIDCPlugin: JWKS with public keys
        OIDCPlugin->>OIDCPlugin: Verify JWT signature + claims (via jose)

        alt OIDC JWT valid
            OIDCPlugin-->>Auth: JwtPayload {sub, email, iss, ...}
        else Invalid JWT
            OIDCPlugin-->>Auth: Authentication failed
        end
    end

    Auth-->>Router: Session or error

SSO Token Conversion (Full Detail)

sequenceDiagram
    participant User
    participant Frontend as PSI Frontend
    participant IdP as OIDC Provider
    participant Backend as PSI Backend
    participant AuthAdapter as FirebaseAuthAdapter
    participant OIDC as genericOidc Plugin
    participant FBAuth as Firebase Admin
    participant JWKS as Provider JWKS Endpoint

    User->>Frontend: Click SSO login button
    Frontend->>IdP: Redirect to authorization endpoint
    Note over IdP: client_id, redirect_uri,<br/>scope=openid email profile,<br/>response_type=id_token (fragment)<br/>or response_type=code (code mode)

    IdP->>User: Login form
    User->>IdP: Credentials
    IdP->>Frontend: Redirect with id_token (fragment) or authorization code

    alt Code mode (NPO, SRG, EO) or code exchange
        Frontend->>Backend: POST /api/sso/exchange-code {code}
        Backend->>IdP: Exchange code for tokens (OIDC discovery)
        IdP-->>Backend: {id_token, access_token}
    else Fragment mode (ZDF, CBC, Radio-Canada, RTBF, KiKA)
        Frontend->>Backend: POST /api/auth/convertToken (JWT)
    end

    Backend->>AuthAdapter: convertToken(jwt)
    AuthAdapter->>OIDC: Verify JWT
    OIDC->>JWKS: Fetch public keys
    JWKS-->>OIDC: JWKS
    OIDC->>OIDC: Verify signature, iss, aud, exp

    AuthAdapter->>FBAuth: getOrCreateUser(email, displayName)
    FBAuth-->>AuthAdapter: Firebase user record
    AuthAdapter->>FBAuth: createCustomToken(uid)
    FBAuth-->>AuthAdapter: Custom token

    Backend-->>Frontend: {loginToken: customToken}

    Frontend->>FBAuth: signInWithCustomToken(loginToken)
    FBAuth-->>Frontend: Firebase session (ID token)

    Note over Frontend: All subsequent API calls use<br/>Firebase ID token in Authorization header

OIDC Provider Configurations

graph LR
    subgraph "genericOidc Plugin"
        Verify[JWT Verification via JWKS]
    end

    subgraph "Provider Implementations"
        ZDF[ZDFspaces / ZDF Internal<br/>fragment]
        KIKA[KiKA<br/>fragment]
        CBC[CBC Azure AD B2C<br/>fragment]
        RC[Radio-Canada Azure AD B2C<br/>fragment]
        RTBF[RTBF Login<br/>fragment]
        NPO[KRO-NCRV / NPO ID<br/>code]
        SRG[SRG SSR Account<br/>code + per-BU clients]
        EO[EO<br/>code]
    end

    subgraph "Provider Helpers"
        AzureHelper[azure-ad-b2c.ts<br/>B2C tenant config]
        CBCHelper[cbc-rc.ts<br/>CBC/RC-specific config]
    end

    Verify --> ZDF
    Verify --> KIKA
    Verify --> CBC
    Verify --> RC
    Verify --> RTBF
    Verify --> NPO
    Verify --> SRG
    Verify --> EO

    CBC --> AzureHelper
    RC --> AzureHelper
    AzureHelper --> CBCHelper

The full provider list is defined in client/util/loginproviders.ts (client-side flow) and mirrored in server/auth/config.ts (genericOidcConfig). The genericOidc plugin consumes remote JWKS for JWT verification; the stub OIDC server (server/auth/stub-oidc.ts, test-only) serves /.well-known/jwks.json and /jwks.

Client-Side Auth

classDiagram
    class ClientAuthAdapter {
        <<interface>>
        +getCurrentUser() User | null
        +getIdTokenAsync() Promise~string~
        +signOutAsync() Promise~void~
        +signInWithGoogleAsync() Promise~void~
        +signInWithTokenAsync(token: string) Promise~void~
        +onAuthStateChanged(callback) Unsubscribe
    }

    class FirebaseAuthAdapter {
        -auth: FirebaseAuth
        +getCurrentUser()
        +getIdTokenAsync()
        +signOutAsync()
        +signInWithGoogleAsync()
        +signInWithTokenAsync(token)
        +onAuthStateChanged(callback)
    }

    class NoopAdapter {
        +getCurrentUser() null
        +getIdTokenAsync() ""
        +signOutAsync()
        +signInWithGoogleAsync()
        +signInWithTokenAsync()
        +onAuthStateChanged()
    }

    ClientAuthAdapter <|.. FirebaseAuthAdapter : default
    ClientAuthAdapter <|.. NoopAdapter : testing

    note for FirebaseAuthAdapter "Wraps Firebase Auth SDK. Google popup sign-in\nand custom token sign-in (SSO)."

Google is the default login for silos using Firebase auth and not in silosWithoutGoogleLogin (rc, rcInt, rtbf, cbc, cbcInt, srg, kika, eo).

Admin Authorization

graph TD
    A[API Request] --> B{Is adminFunction?}
    B -->|No| C[Execute publicFunction]
    B -->|Yes| D[Check admin role]
    D --> E[Read: silo/siloKey/module/admin/userRoles/email]
    E --> F{Role exists?}
    F -->|Yes: Owner| G[Execute adminFunction]
    F -->|No| H[Return 403 Forbidden]

Further Reading