Groups

Groups vs roles

In Keycloak there are two related but distinct concepts: groups and roles.

• A role is a permission or capability (e.g., admin, viewer, editor). Roles are granted to users and checked by applications to decide what a user is allowed to do.
• A group is a container for users. Groups do not grant permissions on their own — they gain permissions through the roles mapped to them.

The power of the combination: map roles to a group, then add users to the group. Every member of the group automatically inherits all roles assigned to that group. When you need to change permissions for a set of users, you update the group’s role mapping once instead of touching every individual user account.

Creating a group

1. In the admin console, make sure you are in the correct realm (check the top-left drop-down).
2. Click Groups in the left sidebar.
3. Click Create group (top-right of the groups list).
4. Enter a Name for the group (e.g., developers, support-agents).
5. Click Save.

The new group now appears in the groups list. Click its name to open the group’s detail page and access its tabs.

Adding members to a group

1. Open the group from the Groups list.
2. Click the Members tab.
3. Click Add member.
4. In the search dialog, type the username or email to find the user.
5. Select the user and click Add.

The user now appears in the Members tab and immediately inherits any roles mapped to this group.

Mapping roles to a group

Role mappings on a group work the same way as role mappings on an individual user — the difference is that every current and future group member inherits the mapped roles automatically.

1. Open the group from the Groups list.
2. Click the Role mapping tab.
3. Click Assign role.
4. Use the search box to find the realm role (or client role) you want to assign.
5. Select one or more roles and click Assign.

The assigned roles are now listed under the group’s role mappings. Any user who is a member of the group will have these roles included in their token.

Subgroups

Keycloak supports a hierarchy of groups. A subgroup (child group) lives under a parent group. Members of a subgroup inherit the roles mapped to that subgroup — but they do not automatically inherit the roles of the parent group unless they are also a direct member of the parent.

To create a subgroup:

1. Open the parent group from the Groups list.
2. Click the Child groups tab (or Sub groups, depending on your Keycloak version).
3. Click Create group.
4. Enter a Name for the child group and click Save.

You can then add members and map roles to the subgroup independently of the parent. This makes it easy to model organizational hierarchies (e.g., engineering → backend, frontend).

Default groups

A default group is a group that every new user is automatically added to upon self-registration. This is useful when you want all newly registered users to start with a baseline set of roles without any administrator action.

To configure default groups:

1. Click Realm settings in the left sidebar.
2. Click the User registration tab.
3. Under Default groups, click Add groups.
4. Select one or more groups from the list and click Add.

Any user who registers through the Keycloak Account Console or the self-registration flow will be automatically placed in all default groups — and will therefore inherit their mapped roles.

Inspecting group members via the REST API

curl -s -H "Authorization: Bearer ${TOKEN}" http://localhost:8080/admin/realms/my-app/groups/${GROUP_ID}/members | jq .

Copy curl ⧉

Replace TOKEN with a valid admin access token and GROUP_ID with the UUID of the group (visible in the URL when you open the group in the admin console).

🔐 Groups over per-user roles

Assign roles to groups, then put users in groups — far easier to manage than assigning roles to individual users. When a user’s responsibilities change, move them between groups instead of hunting down every role assignment on their account.

Trade-offs

Option	Benefit	Cost
Assign permissions through a group (map roles to the group, then add users to it)	Update the role mapping once and it affects every member; moving a user between teams is just moving them between groups	The group structure must be designed well up front — getting it wrong means refactoring later
Assign roles directly to each user, one by one	Good for a personal exception you don’t want to affect the rest of the group	Doesn’t scale — when a team’s permissions change, you have to fix every account individually, and it’s easy to miss one
Use a default group that new users join automatically	No manual onboarding step; new users get baseline roles immediately	If the default group is wrong or too broad, new users get more permission than intended

Common mistakes

• Assigning roles to users one at a time instead of through a group — this becomes unmanageable as the team grows. Map roles to a group and let users inherit them through membership instead.
• Forgetting that a subgroup doesn’t automatically inherit its parent group’s roles — if you expect subgroup members to also get the parent’s permissions, you need to map the role again or add the user to the parent directly.
• Not reviewing default groups before enabling self-registration — if it’s misconfigured or too broad, self-registered users end up with roles they shouldn’t have, or none at all.

Real-world example

A company onboarding new employees — sets the default group to all-employees, so every user who self-registers within the company’s email domain is automatically placed in it with a baseline role such as view-directory, with no manual click from HR or IT.

An engineering team split into subgroups — uses a structure like engineering → backend, frontend to map specialised roles (e.g. deploy-backend) only to the relevant subgroup; when someone changes teams, moving their subgroup membership is all it takes, with no role reassignment needed.

What is the key difference between a group and a role in Keycloak?

Groups grant permissions directly; roles are just labels Roles grant permissions; groups are containers for users that inherit mapped roles Groups and roles are identical — both grant permissions A role can contain users; a group cannot

Which tab do you use to add an existing user to a group?

Role mapping Attributes Members Child groups

If you map the "editor" role to a group, what happens to a user who joins that group?

Nothing — the user must also be granted the role individually The user inherits the "editor" role automatically The user is removed from all other roles The role is copied to the user permanently and removing the user from the group has no effect

Where do you configure which groups new self-registered users are automatically added to?

Clients → Default groups Realm settings → User registration → Default groups Groups → Settings → Auto-join Authentication → Flows → Registration

Submit

Mark as complete