KeycloakRoleMapping

The KeycloakRoleMapping resource assigns Keycloak roles to users, groups, or client service accounts.

Overview

This CRD provides a declarative way to:

Assign realm roles to users
Assign client roles to users
Assign realm roles to groups
Assign client roles to groups
Assign roles to a client’s service account (via serviceAccountRef)

Examples

Realm Role to User

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: admin-role-mapping
spec:
  subject:
    userRef:
      name: admin-user
  roleRef:
    name: admin-role

Client Role to User (using roleRef)

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: client-admin-mapping
spec:
  subject:
    userRef:
      name: service-user
  roleRef:
    name: manage-clients

Inline Client Role to User

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: inline-client-role-mapping
spec:
  subject:
    userRef:
      name: service-user
  role:
    name: manage-clients
    clientRef:
      name: my-client

Inline Role Reference

Instead of referencing a KeycloakRole resource, you can specify the role name directly:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: builtin-role-mapping
spec:
  subject:
    userRef:
      name: my-user
  role:
    name: offline_access

Role to Group

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: group-role-mapping
spec:
  subject:
    groupRef:
      name: developers
  roleRef:
    name: developer-role

Role to a Client’s Service Account

serviceAccountRef assigns roles to the service account user that Keycloak auto-creates for clients with serviceAccountsEnabled: true, without an intermediate KeycloakUser resource:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: my-app-sa-manage-users
spec:
  subject:
    serviceAccountRef:
      name: my-app  # KeycloakClient
  role:
    name: manage-users
    clientRef:
      name: realm-management

Spec

Field	Type	Description	Required
`subject.userRef`	ResourceRef	Reference to KeycloakUser	Exactly one subject ref
`subject.groupRef`	ResourceRef	Reference to KeycloakGroup	Exactly one subject ref
`subject.serviceAccountRef`	ResourceRef	Reference to a KeycloakClient whose service account is the subject	Exactly one subject ref
`roleRef`	ResourceRef	Reference to KeycloakRole resource	Either roleRef or role
`role.name`	string	Keycloak role name (inline)	Either roleRef or role
`role.clientRef`	ResourceRef	Reference to KeycloakClient for client roles (within inline role)	No (realm role if omitted)
`role.clientId`	string	Client ID for client roles (alternative to clientRef)	No

Status

Field	Type	Description
`ready`	boolean	Whether the mapping is synced
`status`	string	Current status (Synced, Error, SubjectError, RoleError)
`message`	string	Additional status information
`resourcePath`	string	Keycloak API path for this role mapping
`subjectType`	string	Subject type (“user” or “group”)
`subjectID`	string	Keycloak ID of the user/group
`roleName`	string	Resolved role name
`roleType`	string	Role type (“realm” or “client”)
`instance`	object	Resolved instance reference
`realm`	object	Resolved realm reference
`observedGeneration`	integer	Last observed generation
`conditions`	[]Condition	Kubernetes conditions

Behavior

Role Resolution

Using roleRef:

The operator looks up the referenced KeycloakRole resource
It reads status.roleName from that resource (which may differ from the CR name)
If the referenced KeycloakRole has its own spec.clientRef, the mapping is automatically scoped to that client and the client’s UUID is resolved from the KeycloakClient’s status
The referenced role (and the client it points at, if any) must be Ready; otherwise the mapping requeues
This is the recommended approach for roles managed by the operator

Using role.name:

The operator queries Keycloak for a role with the given name
This is useful for built-in roles like offline_access

Mapping Types

Subject	Role source	Result
userRef	inline `role` without `clientRef`/`clientId`	User realm role mapping
userRef	inline `role` with `clientRef` or `clientId`	User client role mapping
userRef	`roleRef` to a `KeycloakRole` without `clientRef`	User realm role mapping
userRef	`roleRef` to a `KeycloakRole` with `clientRef`	User client role mapping
groupRef	inline `role` without `clientRef`/`clientId`	Group realm role mapping
groupRef	inline `role` with `clientRef` or `clientId`	Group client role mapping
groupRef	`roleRef` to a `KeycloakRole` without `clientRef`	Group realm role mapping
groupRef	`roleRef` to a `KeycloakRole` with `clientRef`	Group client role mapping
serviceAccountRef	any role source	Role mapping on the client’s service account user

Cleanup

When the KeycloakRoleMapping is deleted:

The finalizer removes the role mapping from Keycloak
The user/group no longer has the role assigned

Use Cases

RBAC Setup

Set up role-based access control with groups:

# Create a group
apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakGroup
metadata:
  name: admins
spec:
  realmRef:
    name: my-realm
  name: admins
  definition: {}
---
# Create a role
apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRole
metadata:
  name: admin-role
spec:
  realmRef:
    name: my-realm
  name: admin
  definition:
    description: Full admin access
---
# Map role to group
apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: admins-admin-role
spec:
  subject:
    groupRef:
      name: admins
  roleRef:
    name: admin-role

Service Account Roles

Assign specific client roles to service accounts:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: service-manage-users
spec:
  subject:
    userRef:
      name: service-account
  role:
    name: manage-users
    clientRef:
      name: realm-management

Multiple Role Assignments

Assign multiple roles to the same user:

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: user-role-1
spec:
  subject:
    userRef:
      name: my-user
  roleRef:
    name: role-1
---
apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakRoleMapping
metadata:
  name: user-role-2
spec:
  subject:
    userRef:
      name: my-user
  roleRef:
    name: role-2

Notes

Exactly one of userRef, groupRef, or serviceAccountRef can be specified
Only one of roleRef or role can be specified
When using role.clientRef, the role must be a client role, not a realm role
Built-in Keycloak roles (like offline_access, uma_authorization) should use inline role.name
Do not combine KeycloakRoleMapping with the authoritative spec.realmRoles/spec.clientRoles fields of a KeycloakUser targeting the same user — the user’s reconciler would remove the mappings again

Keyboard shortcuts

Keycloak Operator