Hostzero-GmbH/keycloak-operator

This release brings a new CRD for managing authentication flows independently of realms, fixes an issue with nested groups on Keycloak 23+, adds proper pagination to all list operations, and supports default/optional client scopes on KeycloakClient.

Highlights

• New KeycloakAuthenticationFlow CRD — manage Keycloak authentication flows independently of KeycloakRealm, allowing flow changes after the initial realm import. The controller translates the typed spec into the sequence of API calls Keycloak's procedural flow API requires (create flow, add executions, set requirements, reorder, apply authenticator configs). Includes RBAC, e2e tests, unit tests, and docs. (#32) (big thanks to @vgt-manuel-birrer for all the testing effort here!)
• defaultClientScopes / optionalClientScopes on KeycloakClient — Keycloak's client REST API ignores these fields in the request body. The operator now strips them before sending to Keycloak and reconciles the assignments via the per-client scope endpoints after create/update.

Bug fixes

• Nested group export and reconciliation on Keycloak 23+ — since Keycloak 23, GET /admin/realms/{realm}/groups returns groups with subGroupCount but an empty subGroups array; nested groups must be fetched via /groups/{id}/children. The exporter and group controller both assumed the legacy inline shape and silently dropped every nested group, and re-reconcile of a nested child kept calling CreateChildGroup, dropping the CR into CreateFailed with 409. The lookup is now strict and parent-scoped, role mappings are exported for subgroups too, and a real-Keycloak e2e test pins the behaviour.
• Offset-based pagination for list helpers — the Keycloak Admin API returns at most 100 results by default. Realms with more than 100 clients, users, groups, roles or organizations were silently truncated. A generic listAll[T] helper now pages through all results using first / max, and is wired through GetClients, GetUsers, GetGroups, GetRealmRoles and GetOrganizations. (thanks @cdm-arm)
• Namespaced realm lookup — fix getKeycloakClientRealmAndVersion for realms in non-default namespaces.
• Better handling of authentication flow updates — refactored to runtime.RawExtension handling and improved diff/update behaviour.

Build, CI & dependencies

• Go 1.26 in CI, with a corresponding golangci-lint upgrade.
• Bump k8s.io/api, k8s.io/apimachinery, k8s.io/client-go to v0.35.4.
• Bump softprops/action-gh-release to v3 and actions/upload-pages-artifact to v5.

Upgrade Guide

Helm Upgrade

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

New contributors

• @cdm-arm made their first contribution in fix: add offset-based pagination for list helpers.

Full changelog: https://github.com/hostzero/keycloak-operator/compare/v0.6.1...v0.7.0

What's Changed

• chore(deps): bump k8s.io/api from 0.35.3 to 0.35.4 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/58
• chore(deps): bump softprops/action-gh-release from 2 to 3 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/55
• chore(deps): bump actions/upload-pages-artifact from 4 to 5 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/54
• chore(deps): bump k8s.io/apimachinery from 0.35.3 to 0.35.4 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/57
• chore(deps): bump k8s.io/client-go from 0.35.3 to 0.35.4 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/56
• Fix nested group export and reconciliation on Keycloak 23+ by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/61
• fix: add offset-based pagination for list helpers by @cdm-arm in https://github.com/Hostzero-GmbH/keycloak-operator/pull/60
• feat: support defaultClientScopes and optionalClientScopes on KeycloakClient by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/52
• feat: add KeycloakAuthenticationFlow CRD #32 by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/39

New Contributors

• @cdm-arm made their first contribution in https://github.com/Hostzero-GmbH/keycloak-operator/pull/60

Full Changelog: https://github.com/Hostzero-GmbH/keycloak-operator/compare/v0.6.1...v0.7.0