Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Realms, Users and Roles

Groups and User Attributes in Keycloak

Organize users with Keycloak groups and subgroups, inherit roles and attributes, add the groups claim to tokens, and use attributes for custom data such as department or tenant.

Assigning roles user by user does not scale. Groups solve that: put people in a group once, attach roles to the group, and every member gets them. Groups form a tree, so a team inside a department inherits what the department grants. This lesson shows how to design the tree, how inheritance works, how to get group information into tokens and how attributes carry custom data.

What a group is

A group is a named set of users with optional role mappings and attributes. Groups can contain subgroups, forming a hierarchy such as:

TEXT
/company
  /company/engineering
    /company/engineering/backend
    /company/engineering/platform
  /company/finance

A group is identified by its path (/company/engineering/backend), which is what you will see in tokens. A user can belong to several groups.

Create groups in Groups > Create group. Open a group to see tabs: Child groups, Members, Attributes and Role mapping. Add a user either from the user's Groups tab (Join group) or from the group's Members tab (Add member).

Inheritance

  • Roles: a member inherits the roles of the group and of all ancestors. A member of /company/engineering/backend gets roles mapped to /company, /company/engineering and /company/engineering/backend. The reverse is not true: parents do not get children's roles.
  • Attributes: group attributes are inherited by members; a more specific (child) group's attribute overrides the same attribute name on an ancestor. A user's own attribute overrides group values when you read the effective attribute.
  • Membership: being a member of a subgroup does not make you a member of the parent for the purposes of a groups claim; the claim lists exactly the groups you joined (but you can filter and build rules on paths).

Because inheritance flows downward, put broad roles high and narrow roles low.

Groups versus roles

Question Prefer
"Which people belong together?" (team, department, customer) Group
"What may a person do in an app?" Role
"Apply the same permissions to many people" Group + role mapping
"An app needs to know the person's team" Group membership claim

A frequent design is groups for membership, roles for permissions: map roles to groups, and do not check group names in the application when a role says the same thing. Checking a role keeps the app independent of how your organization is structured.

Adding groups to tokens

Groups are not in tokens by default. Add a Group Membership protocol mapper, either on one client or on a shared client scope:

  1. Clients > (client) > Client scopes > (client)-dedicated scope > Add mapper > By configuration > Group Membership.
  2. Name: groups. Token claim name: groups. Turn Full group path on or off, and enable Add to ID token / Add to access token as needed.

With full path on, the claim looks like "groups": ["/company/engineering/backend"]; off gives ["backend"] and can make two groups named backend in different trees ambiguous. Keep full paths for anything security-related.

Remember that large group lists make tokens big. Tokens travel in HTTP headers, and servers reject very large headers (often over 8 KB). Add only the claims an application needs.

Attributes

An attribute is a custom name-value pair on a user (or group, client, realm). Typical examples: department, employeeId, tenantId, phone. Since Keycloak 24 attributes should be declared in the user profile (Realm settings > User profile) to get validation and forms; undeclared ones are unmanaged.

To send an attribute in a token use a User Attribute mapper: User Attribute = tenantId, Token Claim Name = tenant_id, Claim JSON Type String, add to access token. The mapper can emit multivalued attributes as a JSON array.

Be careful with attributes users can edit themselves: if a user can set tenantId, they could change who they appear to be. In the user profile, make sensitive attributes admin-only for editing. Roles and attributes that control access must never be user-editable.

Group management over the REST API

Terminal
# list top-level groups
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8080/admin/realms/demo/groups

# create a subgroup under a group id
curl -i -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  http://localhost:8080/admin/realms/demo/groups/$PARENT_ID/children \
  -d '{"name":"backend"}'

# put a user in a group
curl -i -X PUT -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/admin/realms/demo/users/$USER_ID/groups/$GROUP_ID

Inheritance in code (stand-in)

This runnable stand-in models the tree, the roles and attributes of each group, and computes a user's effective roles and attribute values with the inheritance rules above.

Node.js Stand-in: group inheritance

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Dana is not in /company/finance, so she gets no ledger-read. Her region is eu because the child group overrides the parent's global.

Group-based rules (stand-in)

A second stand-in shows an application using a role from the token instead of a group name, plus a path-prefix check for membership, which is how you test "is in this subtree".

Node.js Stand-in: subtree membership check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last line shows why you compare path segments with a trailing slash: a plain startsWith('/company/eng') would wrongly match /company/engineering.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A user is a member of /company/engineering/backend. Which roles apply?

    Members inherit roles from their group and every ancestor group.
  2. 2. How do you get group membership into a token?

    Groups are not in tokens by default; a Group Membership mapper adds the claim.
  3. 3. Why is it risky to let users edit an attribute like tenantId?

    Attributes used for access decisions must be admin-controlled.
  4. 4. Why use the full group path in the claim?

    Two groups named backend under different parents differ only by their paths.

Summary

  • Groups are a hierarchy of users with role mappings and attributes; their identity is the path.
  • Members inherit roles and attributes from ancestors; child values override parents.
  • Prefer groups for membership and roles for permissions; apps should check roles.
  • A Group Membership mapper adds groups to tokens; keep tokens small.
  • Attributes carry custom data; declare them in the user profile and keep access-relevant ones admin-only.

Next: Required Actions and User Federation