Authentication & SSO

Every request to the DataFlow AI Platform is authenticated against a single Keycloak realm before it reaches any service. This page walks the full identity path — browser login, gateway JWT validation, identity-header propagation, downstream re-validation, token lifecycle, and the security hardening applied to each response.

Identity provider — Keycloak

The platform delegates all authentication to Keycloak 24, running as the OIDC / SSO identity provider. A single realm holds every client, role, group, and user.

Keycloak itself runs in the compose topology on host port 8180 (mapped to container 8080) and stores its data in a dedicated dataflow_keycloak database on the shared PostgreSQL instance.

Brute-force protection

The dataflow realm enables Keycloak's built-in brute-force detection. Repeated failed logins progressively slow down and then temporarily lock an account.

Active Directory federation

For production, Keycloak federates users from Polkomtel's corporate directory. The admin guide describes an LDAP user-federation provider pointed at ldaps://ad.polkomtel.internal:636 in READ_ONLY edit mode, with AD-group → Keycloak-role group mappers and periodic changed-user synchronisation. Users authenticate with their existing corporate credentials; their AD group membership determines their platform role.

OAuth2 clients

The realm defines two OAuth2 clients with deliberately different trust profiles — one public client for the browser SPA, one confidential client for backend service-to-service calls.

dataflow-app — the public SPA client

Because a single-page application cannot keep a secret, dataflow-app is a public client that relies on PKCE with the S256 challenge method (pkce.code.challenge.method: S256) to protect the authorization-code exchange. Its configuration:

• Redirect URIs include the localhost development ports (5173, 4173, 3000, 3006) and the production origin https://etl.exai.cloud/*.
• Web origins mirror the redirect URIs plus the + wildcard token.
• Default client scopes are web-origins, acr, profile, roles, and email.
• Scope mappings grant dataflow-app all six realm roles.

dataflow-api — the confidential service client

dataflow-api is a confidential client used for client-credentials (service-to-service) flows. Its secret ships as the placeholder REPLACE_IN_KEYCLOAK in the realm export and must be set in the Keycloak admin console. This is the same audience that downstream services require in the aud claim (see JWT validation).

The OIDC login flow

The frontend uses the keycloak-js adapter. On startup it constructs a singleton Keycloak instance (frontend/src/auth/keycloak.ts) from three environment variables:

Initialisation (getKeycloakInitOptions) uses onLoad: 'check-sso', a silent SSO check via /silent-check-sso.html, pkceMethod: 'S256', and checkLoginIframe: false.

Sequence diagram

 Browser                Keycloak (:8180)            API Gateway (:8085)
   │                          │                            │
   │  (1) load SPA from nginx :3006                          │
   │                          │                            │
   │  (2) check-sso / login redirect (PKCE S256)            │
   │─────────────────────────▶│                            │
   │                          │                            │
   │  (3) user authenticates (corporate AD credentials)      │
   │◀─────────────────────────│                            │
   │                          │                            │
   │  (4) redirect back to origin "/" with authorization code│
   │◀─────────────────────────│                            │
   │                          │                            │
   │  (5) keycloak-js exchanges code + PKCE verifier         │
   │─────────────────────────▶│                            │
   │  (6) access token + refresh token (JWT, RS256)         │
   │◀─────────────────────────│                            │
   │                          │                            │
   │  (7) buildProfileFromKeycloak() parses token claims     │
   │  (8) signalAuthReady() — first API requests unblocked   │
   │                          │                            │
   │  (9) GET /api/v1/...  Authorization: Bearer <JWT>       │
   │────────────────────────────────────────────────────────▶│
   │                          │                            │
   │                  (10) gateway validates JWT, injects   │
   │                       X-User-* headers, proxies on     │
   │◀────────────────────────────────────────────────────────│

What happens in the browser

1. AuthProvider.tsx runs keycloakInstance.init(...) inside a Promise.race guarded by a 15-second timeout (KEYCLOAK_INIT_TIMEOUT_MS — previously 4 s, raised to fix an SSO redirect loop).
2. On success, buildProfileFromKeycloak() parses the token into a KeycloakUserProfile: subject, name, email, realm_access.roles, and the workspace_id / workspace claim.
3. The Keycloak instance is exposed as window.__keycloak for diagnostics.
4. login() defaults the post-login redirect target to origin / — not the current URL — so users do not bounce back to /login. logout() redirects to /login.

Gating the first API requests

The axios client (frontend/src/api/client.ts) obtains the access token through a registered token accessor (registerTokenAccessor). A signalAuthReady() / waitForAuthReady promise gates the first requests until Keycloak initialisation finishes, preventing an unauthenticated first wave of calls.

JWT validation at the gateway

