Skip to main content

Keycloak

Purpose: For platform engineers, shows how to configure Keycloak realms, clients, OIDC settings, and RBAC Manager integration.

What Keycloak Does​

Keycloak provides enterprise SSO and OIDC/SAML authentication for the cluster. It federates identity from LDAP/Active Directory, manages users and groups, and issues OIDC tokens that Kubernetes uses for authentication. RBAC Manager converts Keycloak group memberships into Kubernetes RoleBindings, completing the access control chain.

How It's Deployed​

Keycloak is deployed via FluxCD from openCenter-gitops-base:

openCenter-gitops-base/applications/base/services/keycloak/
├── namespace.yaml
├── source.yaml
├── helmrelease.yaml
└── helm-values/
    └── hardened-values.yaml

Customer overlay:

applications/overlays/<cluster>/services/keycloak/
├── kustomization.yaml
└── override-values.yaml

Keycloak depends on:

  • cert-manager — TLS certificates for the Keycloak endpoint.
  • postgres-operator — PostgreSQL database for Keycloak's persistent state.

Both must be deployed before Keycloak.

Backup Durability Limitation

openCenter does not currently provide a Keycloak-specific durability workflow. Treat backup and restore of the backing PostgreSQL database as an operator responsibility and validate that restore path before relying on Keycloak recovery.

Key Configuration​

Realm Setup​

openCenter clusters use a dedicated realm (typically opencenter) for Kubernetes authentication. The realm is configured after deployment via the Keycloak admin console or realm export/import:

  1. Log in to https://keycloak.${CLUSTER_DOMAIN}/admin.
  2. Create a realm named opencenter.
  3. Configure identity providers (LDAP/AD federation) under the realm's Identity Providers section.

OIDC Client for Kubernetes​

Create an OIDC client that the Kubernetes API server uses for token validation:

Client ID:     kubernetes
Client Protocol: openid-connect
Access Type:   confidential
Valid Redirect URIs: https://<cluster-api>:6443/*

Map group memberships into the OIDC token by adding a "groups" mapper:

  1. Go to the kubernetes client → Client Scopes → Dedicated scope.
  2. Add a mapper of type "Group Membership" with Token Claim Name groups.
  3. Disable "Full group path" to get flat group names.

Kubernetes API Server OIDC Flags​

The Kubernetes API server must be configured to trust Keycloak tokens. openCenter-cli sets these via Kubespray variables:

# Set by openCenter-cli in Kubespray inventory
kube_oidc_auth: true
kube_oidc_url: https://keycloak.${CLUSTER_DOMAIN}/realms/opencenter
kube_oidc_client_id: kubernetes
kube_oidc_username_claim: preferred_username
kube_oidc_groups_claim: groups

LDAP/AD Federation​

To federate users from Active Directory:

  1. In the Keycloak admin console, go to User Federation.
  2. Add an LDAP provider with your AD connection details (URL, bind DN, search base).
  3. Configure group mapping to sync AD groups into Keycloak groups.
  4. Set sync interval (e.g., every 60 minutes) for periodic user/group synchronization.

Integration with RBAC Manager​

Keycloak groups flow into Kubernetes RBAC via RBAC Manager. See the RBAC Manager doc for how RBACDefinition CRs map Keycloak groups to ClusterRoleBindings.

Verification​

# Check Keycloak pods
kubectl get pods -n keycloak

# Verify HelmRelease status
flux get helmreleases -n flux-system | grep keycloak

# Test OIDC discovery endpoint
curl -s https://keycloak.${CLUSTER_DOMAIN}/realms/opencenter/.well-known/openid-configuration | jq '.issuer'

# Verify Kubernetes OIDC integration
kubectl auth whoami  # Should show OIDC identity when using OIDC kubeconfig

Troubleshooting​

Keycloak pod CrashLoopBackOff: Check that the PostgreSQL database is running and the database credentials secret exists. Verify with kubectl logs -n keycloak <pod>.

OIDC tokens rejected by API server: Confirm the kube_oidc_url matches the Keycloak realm URL exactly (including /realms/<realm>). Check API server logs for OIDC validation errors.

Common Customizations​

  • Custom themes: Mount a custom theme via a ConfigMap or PVC for branded login pages.
  • Session timeouts: Adjust SSO session idle and max lifespan in the realm settings.
  • MFA: Enable OTP or WebAuthn as required authentication actions in the realm.
  • Backup: Keycloak state lives in PostgreSQL, and durability remains operator-owned.
  • Resource limits: Adjust in override-values.yaml based on user count and authentication load.