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
BetterAuthAdapterbase class orfirebaseIdTokenplugin. The Firebase integration is thefirebaseAuthAdapterplus thefirebaseplugin.
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
- Authentication Flow -- C4 Level 3 sequence diagrams
- Adapter Pattern -- all adapter interfaces
- SSO Integration Guide (psi-product) -- adding new providers