Skip to content

Architecture

Service Flow

The CELINE Dashboards stack layers several components to deliver SSO-protected analytics services:

  1. The user's browser (or CLI) makes a request to a service URL.
  2. Caddy receives the request and calls oauth2-proxy via forward_auth to verify the session.
  3. If the session is valid, oauth2-proxy injects identity headers (X-Auth-Request-User, X-Auth-Request-Access-Token) and Caddy proxies the request to the target service.
  4. If no valid session exists, oauth2-proxy redirects the browser to Keycloak for OIDC login.
  5. On successful login, Keycloak issues tokens, oauth2-proxy creates a session cookie, and the user is redirected back.

Component Roles

Component Port (local) Purpose
Caddy 80 / 443 Reverse proxy, forward_auth, virtual hosting
oauth2-proxy internal OIDC session management, header injection
Keycloak 8080 Identity provider, realm management
Superset internal Analytics dashboards
Jupyter internal Notebook execution

Auth Chain

Request → Caddy
  → oauth2-proxy (forward_auth)
    → Keycloak (if no session)
  → inject headers
  → Superset / Jupyter
    → local SecurityManager / JWT authorizer

Identity Propagation

oauth2-proxy injects the following headers into upstream requests:

Header Content
X-Auth-Request-User Username from Keycloak
X-Auth-Request-Email Email from Keycloak
X-Auth-Request-Access-Token Keycloak access token (JWT)

Superset and Jupyter each consume these headers to establish the user session and enforce authorization locally. No direct Keycloak calls are made by the applications at request time.

Authorization is decided from the access token only, never from a groups header. The token carries two levels of authority: the realm role platform-admin (realm_access.roles), the only platform-wide grant, and each organisation's own groups (organization.<alias>.groups), valid only inside that organisation. There are no realm groups; a realm group still present in a token grants nothing. See authentication.md.

Multi-Host Setup

Services are exposed under *.celine.localhost subdomains for local development:

Subdomain Service
superset.celine.localhost Apache Superset
jupyter.celine.localhost Jupyter
sso.celine.localhost oauth2-proxy
keycloak.celine.localhost Keycloak

oauth2-proxy is configured with skip_jwt_bearer_tokens = true to allow service/CLI tokens to bypass the browser SSO flow.