Hostzero-GmbH/keycloak-operator

This release unifies instance authentication under a new spec.auth block, adds TLS configuration for custom CAs, introduces declarative IdP token-exchange permissions, and implements roleRef resolution in KeycloakRoleMapping. Documentation and e2e coverage for the preserve-resource deletion annotation is also expanded.

Breaking changes

KeycloakInstance / ClusterKeycloakInstance auth shape (spec.auth)

The top-level spec.credentials and spec.client fields are removed. Authentication is now configured via a single spec.auth block that selects exactly one of passwordGrant or clientCredentials. Both grants source secret material from Kubernetes Secrets; inline username / clientId remain allowed, but inline client.secret is gone.

Manifests using the old shape are rejected by the admission webhook and must be migrated before upgrading.

Migration (password grant)

# Before
spec:
  credentials:
    secretRef:
      name: keycloak-admin

# After
spec:
  auth:
    passwordGrant:
      secretRef:
        name: keycloak-admin

Migration (client credentials)

# Before
spec:
  credentials:
    secretRef:
      name: dummy-unused-admin   # was required, ignored at runtime
  client:
    id: keycloak-operator
    secret: my-client-secret     # inline string in the CR

# After
spec:
  auth:
    clientCredentials:
      secretRef:
        name: keycloak-operator-client

Companion Secret (default keys: client-id / client-secret):

kubectl create secret generic keycloak-operator-client \
  --from-literal=client-id=keycloak-operator \
  --from-literal=client-secret=my-client-secret

For ClusterKeycloakInstance, the same rewrite applies; secretRef.namespace remains required (cluster-scoped resource).

This change also drops the long-standing requirement to ship a dummy admin user/password Secret when authenticating via OAuth2 client credentials.

See the full migration guide in the KeycloakInstance docs. (#83)

Highlights

• spec.auth with secret-backed credentials — KeycloakInstance and ClusterKeycloakInstance now use a unified spec.auth block (passwordGrant or clientCredentials) with all sensitive material in Kubernetes Secrets. CEL validation enforces exactly one grant type. (#83)
• spec.tls for custom CA bundles — verify the Keycloak HTTPS endpoint against a PEM bundle from a Secret or ConfigMap, or set insecureSkipVerify for dev/test clusters. The operator reloads the HTTP client when TLS settings change. (#83)
• Declarative IdP token-exchange permission — optional spec.tokenExchange.allowedClients on KeycloakIdentityProvider wires Keycloak fine-grained authz so only the listed clients may perform RFC 8693 Token Exchange against the IdP as subject_issuer. Fully opt-in: omitting the field leaves Keycloak permissions untouched; an empty list explicitly denies all. Soft-waits when referenced clients do not yet exist. (#87)
• KeycloakRoleMapping roleRef resolution — mappings can reference a KeycloakRole CR by name; the operator reads status.roleName, transitively follows the role's clientRef, and supports cross-namespace refs on subject, role, and client. (#85)

Upgrade Guide

1. Migrate instance manifests (required)

Update every KeycloakInstance and ClusterKeycloakInstance to the new spec.auth shape before or immediately after upgrading the operator. See Breaking changes above.

Recommended order:

1. Create any new client-credentials Secrets (move inline client.secret out of the CR).
2. Rewrite manifests to spec.auth.
3. Apply manifest changes.
4. Upgrade the operator Helm release.

2. Helm upgrade

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

Full Changelog: https://github.com/Hostzero-GmbH/keycloak-operator/compare/v0.8.0...v0.9.0

What's Changed

• feat(api)!: spec.auth with secret-backed credentials + spec.tls (CA / insecureSkipVerify) by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/83
• feat(controller): implement role reference resolution in KeycloakRoleMapping by @luxass in https://github.com/Hostzero-GmbH/keycloak-operator/pull/85
• Improved documentation on annotation for preserving keycloak resources when a CR is deleted from kubernetes. Added extensive e2e tests for all resource cases by @simepavlic in https://github.com/Hostzero-GmbH/keycloak-operator/pull/86
• feat(idp): declarative token-exchange permission via spec.tokenExchange by @simepavlic in https://github.com/Hostzero-GmbH/keycloak-operator/pull/87

Full Changelog: https://github.com/Hostzero-GmbH/keycloak-operator/compare/v0.8.0...v0.9.0

What's Changed

• feat(controller): implement role reference resolution in KeycloakRole… by @luxass in https://github.com/Hostzero-GmbH/keycloak-operator/pull/85
• Annotation for preserving keycloak resources docs and testing by @simepavlic in https://github.com/Hostzero-GmbH/keycloak-operator/pull/86
• feat(api)!: spec.auth with secret-backed credentials + spec.tls (CA / insecureSkipVerify) by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/83
• feat(idp): declarative token-exchange permission (rebased) by @simepavlic in https://github.com/Hostzero-GmbH/keycloak-operator/pull/87
• chore(deps): bump actions/upload-artifact from 5 to 7 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/89

New Contributors

• @luxass made their first contribution in https://github.com/Hostzero-GmbH/keycloak-operator/pull/85
• @simepavlic made their first contribution in https://github.com/Hostzero-GmbH/keycloak-operator/pull/86

Full Changelog: https://github.com/Hostzero-GmbH/keycloak-operator/compare/v0.8.0...v0.9.0