ADR-073: Security and Multi-Tenancy Model

Category: architecture Provenance: human

Decision

Adopt a "Realm-as-Tenant" security model where the Operator has no privileged access to namespaces by default. Access is strictly opt-in: The Operator gains permissions within a namespace only when a Helm chart (Realm or Client) instantiates a RoleBinding for the Operator's ServiceAccount. Key components: 1. Operator has minimal global privileges (ClusterRoleBinding only for CRD metadata watch). 2. Namespace access is granted dynamically via RoleBindings created by the Realm/Client Helm charts. 3. Cross-namespace Client creation is authorized purely via clientAuthorizationGrants allowlists in the Realm CR, not by sharing secrets or tokens.

Rationale

This model enforces the Principle of Least Privilege. The Operator cannot read Secrets in a namespace unless explicitly authorized by that namespace's owner (via installing the Chart). Benefits: - Security: Compromise of the Operator does not automatically grant access to all secrets in the cluster, only those in "opt-in" namespaces. - Scalability: Decouples the Operator's permission set from the cluster size; no massive ClusterRole updates needed. - Maintainability: Permissions are managed declaratively alongside the resources (Realms/Clients) in GitOps. - Multi-Tenancy: Clear boundary where a Namespace equates to a Tenant (or part of one), managing its own access grants.

Agent Instructions

When explaining security, always emphasize that the Operator is not omnipotent. It relies on the "Realm-as-Tenant" pattern. Do not suggest manually creating ClusterRoleBindings for the operator. Always direct users to use the Helm charts which handle the RBAC wiring automatically. When debugging "Permission Denied" errors for the operator, check for the existence of the keycloak-operator-access RoleBinding in the target namespace.

Rejected Alternatives

Global Operator Omnipotence (ClusterAdmin)

Violates least privilege. Gives the operator access to all Secrets in the cluster, which is a security risk.

Token-based Authentication for Clients

Requires secret exchange and management, which is complex and not GitOps-friendly.