Group Model

Summary

Keymate manages groups through Keycloak's group system, which provides hierarchical, attribute-bearing containers for users. A group collects users who share common access needs and assigns them realm roles or client roles collectively. Keycloak organizes groups into a tree structure where subgroups inherit their parent's role mappings. Administrators can structure the group hierarchy to separate platform-wide concerns from team-specific or department-specific needs.

Why It Exists

Assigning permissions to individual users does not scale. When hundreds of users need the same access — viewing reports, managing orders, deploying services — maintaining per-user role assignments leads to inconsistency and administrative overhead. Groups solve this by letting administrators assign roles once to a group, then manage access by adding or removing users from that group. The group model also provides a natural integration point for external identity providers that synchronize directory groups into Keycloak.

Where It Fits in Keymate

Groups occupy the layer between individual users and authorization policies. Users belong to groups, groups carry role mappings, and policies evaluate effective roles during access decisions. Groups interact with several Keymate concepts:

• Roles — groups carry realm role and client role mappings. Members inherit all roles assigned to their groups.
• Organizations — organizations carry tenant associations (tenantId) and their own role mappings (globalRoles, clientRoles). Groups complement organizations by providing realm-level role containers that any organization's users can be assigned to.
• Policy evaluation — the Policy Engine resolves a user's effective group memberships and their associated roles when evaluating authorization decisions.
• Token claims — group memberships and inherited roles can be projected into access tokens, enabling downstream services to make authorization decisions without additional lookups.

Boundaries

The group model covers:

• Hierarchical group and subgroup structure within a Keycloak realm
• Role mappings (realm and client) inherited through group membership
• Group attributes as key-value metadata
• User-to-group membership assignment

The group model does not cover:

• Direct permission assignments (permissions bind to roles, not groups)
• Fine-grained authorization relationships (see FGA Engine for tuple-based authorization)
• Organization hierarchy (see Organization Hierarchy — organizations and groups are complementary but distinct structures)

How It Works

Group structure

Keycloak represents each group as a GroupRepresentation object with a name, an optional description, a path reflecting its position in the hierarchy, optional attributes (key-value pairs), and an array of child subgroups. Groups form a tree: top-level groups sit at the realm root, and each group can contain subgroups to any depth.

A group's path encodes its position in the tree. A top-level group named "Engineering" has the path /Engineering. A subgroup named "Backend" under "Engineering" has the path /Engineering/Backend. This path-based addressing allows membership assignment by path as well as by ID.

Role inheritance

Groups carry two categories of role mappings:

Role type	Scope	Example
Realm role	Applies across the entire realm	report-viewer, audit-reader
Client role	Scoped to a specific Keycloak client	order-service:manager, billing-app:admin

When a user belongs to a group, the user inherits all realm and client roles mapped to that group. If a group has subgroups, members of a subgroup also inherit the parent group's role mappings — role inheritance flows downward through the group tree.

Group attributes

Each group can carry attributes as key-value pairs (each key maps to a list of string values). Attributes serve as metadata for organizational tagging, external system identifiers, or policy evaluation context. For example, a group might carry department: ["engineering"] and costCenter: ["ENG-400"] attributes that policies or token mappers reference during evaluation.

Group scope in Keymate

Groups in Keycloak are realm-level entities — every group exists within a single realm and is accessible to all users in that realm. Keymate does not add a structural tenant-scoping mechanism to groups themselves. Instead, administrators organize groups by intended purpose through naming conventions and role assignments:

• Platform groups — carry realm roles such as platform-super-admin, platform-sre, or platform-security-auditor. Intended for cross-cutting concerns that span organizational boundaries.
• Team or department groups — carry client roles scoped to specific applications. Intended for project teams, business units, or department-level access.

Tenant-level access boundaries are managed through organizations, which carry a tenantId and their own globalRoles and clientRoles mappings. Organizations and groups are complementary: organizations define who belongs to which tenant, while groups define which roles those users inherit at the realm level. See Tenant Group Inheritance for planned enhancements to how group memberships may propagate through the organizational hierarchy.

Membership resolution flow

During an authorization request, the system resolves group memberships in two stages:

1. Direct membership — identify all groups the user is explicitly assigned to
2. Hierarchy expansion — walk up the group tree to include parent groups and their role mappings, producing the user's effective role set

Diagram

Example Scenario

Scenario

A platform administrator creates a group for compliance auditors who need read-only access to audit logs, assigning the audit-reader realm role. Separately, a team lead creates a group for the backend engineering team with client-specific roles for the order management service.

Input

• Actor: Jane Doe (member of both the "Compliance Auditors" group and the "Backend Team" group under Acme Corp)
• Resource: Audit log entry in the Acme Corp tenant
• Action: audit:read
• Context: Acme Corp tenant scope

Expected Outcome

• Granted
• Why: Jane's effective roles include audit-reader (inherited from the "Compliance Auditors" group) and order-service:editor (inherited from the "Backend Team" group). The audit:read action is permitted by the audit-reader realm role.

Common Misunderstandings

• Groups are not roles. A group is a container for users that carries role mappings. The group itself does not grant permissions — its mapped roles do. Removing a role from a group removes that permission from all members.
• Subgroup members do not automatically belong to the parent group. Membership is explicit per group. However, subgroup members inherit the parent group's role mappings through Keycloak's role inheritance mechanism.
• Groups are realm-level, not tenant-level. All groups in a realm are accessible to all users in that realm. Tenant-level access boundaries are managed through organizations, not through group visibility scoping.

warning

Deleting a group removes all its role mappings and subgroups. Members lose the roles they inherited from that group. This operation cannot be undone — verify group membership and role dependencies before deleting.

Design Notes / Best Practices

• Prefer groups over direct role assignments for any role shared by more than a few users. This reduces administrative overhead and ensures consistency when roles change.
• Use the group hierarchy to model team structures. Assign broad roles at parent groups and specific roles at subgroups. Members of subgroups inherit parent roles without duplication.
• Use group attributes for metadata that policies or token mappers need during evaluation — cost centers, department codes, external system identifiers.
• Keep platform-wide groups minimal. Reserve them for cross-cutting concerns such as compliance auditing or SRE access. Most access control belongs in team-specific or department-specific groups.

tip

Assign roles at the highest applicable group level. A role assigned to a parent group propagates to all subgroups, avoiding duplication and reducing the risk of inconsistent assignments.

Related Use Cases

• Onboarding a new department by creating a group and assigning standard roles
• Synchronizing directory groups from an external identity provider into Keycloak groups
• Granting audit access across the organization through a compliance group with realm roles
• Restricting client-specific permissions to a team through client role mappings on a subgroup

Related Docs

Tenant Group Inheritance

How group memberships propagate through the organizational hierarchy

Group Management Guide

Step-by-step guide for creating and managing groups in the Admin Console

Authorization Concepts

Authorization models and policy evaluation in Keymate

Token Claims & Context

How group roles are projected into access tokens