Flow: Authentication and Identity Propagation This flow separates the external user's credential from the identity of each internal workload. Status: user JWT validation and workload tokens are Implemented/Partially implemented ; full request-bound subject assertions are Planned .
authentication · user, workload, subject assertion 01 / 07 ← →
The user signs in with Keycloak and sends an OIDC token to the gateway. The gateway validates it against JWKS, obtains its own audience-bound workload token, and sends separate subject and actor context. The service verifies workload caller and subject-asserter authority before authorization. OIDC + PKCE user access token HTTPS + bearer JWKS validate destination token workload JWT + subject / actor verified principal context User browser · application Keycloak identity + token issuer IMPLEMENTED Gateway validate · normalize PARTIAL Destination service caller + subject asserter PARTIAL Authorization follows identity is not permission COMPOSITE TARGET
01 User signs in The user authenticates with Keycloak using OIDC authorization code with PKCE. The platform services never receive the password.
02 Identity Provider issues the user token The signed JWT names the user and carries identity context such as organization and coarse roles. Those claims authenticate; they are not a resource grant.
03 Request reaches the gateway The client presents the bearer token on HTTPS. The gateway matches the exact operation and selects required, optional, or public authentication behavior.
04 Gateway validates the external credential The gateway pins the algorithm and validates signature, issuer, audience, time claims, and required identity claims against cached JWKS. A present but invalid token always fails.
05 Gateway obtains a destination credential For the selected upstream, the gateway uses its own Keycloak service identity to obtain or reuse a short-lived token addressed to that destination service.
06 Identity context is propagated The gateway sends the destination-bound workload credential plus normalized subject, actor, organization, delegation, operation, and decision context. Client-supplied internal context is removed.
07 Service verifies caller and subject authority The service verifies the workload token audience and caller allowlist, then accepts end-user context only if that workload is an approved subject asserter. Failure is 401/403 with no alternate trust path.
Application and agent credentials
Machine clients use their own principal and scopes rather than borrowing a human password. Agent execution uses RFC 8693 token exchange: sub remains the user, act.sub identifies the agent, and the service workloads remain separately authenticated. See Agent Delegation .
Failure and recovery
Unknown signing key triggers a bounded JWKS refresh; it does not bypass validation.
A wrong issuer, audience, caller, or subject asserter fails immediately.
Identity-provider outage may be masked only by still-valid cached keys/tokens. New token minting eventually fails closed.
Request/trace IDs, principal type, caller workload, audience, result, and failure class are emitted without logging the credential.
See Security Architecture for claim ownership and Authorization Decision for what happens after identity is established.