KeycloakUser

Identifier field: Set the username in the spec.username field. Required for regular users and immutable once set; omit it for service account users, which are identified by clientRef. A username inside spec.definition is tolerated only when it matches spec.username; a conflicting value is rejected.

A KeycloakUser represents a user within a Keycloak realm, or a service account user associated with a client.

Specification

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakUser
metadata:
  name: john-doe
spec:
  # One of realmRef, clusterRealmRef, or clientRef must be specified
  
  # Option 1: Reference to a KeycloakRealm (for regular realm users)
  realmRef:
    name: my-realm
  
  # Option 2: Reference to a ClusterKeycloakRealm (for cluster-scoped realms)
  # clusterRealmRef:
  #   name: my-cluster-realm
  
  # Option 3: Reference to a KeycloakClient (for service account users)
  # clientRef:
  #   name: my-client
  
  # User definition (Keycloak UserRepresentation)
  # Note: For service account users (clientRef), definition is optional
  username: johndoe
  definition:
    email: john.doe@example.com
    firstName: John
    lastName: Doe
    enabled: true
    # ... any other Keycloak user properties
    # (must not contain realmRoles, clientRoles, or groups — see below)
  
  # Optional: role and group assignments (see "Roles and Groups")
  realmRoles:
    - offline_access
  clientRoles:
    my-app:
      - admin
  groups:
    - developers
  
  # Optional: Initial password (only set on creation)
  initialPassword:
    value: "temporary-password"
    temporary: true  # User must change on first login

To manage credentials in a Kubernetes Secret (including password generation), use KeycloakUserCredential.

Status

status:
  ready: true
  status: "Ready"
  userID: "12345678-1234-1234-1234-123456789abc"
  message: "User synchronized successfully"
  resourcePath: "/admin/realms/my-realm/users/12345678-..."
  isServiceAccount: false
  instance:
    instanceRef: my-keycloak
  realm:
    realmRef: my-realm
  conditions:
    - type: Ready
      status: "True"
      reason: Synchronized

Example

Basic User

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakUser
metadata:
  name: admin-user
spec:
  realmRef:
    name: my-realm
  username: admin
  definition:
    email: admin@example.com
    firstName: Admin
    lastName: User
    enabled: true
    emailVerified: true

User with Managed Credentials

Create the user, then attach a KeycloakUserCredential that generates a password, stores it in a Secret, and syncs it into Keycloak:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakUser
metadata:
  name: john-doe
spec:
  realmRef:
    name: my-realm
  username: johndoe
  definition:
    email: john.doe@example.com
    firstName: John
    lastName: Doe
    enabled: true
    emailVerified: true
---
apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakUserCredential
metadata:
  name: john-doe-credential
spec:
  userRef:
    name: john-doe
  userSecret:
    secretName: john-doe-password
    create: true  # Generate a password and create the secret

See KeycloakUserCredential for existing secrets, key names, and password policy.

User with Attributes

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakUser
metadata:
  name: employee
spec:
  realmRef:
    name: my-realm
  username: jsmith
  definition:
    email: jsmith@company.com
    firstName: Jane
    lastName: Smith
    enabled: true
    attributes:
      department:
        - Engineering
      employee_id:
        - "12345"
      manager:
        - "jdoe"

User with Roles and Groups

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakUser
metadata:
  name: developer
spec:
  realmRef:
    name: my-realm
  username: developer1
  definition:
    email: dev@example.com
    enabled: true
  realmRoles:
    - offline_access
  clientRoles:
    my-app:
      - viewer
  groups:
    - developers
    - team-alpha

Service Account User

Manage the service account user associated with a client. This is useful for assigning roles or attributes to a client’s service account.

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakUser
metadata:
  name: my-service-account
spec:
  # Use clientRef instead of realmRef for service account users
  clientRef:
    name: my-service-client
  # Definition is optional - the service account is automatically created by Keycloak
  # when serviceAccountsEnabled: true on the client
  definition:
    # You can add/modify attributes on the service account
    attributes:
      department:
        - Platform

Service Account with Roles

The typed role fields also work for service account users:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakUser
metadata:
  name: my-service-sa
spec:
  clientRef:
    name: my-service-client
  realmRoles:
    - admin
  clientRoles:
    realm-management:
      - manage-users

Alternatively, assign individual roles with KeycloakRoleMapping using serviceAccountRef — without an intermediate KeycloakUser (see KeycloakRoleMapping). Do not combine both mechanisms for the same user.

Roles and Groups

spec.realmRoles, spec.clientRoles, and spec.groups are reconciled via Keycloak’s dedicated role-mapping and group-membership endpoints. They must not appear inside spec.definition (Keycloak ignores them in the user representation anyway); the operator rejects such definitions.

Each field is authoritative when set:

• Omitted (nil): the operator does not touch that category of assignments.
• Set (even to an empty list): the operator reconciles Keycloak to exactly that set, removing anything else. For clientRoles, roles on clients absent from the map are also removed.

Groups are matched by top-level group name. Roles and groups must already exist in the realm (e.g. via KeycloakRole or KeycloakGroup); unknown names are skipped with a log message.

Because these fields are authoritative, do not combine them with KeycloakRoleMapping resources targeting the same user — the user’s reconciler would remove the mappings again.

Definition Properties

Common properties from Keycloak UserRepresentation:

Role and group assignments (realmRoles, clientRoles, groups) are typed spec fields, not definition properties.

Short Names

kubectl get kcu

Parent Reference

A KeycloakUser can belong to one of three parent types:

Note: Exactly one of realmRef, clusterRealmRef, or clientRef must be specified.

Service Account Users

When using clientRef, the operator manages the service account user that Keycloak automatically creates for clients with serviceAccountsEnabled: true. This allows you to:

• Add custom attributes to the service account
• Use KeycloakRoleMapping to assign roles to the service account
• Manage the service account declaratively alongside other resources

The definition field is optional for service account users since Keycloak creates the user automatically.

Notes

• spec.initialPassword is only set on user creation
• To manage or rotate a password declaratively, use KeycloakUserCredential
• For service account users, the username is automatically set by Keycloak (format: service-account-<client-id>)