Skip to main content
Version: 2.0-rc2

ADR 005: Tool for Keycloak configuration

Date: 2025-09-04

Status: Accepted

Decision Makers: @cr0ssing @luckey @DerLinne

Context​

In our Kubernetes-based environment, we require a secure, reliable, and maintainable mechanism for managing KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. realm configurations across environments. The goal is to automate and declaratively manage realm definitions (clients, users, roles, etc.) while ensuring GitOps compatibility, idempotent application, and cloud-native integration.

Multiple approaches for realm management exist, including:

Declarative tools (e.g., keycloak-config-cli, KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. Operator)

Imperative scripting (e.g., curl-based usage of the KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. Admin API)

Static import at container startup

A thorough technical and community risk assessment was performed, focusing on factors such as maintainability, documentation, CI/CD integration, community support, and project activity. The tool keycloak-config-cli emerged as the most suitable choice for our use case.

Checked Architecture Principles​

  • [full] – Model-centric data flow
  • [full] – Distributed architecture with unified user experience
  • [full] – Modular design
  • [full] – Integration capability through defined interfaces
  • [full] – Open source as the default
  • [full] – Cloud-native architecture
  • [full] – Prefer standard solutions over custom development
  • [full] – Self-contained deployment
  • [full] – Technological consistency to ensure maintainability
  • [partial] – Multi-tenancy
    • While the tool supports realm-level separation, it does not offer dynamic realm deletion or automated multi-tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. lifecycle management.
  • [full] – Security by design

Decision​

We will use keycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs.-config-cli to manage KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. realm configurations declaratively within our Kubernetes infrastructure.

Reasons:​

  • Declarative & Idempotent: Supports YAML/JSON configs, safe to reapply without duplication.
  • GitOps-Compatible: Works well in CI/CD, Helm, and ArgoCD environments.
  • Kubernetes-Native: Runs as a Job, InitContainer, or sidecar.
  • Well-Maintained: Active community, fast issue resolution (median 19h), recent commits.
  • Low maintenance risk: License (Apache 2.0), code review, and CI pipelines are in place.

Despite lacking native realm deletion support, this can be addressed using scripting or operator integration where necessary. The trade-off is acceptable given the operational simplicity and stability of the tool.

Consequences​

  • CIVITAS/CORE Infrastructure: Integration of keycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs.-config-cli into CI/CD pipelines, Helm charts, and GitOps workflows for automated KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. configuration.
  • Security & Auditing: Changes to realm configurations are tracked via Git, improving auditability.
  • Onboarding & Developer Experience: Developers can model realm definitions clearly using versioned, declarative files.
  • Limitations: Realm deletions and certain advanced KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. features may require supplemental tooling.

Alternatives​

  • KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. Operator (CRDs): Discarded due to increased operational complexity, stability concerns, and limited support for advanced KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. features.
  • Admin REST API via curl: Discarded for being imperative, harder to maintain, and lacking reconciliation logic.
  • Startup --import-realm flag: Not suitable due to being non-idempotent and only effective on initial startup of a clean database.

See also​