KeycloakOrganization

Identifier field: Set the organization name in the spec.name field. It is required and immutable once set. A name inside spec.definition is tolerated only when it matches spec.name; a conflicting value is rejected.

A KeycloakOrganization represents an organization within a Keycloak realm.

Note: Organizations require Keycloak 26.0.0 or later. Attempting to use this resource with earlier Keycloak versions will result in an error.

Specification

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakOrganization
metadata:
  name: acme-corp
spec:
  # One of realmRef or clusterRealmRef must be specified
  realmRef:
    name: my-realm
  
  # Required: Organization definition (Keycloak OrganizationRepresentation)
  name: ACME Corporation
  definition:
    alias: acme
    description: ACME Corp organization
    enabled: true
    domains:
      - name: acme.com
        verified: true
    attributes:
      industry:
        - Technology

Status

status:
  ready: true
  status: "Ready"
  organizationID: "12345678-1234-1234-1234-123456789abc"
  message: "Organization synchronized successfully"
  resourcePath: "/admin/realms/my-realm/organizations/12345678-..."
  instance:
    instanceRef: my-keycloak
  realm:
    realmRef: my-realm
  conditions:
    - type: Ready
      status: "True"
      reason: Synchronized

Examples

Basic Organization

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakOrganization
metadata:
  name: my-org
spec:
  realmRef:
    name: my-realm
  name: My Organization
  definition:
    enabled: true

Organization with Domains

Organizations can be associated with email domains. Users with matching email domains can be automatically associated with the organization.

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakOrganization
metadata:
  name: example-org
spec:
  realmRef:
    name: my-realm
  name: Example Organization
  definition:
    alias: example
    description: An example organization with verified domains
    enabled: true
    domains:
      - name: example.com
        verified: true
      - name: example.org
        verified: false

Organization with Custom Attributes

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakOrganization
metadata:
  name: enterprise-org
spec:
  realmRef:
    name: my-realm
  name: Enterprise Organization
  definition:
    alias: enterprise
    enabled: true
    attributes:
      tier:
        - enterprise
      maxUsers:
        - "1000"
      supportLevel:
        - premium

Organization with Cluster-Scoped Realm

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakOrganization
metadata:
  name: global-org
spec:
  clusterRealmRef:
    name: shared-realm
  name: Global Organization
  definition:
    enabled: true

Definition Properties

Common properties from Keycloak OrganizationRepresentation:

Domain Properties

Short Names

kubectl get kcorg

Requirements

• Keycloak 26.0.0+: Organizations are a feature introduced in Keycloak 26. The operator will report an error if you try to create an organization on an older Keycloak version.
• Organizations must be enabled: The organization feature must be enabled in the realm settings.

Reconciliation

Reconciliation is idempotent. On each periodic resync the operator fetches the current organization from Keycloak and compares it against the spec; the update PUT is skipped when they already match, so an unchanged organization does not generate redundant writes or log noise. domains[].verified is set by Keycloak on read and is ignored in the comparison, so leaving it unset (or out of sync with the server) does not trigger a perpetual update loop.

Notes

• Organizations are immutable by ID - once created, the id field cannot be changed
• The alias is used in URLs and should be URL-safe
• Verified domains can be used for automatic user association based on email
• Use attributes for custom metadata and configuration