Learn Keycloak - Groups & Roles

#Introduction

In episode 17 you connected Keycloak to external systems through SCIM so users are automatically provisioned from the HR system. Episode 18 goes one level deeper to the foundation that determines what users are allowed to do: groups and roles. Groups group users, roles grant permissions, and the two meet in role mapping. You'll see the difference between realm roles and client roles, how composite roles work, group hierarchies, and the authorization patterns RBAC, ABAC, and group-based permissions.

#Understanding Groups in Keycloak

A group is a container for users who share something in common, such as division, location, or access level. Groups don't set permissions directly; they become the attachment point for applying roles and attributes to many users at once — far more economical than editing users one by one.

#Creating a Group

Through the admin console, open the Groups menu and click New group. As an automated alternative, use the Admin REST API:

curl -X POST "https://id.example.com/admin/realms/myrealm/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "developers"}'

The group management endpoints in the Admin REST API live under /admin/realms/ with the realm name as a path segment. This is important to understand if you later want to write provisioning scripts.

#Group Hierarchy

Groups can have subgroups. For example the engineering group with the children developers, devops, and qa. This hierarchy helps large organizations:

• Roles attached to the parent group are inherited by all subgroups and their members.
• Membership is transitive: a user in devops is automatically considered a member of engineering.

{
  "name": "engineering",
  "subGroups": [
    {"name": "developers"},
    {"name": "devops"},
    {"name": "qa"}
  ]
}

#Group Membership

Add users to a group via the group detail page (the Members tab) or from the user profile (the Groups tab). The key point: group roles and attributes flow to all members, so manage once at the group level, not per user. To list groups from the terminal, run kcadm.sh get groups -r myrealm.

#Group Attributes

Groups can carry key-value attributes, for example department=engineering or location=jakarta. These attributes are the fuel for attribute-based authorization (ABAC), which we'll cover shortly.

#Default Groups

Some groups are meant to be joined by all new users without them choosing. Open Realm Settings → the Login tab, then add the group to the Default groups setting. Newly registered users automatically join that group — a common pattern for applying onboarding roles from day one.

#Understanding Roles in Keycloak

Roles are named sets of permissions that can be granted to users or groups. Keycloak distinguishes two scopes: realm and client.

#Realm Roles vs Client Roles

Rule of thumb: keep things that span applications in realm roles, keep application-specific things in client roles. This keeps role mapping readable and non-conflicting.

#Composite Roles

A composite role is a role that "wraps" other roles. When a user is given a composite role, all the roles inside it become active:

roles:
  - name: reader
    composite: true
    includes:
      - realm: view-user
      - realm: view-group
      - client: webapp
        role: view-basic-info

#Role Hierarchy

Composite roles create a kind of role hierarchy. reader is higher than view-user because it includes it. This hierarchy is useful for assembling large roles from small blocks, but be careful: complexity rises with depth, and auditing becomes harder.

#Role Mapping

Role mapping is the process of attaching a role to a user or group:

• User level: user detail page → Role mapping tab.
• Group level: group detail → Role mapping tab. All group members automatically get that role.
• API: the role-mappings/realm subpath under the user realm endpoint, and a similar subpath under the group endpoint.

Role mapping to groups is the most efficient technique at scale: add a user to the group, and the roles come along automatically.

#Groups vs Roles: When to Use Which

The big picture: groups = organizational structure, roles = access rights. In practice, both are combined — groups are given roles.

#Authorization: RBAC, ABAC, and Group-Based Permissions

#RBAC (Role-Based Access Control)

The most common model: users or groups are given roles, and the application checks the roles in the token (for example the realm_access or resource_access claim in a JWT). Simple, easy to audit, and the basis of almost every Keycloak setup.

#ABAC (Attribute-Based Access Control)

Decisions are made from attributes, not just roles: "may access if location equals the data's country", "may if clearance-level is above 3". In Keycloak, these attributes can come from user attributes as well as group attributes.

#Group-Based Permissions

The most practical combination of the two: groups hold attributes and roles, then the application decides based on group membership. This is the recommended pattern for automated onboarding and offboarding — just manage group membership.

#Fine-Grained Authorization

For the most detailed control, Keycloak has Authorization Services (UMA 2.0): resources, scopes, policies, and server-side context evaluation. This is a big topic that will be covered in episode 25. For this episode, just know that RBAC and ABAC through groups and roles are the foundation you must master before touching that layer.

#Best Practices

#Role Naming Conventions

Use a consistent verb-noun pattern, for example view-*, create-*, manage-*. Consistency makes the role set readable and safe to refactor.

#Group Design Patterns

Pick one classification basis: organization, function, or access level — don't mix them in a single hierarchy. For example, don't place intern and engineering as siblings at the same level if they have different meanings.

#Permission Modeling

Attach roles to groups, not to individual users. Manage permissions top-down: parent groups for general things, subgroups for exceptions.

#Principle of Least Privilege

Grant only the minimum permissions needed, and periodically check whether they're still relevant. Combine with the audit events in episode 22 to see who actually uses those roles.

#Closing

In this episode 18, you mapped the two pillars of Keycloak authorization: groups as organizational structure (hierarchy, membership, attributes, default groups) and roles as access rights (realm/client, composite, role mapping), then united them in RBAC, ABAC, and group-based permissions.

Key takeaways:

• Groups for structure, roles for permissions — keep them separate so the model stays simple.
• Attach roles to groups, not to individual users, for scale and ease of auditing.
• Realm roles for cross-application, client roles for one application — don't mix them carelessly.
• Composite roles make assembling access rights easier, but keep the hierarchy shallow.

In the next episode (episode 19), you'll lift Keycloak from a sandbox to a real installation: installing Keycloak — standalone ZIP/TAR, the Docker container from quay.io, database configuration, and initial realm setup.