ADR 0005 Keycloak Auth

ADR-0005: Keycloak as identity provider

Status: Accepted Date: 2026-04-25 Decider: Maintainer

Context

FinCore needs OAuth2 / OIDC for:

• Machine-to-machine API access (adopter's services calling FinCore APIs)
• Human users (operators, compliance officers, admins) accessing the dashboard
• Service-to-service auth (modular monolith now, microservices later)
• Token issuance, validation, rotation, revocation
• Role-based access control with fine-grained permissions

Building auth from scratch is wrong by default - it's a category where you don't want to be clever or DIY. The choice is which off-the-shelf identity provider to bundle.

Options:

1. Keycloak - mature, OSS (Apache 2.0), huge feature set, self-hostable, Red Hat-backed
2. Auth0 / Okta - SaaS only, pricing per-MAU, vendor lock-in
3. AWS Cognito / GCP Identity Platform - cloud-vendor-locked
4. Hand-rolled OIDC - recipe for breach

For an OSS project that adopters self-host, options 2-3 are out (vendor lock conflicts with self-hosting). Option 4 is reckless. Option 1 is the answer.

Decision

Use Keycloak 26.6.1 as the bundled identity provider:

• Single realm fincore with pre-configured roles, scopes, clients
• Bundled in docker compose for sandbox / local dev
• Production deployments either run Keycloak HA cluster, or swap to external OIDC (any OIDC-compatible provider works - Auth0, Okta, AWS Cognito, GCP, internal Keycloak, Authelia, etc.)
• Spring Security OAuth2 Resource Server validates JWTs (no Keycloak adapter - pure standard OIDC)
• JWKS cached in Gateway for 10 minutes
• Keycloak admin password sealed in Vault, audited

Realm configuration delivered as Keycloak realm export JSON in deploy/keycloak/fincore-realm.json - versioned, auto-imported on Keycloak startup in dev.

Consequences

Positive

• Battery-included sandbox: docker compose up includes a working OIDC provider with seeded users
• Zero vendor lock-in for adopters: any OIDC provider works in production
• Mature feature set: MFA, social login, LDAP federation, fine-grained authz (Keycloak Authorization Services)
• Spring Security integration: well-trodden, every Spring tutorial covers it
• Self-hostable: aligns with our self-hosted OSS positioning
• Apache 2.0: compatible with our BSL - adopters can re-package our Keycloak setup freely

Negative

• Keycloak resource footprint: ~512 MB RAM minimum. For laptops this is fine; for tiny environments it's a constraint.
• Keycloak operational complexity: HA Keycloak (clustering, infinispan caches, DB) is non-trivial. Most adopters offload to external managed Keycloak or external OIDC.
• Configuration sprawl: Keycloak's realm config has many knobs. We standardize via the imported realm JSON.
• Major upgrades: Keycloak releases breaking changes. Pin version, test before upgrade.

Neutral

• Adopters who prefer Auth0/Okta/Cognito just point Spring's issuer-uri at their provider. No code change.

Alternatives considered

Auth0 / Okta as required dependency

• Rejected: hard SaaS lock-in violates self-hosting OSS goal
• Rejected: pricing surprises adopters

AWS Cognito / GCP Identity Platform

• Rejected: cloud lock-in
• Cognito's OIDC is non-standard in spots; harder to swap out

Spring Authorization Server (built-in)

• Considered: would remove Keycloak dependency
• Rejected: less feature complete (no admin UI, no MFA, no social, no LDAP)
• Reconsider in v2.x if Keycloak proves overkill - but probably not

Hand-rolled JWT issuance + validation

• Rejected: too easy to ship vulnerabilities
• Rejected: no admin UI, no user management UX

Ory Hydra + Kratos

• Considered: clean architecture, OSS
• Rejected: less mainstream than Keycloak, smaller community
• Maybe reconsider for v2.x

FusionAuth

• Considered: good UX, modern
• Rejected: dual licensing creates ambiguity for OSS adopters
• Less proven at fintech scale

Validation

• E2E test: bring up docker compose, get token via client_credentials, call /v1/accounts, assert 201
• Integration test: forged JWT (wrong signature) returns 401
• Integration test: expired JWT returns 401
• Integration test: missing scope returns 403
• Realm config import idempotent - reapply produces identical state

Related

• Architecture-Security - full auth flow
• deploy/keycloak/fincore-realm.json - realm config (delivered with v0.1)
• Spring Boot Actuator integration: JWT validation metrics published