Hostzero-GmbH/keycloak-operator

Highlights

This release introduces the KeycloakRequiredAction CRD for managing realm required action providers, adds human-friendly alias-based authentication flow binding overrides for KeycloakClient, and extends KeycloakIdentityProvider with secret references for sensitive configuration values.

New Features

KeycloakRequiredAction CRD

New custom resource to manage Keycloak required action providers (password update, OTP configuration, email verification, terms and conditions, etc.) through dedicated Admin API endpoints. Unlike requiredActions inside KeycloakRealm.spec.definition which only apply on initial realm import, KeycloakRequiredAction resources are reconciled continuously and can be added, modified, or removed after realm creation.

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRequiredAction
metadata:
  name: terms-and-conditions
  namespace: keycloak
spec:
  realmRef:
    name: my-realm
  definition:
    alias: TERMS_AND_CONDITIONS
    name: "Terms and Conditions"
    providerId: TERMS_AND_CONDITIONS
    enabled: true
    defaultAction: true
    priority: 20

• References either a namespaced KeycloakRealm (via realmRef) or a ClusterKeycloakRealm (via clusterRealmRef).
• Definition follows Keycloak's RequiredActionProviderRepresentation with fields: alias, name, providerId, enabled, defaultAction, priority, and config.
• On deletion, the required action is removed from Keycloak unless the keycloak.hostzero.com/preserve-resource annotation is set.
• Short name: kcra.

See the KeycloakRequiredAction Documentation for full details.

Authentication Flow Binding Overrides by Alias (KeycloakClient)

KeycloakClient resources now support referencing authentication flows by their human-readable alias instead of Keycloak-generated UUIDs when configuring authenticationFlowBindingOverrides. This makes manifests portable across environments where flow UUIDs differ.

Two new keys are recognized inside spec.definition.authenticationFlowBindingOverrides:

• browserFlowAlias -- resolved to the flow UUID and stored as browser
• directGrantFlowAlias -- resolved to the flow UUID and stored as direct_grant

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakClient
metadata:
  name: my-app
spec:
  realmRef:
    name: my-realm
  definition:
    clientId: my-app
    enabled: true
    publicClient: true
    standardFlowEnabled: true
    authenticationFlowBindingOverrides:
      browserFlowAlias: "my-custom-browser-flow"
      directGrantFlowAlias: "my-custom-direct-grant"

The operator resolves aliases to UUIDs at reconciliation time. If both an alias key and the corresponding UUID key are present, the alias takes precedence. If no matching flow is found, reconciliation fails with status reason FlowAliasResolutionFailed.

The existing UUID-based approach (browser / direct_grant keys) continues to work unchanged.

See the KeycloakClient Documentation for full details.

Identity Provider Config from Secret (configSecretRef)

KeycloakIdentityProvider resources can now reference a Kubernetes Secret for sensitive configuration values (e.g. clientId, clientSecret) instead of embedding them in plaintext in spec.definition.config.

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakIdentityProvider
metadata:
  name: corporate-sso
spec:
  realmRef:
    name: my-realm
  configSecretRef:
    name: corporate-sso-credentials
  definition:
    alias: corporate-sso
    providerId: oidc
    enabled: true
    config:
      authorizationUrl: https://sso.corp.example.com/auth
      tokenUrl: https://sso.corp.example.com/token
      defaultScope: openid profile email

• All entries from the referenced Secret's data are merged into definition.config before syncing to Keycloak.
• Secret values take precedence over values specified inline in definition.config.
• When the Secret changes, the operator automatically re-reconciles the identity provider to pick up the new values.

See the KeycloakIdentityProvider Documentation for full details.

Improvements

Dependency Updates

• k8s.io/api, k8s.io/apimachinery, k8s.io/client-go from 0.35.2 to 0.35.3
• codecov/codecov-action from 5 to 6
• azure/setup-helm from 4 to 5
• actions/configure-pages from 5 to 6
• actions/deploy-pages from 4 to 5

Breaking Changes

None.

Bug Fixes

None.

Upgrade Guide

Helm Upgrade

helm upgrade keycloak-operator oci://ghcr.io/hostzero-gmbh/charts/keycloak-operator \
  --namespace keycloak-operator \
  --version 0.6.0

What's Changed

• chore(deps): bump k8s.io/client-go from 0.35.2 to 0.35.3 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/35
• feat: add KeycloakRequiredAction CRD #33 by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/38
• feat: support authentication flow binding overrides by alias by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/41
• chore(deps): bump actions/configure-pages from 5 to 6 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/42
• chore(deps): bump actions/deploy-pages from 4 to 5 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/43
• chore(deps): bump azure/setup-helm from 4 to 5 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/44
• chore(deps): bump codecov/codecov-action from 5 to 6 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/45
• Allow secret ref for KeycloakIdentityProvider. Closes #46 by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/47

Full Changelog: https://github.com/Hostzero-GmbH/keycloak-operator/compare/v0.5.0...v0.6.0