All client traffic enters through the API Gateway (reactive Spring Cloud Gateway, WebFlux) under /api/v1/**. The gateway is configured as an OAuth2 resource server and validates the bearer JWT on every request.

The gateway's SecurityConfig.kt disables CSRF, HTTP Basic, and form login, and wires a ReactiveKeycloakJwtConverter to translate Keycloak roles into Spring authorities.

What is checked

Audience enforcement is performed by JwtAuthenticator. The ReactiveKeycloakJwtConverter logs every accepted JWT at INFO (principal, subject, issuer, expiry, realm roles, granted authorities).

Public paths

A small set of paths bypass authentication entirely (permitAll): OPTIONS /**, /actuator/**, /actuator/health/**, /api/v1/health, and /health/**.

Identity-header propagation

After the JWT is validated, the gateway's AuthFilter — a GlobalFilter registered at order −90 — extracts the token claims and injects six X-User-* identity headers into the request forwarded downstream.

Public paths (/actuator, /api/v1/health, /health) bypass the filter. Non-JWT requests (for example cookie-only or unauthenticated requests) pass through without identity headers and are logged only at DEBUG.

JWKS re-validation in servlet services

The six downstream services are Spring MVC (servlet) applications. They do not blindly trust the gateway — they independently re-validate the same JWT, a defense-in-depth design.

Each service's common/security/SecurityConfig is annotated @EnableWebSecurity and @EnableMethodSecurity(prePostEnabled = true), runs stateless sessions, and disables CSRF. As an OAuth2 resource server it decodes tokens with:

NimbusJwtDecoder.withJwkSetUri(
    // spring.security.oauth2.resourceserver.jwt.jwk-set-uri
)

A KeycloakJwtConverter maps the token's roles to authorities, so @PreAuthorize("hasAnyRole(...)") evaluates real Keycloak roles, not SCOPE_* claims.

After re-validation, a SecurityContextPopulatingInterceptor reads the gateway's X-User-* headers into a thread-local SecurityContextHolder. The SecurityContext data class exposes isAdmin, isEngineerOrAbove, and isAnalystOrAbove helpers. Thread-local cleanup is guaranteed three ways (FA-005):

1. The interceptor's afterCompletion callback.
2. A SecurityContextCleanupFilter wrapping every /api/* request in try/finally.
3. A SecurityContextTaskDecorator for @Async thread pools.

Token lifecycle & refresh

The access token is short-lived and refreshed silently in the background so the user is never interrupted by a re-login.

• Silent refresh — AuthProvider.scheduleTokenRefresh calls kc.updateToken to refresh the token 30 s before expiry. If the refresh fails, the session is cleared and isAuthenticated becomes false.
• Session timeout warning — a SessionTimeoutModal appears 60 s before expiry (reduced from 5 minutes, which had caused the modal to appear immediately after login). The "Extend session" action calls updateToken(-1) to force a refresh.
• 401 retry — the axios response interceptor implements a 401 → silent token refresh → retry original request flow, so a token that expired mid-flight is transparently renewed.
• Logout — clears the refresh and session timers, resets all React state, and calls keycloakInstance.logout.

Dev-mode fallback

For local development without a running Keycloak, the frontend ships a mock auth path in frontend/src/auth/devAuth.ts.

• When VITE_AUTH_MODE=dev or VITE_AUTH_ENABLED=false (only in the Vite dev server), a persona switcher offers four mock profiles — engineer, analyst, admin, steward — that are indistinguishable from real Keycloak profiles. The dev token accessor returns null.
• AuthProvider only falls back to dev mode when allowDevModeFallback is explicitly set. Otherwise a Keycloak init failure leaves the user unauthenticated — there is no implicit grant.

The gateway dev escape hatch

The backend has a parallel switch: dataflow.gateway.dev-permit-reads (default false). When true:

• The gateway permits all GET requests plus a few always-safe POSTs (copilot, ai, catalog/ask, search) without a JWT.
• Downstream SecurityConfig grants the anonymous user a broad set of roles.

Security hardening

Every response that leaves the gateway is hardened by a chain of per-route filters. The platform describes this posture as SOC 2 / OWASP-aligned.

Security headers

SecurityHeadersFilter runs at order HIGHEST_PRECEDENCE + 10 and writes headers in a beforeCommit hook (so they land before the response is committed).

TLS

The realm enforces sslRequired: external. The gateway emits the HSTS preload header above; the admin guide additionally requires Keycloak to be served over HTTPS on port 443 and database connections to use sslmode=verify-full.

CORS

CorsConfig registers a CorsWebFilter on /**. Allowed origins come from dataflow.cors.allowed-origins (default http://localhost:5173, http://localhost:3000, https://app.dataflow.polkomtel.pl, https://staging.dataflow.polkomtel.pl). Methods are GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD, allowCredentials is true, and maxAge defaults to 3600 s. Exposed headers include the rate-limit headers, ETag, and Content-Disposition.

Rate limiting

RedisRateLimitFilter is a Redis sliding-window (sorted-set) limiter keyed rate_limit:{clientIp}:{endpoint}. The client IP is resolved from X-Forwarded-For, then X-User-Id, then the remote address, then anonymous.

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; an over-limit request returns HTTP 429 with Retry-After. The limiter is fail-closed by default (dataflow.gateway.rate-limit.fail-closed=true, FR-019): if Redis is unavailable the gateway returns HTTP 503 with X-RateLimit-Status: degraded rather than silently dropping protection, and a 30-second circuit breaker delays retrying Redis. Setting fail-closed=false is a dev-only fail-open opt-out.

Audit logging

AuditInterceptor intercepts POST, PUT, PATCH, and DELETE on /api/** (skipping health and actuator). It performs a dual write:

1. Structured JSON through the SLF4J logger com.polkomtel.dataflow.audit — level chosen by status (2xx → INFO, 4xx → WARN, otherwise ERROR) — for SIEM ingestion.
2. Asynchronous DB persistence via an optional AuditPersistence bean on a single daemon thread.

Each entry captures the event ID, request ID, action (CREATE / UPDATE / PARTIAL_UPDATE / DELETE), method, path, resource type and ID, status code, duration, actor (user ID / email / role / workspace from the X-User-* headers), remote address, success flag, category, and any error type and message. Audit logs are retained 365 days and exportable to SIEM; AuditLogController read access requires hasRole('ADMIN').

PII masking

PiiMaskingFilter (a Spring Cloud Gateway filter at order LOWEST_PRECEDENCE - 10) is the only filter that intercepts response bodies, and it is applied to every route. It recognises seven PII patterns:

Summary

Authorization — what an authenticated identity is actually allowed to do — is covered separately in RBAC & permissions.