Keycloak Server Setup

Keycloak (via the codecentric keycloakx chart) is an open-source identity and access management server: OIDC/SAML login, realms, users, and identity provider brokering.

Why it's in KubeAid

KubeAid uses Keycloak as the OIDC provider for cluster access (kubectl oidc-login, group-based RBAC) and for other applications in the stack that need SSO (e.g. Harbor's OIDC login). It depends on a Postgres instance — see Migrating Zalando PGSQL to CNPG Postgres for the current recommended backing database.

Welcome to the Keycloak Helm Chart & Server Setup Documentation.

Table of Contents (Index)

• 1. Quick Start: Admin Password Generation
• 2. Identity Provider (IdP) Integrations
  • Google IdP Setup
  • Azure AD IdP Setup
  • Keycloak-to-Keycloak IdP Brokering
  • External IdP Group Mappers
• 3. Kubernetes Client & Cluster Integration
  • Install Krew & oidc-login
  • Setup Kubernetes Client in Keycloak
  • Setup Client Side (kubectl oidc-login & kubeconfig)
  • Keycloak Group-based Cluster RBAC
• 4. Realm, User & Authentication Management
  • Basic Keycloak Setup
  • User Administration
  • Default IdP Login Redirector
  • Client Specific Authentication Flow
  • Enabling & Forcing YubiKey (WebAuthn) 2FA
  • SMTP Email Configuration
• 5. Customization & Extensions
  • Custom Login Page Theme
  • Webhook Event Plugin
• 6. Operations, Disaster Recovery & Maintenance
  • Keycloak Upgrade Guide
  • Disaster Recovery
  • Migrating Zalando PGSQL to CNPG Postgres
  • Troubleshooting
  • Good Reads & References

---

1. Quick Start: Admin Password Generation

Generate Keycloak admin password (fallback user).

NOTE: Do not set the admin password from the WebUI; pass it via environment variable KEYCLOAK_PASSWORD.

openssl rand -base64 14 > ./keycloak_password

# Sealed Secret approach
kubectl create secret generic keycloak-admin -n keycloak --dry-run=client --from-file=KEYCLOAK_PASSWORD=./keycloak_password -o json > mysecret.json
kubeseal --controller-name sealed-secrets --controller-namespace system < mysecret.json > keycloak-admin.json

---

Documentation Modules Overview

Detailed step-by-step guides are organized into focused topics under the doc/ directory:

Section	Topic	Description
🔐 IdP Integrations	doc/idp-integrations.md	Integrating Google, Azure AD, and Keycloak-to-Keycloak identity brokering.
☸️ Kubernetes Integration	doc/kubernetes-integration.md	oidc-login setup, kubeconfig configuration, and group-based Cluster RBAC.
👥 Realm & User Management	doc/realm-user-management.md	Realm creation, user administration, YubiKey (WebAuthn) 2FA, and SMTP email setup.
🎨 Customization & Plugins	doc/customization-plugins.md	Custom UI login theme and Webhook event plugin configuration.
🛠️ Operations & Recovery	doc/operations-maintenance.md	Upgrade guide, realm export/import DR, Zalando-to-CNPG DB migration, & troubleshooting.