Skip to content

ADR 0002: Keycloak OIDC Authentication

Status

Accepted

Context

The platform requires a secure user login system. It must support multiple service components, enforce role segregation (viewer, editor, admin), support single sign-on (SSO), and prevent storing static credentials inside application databases.

Decision

We implement OpenID Connect (OIDC) authentication backed by Keycloak as the Identity Provider (IdP). * The Angular Client requests authorization code flows with PKCE. * Keycloak issues cryptographically signed JWT tokens. * The API Proxy Server verifies incoming JWT tokens statelessly using public signing keys fetched from Keycloak's JWKS certificates endpoint (RS256 signature verification). * Roles are stored as client roles within JWT access tokens and parsed by the API Gateway to restrict write handlers.

Consequences

  • Pros: Stateless API design (no sessions database on the Gateway); industry-standard protocol (OIDC/OAuth 2.0); credentials are managed exclusively by Keycloak.
  • Cons: Introduces dependency on Keycloak and PostgreSQL availability; tokens must be renewed frequently.