What Is a Composite Role in Keycloak?
Assigning one single role to a user and having them automatically receive five others along with it isn't magic — it's a composite role. This guide explains exactly what that means and how to use the feature well.
Imagine a hotel that issues a single “Manager” keycard which, behind the scenes, automatically opens every door that a “Front Desk Staff” card opens, plus every door a “Housekeeping Supervisor” card opens, plus a few manager-only doors on top. Nobody manually programmed the manager’s card with every single door individually — the system was simply told “this card includes the permissions of these other cards too.” Keycloak’s composite role feature works exactly this way: a role can be built by bundling several other roles together, so assigning one role to a user quietly grants everything those included roles grant as well.
1What Is a Composite Role?
The foundation everything else in this guide builds on.
A composite role in Keycloak is a role that has one or more other roles associated with it, so that assigning the composite role to a user automatically grants every role bundled inside it as well. Instead of assigning a user five separate roles one by one, an administrator can create a single composite role that already contains all five, and simply assign that one role.
Think of a composite role like a combo meal at a restaurant. Ordering “The Manager Combo” automatically gets you the burger, the fries, and the drink — you don’t order each item separately, and the menu doesn’t need a new combo listed for every possible combination a customer might want built from scratch each time.
This becomes especially useful as an application grows and permission structures get more layered — rather than remembering and re-assigning a long list of individual roles to every new manager-level user, an administrator defines that bundle once, as a composite role, and reuses it.
Bundling
One role packages together several other roles that logically belong together.
Automatic Inheritance
A user assigned the composite role receives every included role’s permissions without needing each one assigned individually.
Simplified Administration
Managing one assignment is far easier than tracking a long, repeated list of individual roles per user.
Reusable Structure
The same composite role definition can be assigned to as many users as needed, staying consistent across all of them.
A composite role isn’t a different kind of object from a regular role — any role in Keycloak can become “composite” simply by having other roles attached to it.
2Composite Role vs. Simple Role vs. Group
Three related but distinct ways Keycloak lets you organize permissions.
Newcomers often lump these three concepts together, but each solves a slightly different problem, and understanding the distinction leads to cleaner, easier-to-maintain permission structures.
A simple role is a single, standalone permission — like a keycard that only opens the supply closet. A composite role is a bundle of several such permissions into one card — like the manager card from the introduction. A group is different again: it’s a way of organizing which users belong together — like a department roster — and a group can itself have roles attached to it, which its members then receive.
| Concept | What It Organizes | Typical Use |
|---|---|---|
| Simple Role | One specific permission | A single, focused capability, like “can approve invoices” |
| Composite Role | A bundle of several roles | A convenient combination, like “Manager” bundling several simple roles |
| Group | A collection of users | Organizing people by department or team, with roles attached at the group level |
Groups and composite roles can look similar from a distance — both result in a user “getting” several permissions at once — but a group is fundamentally about organizing people, while a composite role is about organizing permissions themselves, independent of who holds them.
3The Building Blocks Inside a Composite Role
What a composite role is actually made of, and the two kinds of roles it can bundle.
Associated Realm Roles
Broad, realm-wide roles that can be included inside a composite role’s bundle.
Associated Client Roles
Roles scoped to one specific application can also be included, even inside a realm-level composite role.
The Composite Role Itself
The “outer” role that users are actually assigned, acting as the entry point to everything bundled inside it.
This means a single composite role can mix and match — pulling in some broad realm roles alongside some very specific client roles — allowing administrators to build permission bundles that map closely to a real job function, rather than being limited to one narrow category of role.
It’s like a combo meal that mixes items from different parts of the menu — a main course, a side, and a drink — rather than being restricted to only combining items from one single section.
A composite role can even include another composite role inside it, creating layered bundles — a power that’s genuinely useful but also, as covered in Chapter 9, something to use carefully.
4How Composite Roles Are Resolved Internally
What actually happens when Keycloak figures out everything a user’s composite role grants them.
A User Is Assigned a Composite Role
An administrator assigns the outer composite role directly to a user’s account.
Keycloak Looks Up That Role’s Included Roles
At login or token-generation time, Keycloak checks whether the assigned role has other roles bundled inside it.
Keycloak Expands the Bundle Fully
Every included role — and any roles bundled inside those, if nested — is collected into the user’s complete, effective set of roles.
The Full, Expanded Role Set Is Placed in the Token
The resulting JWT’s role claims reflect the complete set of permissions, not just the single composite role name.
flowchart TD
A[User Assigned: Manager Role] --> B{Is Manager a Composite Role?}
B -->|Yes| C[Expand Included Roles]
C --> D[Front Desk Role]
C --> E[Housekeeping Supervisor Role]
C --> F[Manager-Only Role]
D --> G[Full Effective Role Set]
E --> G
F --> G
G --> H[Included in Issued JWT]
Because the expansion happens automatically at token generation time, a user’s effective permissions always reflect the composite role’s current, up-to-date definition — change what’s bundled inside a composite role, and every user holding it is affected the next time they log in or refresh their token.
5Common Patterns for Using Composite Roles
A few structures that come up repeatedly across real Keycloak deployments.
Job-Title Bundles
A composite role named after a real-world job title, bundling every permission that role genuinely needs.
Tiered Access Levels
Higher-tier composite roles (like “Admin”) include everything a lower tier (like “Editor”) includes, plus a few extra roles on top.
Cross-Application Bundles
A single composite role pulling together client roles from several different applications, for users who need coordinated access across all of them.
Tiered Roles in a SaaS Product
A product might define an “Editor” role with a handful of simple permissions, then build a “Manager” composite role that includes Editor plus a few additional roles, and an “Admin” composite role that includes Manager plus even more — giving each tier a clean, natural progression rather than repeating shared permissions in every tier’s definition separately.
Onboarding a New Department Head
Instead of an administrator manually assigning a long list of individual permissions to every new department head, a single “Department Head” composite role — already containing that exact bundle — can be assigned once, ensuring consistency across everyone who holds the title.
6Composite Roles in the Issued Token
Connecting composite roles back to the JWT structure covered in earlier guides.
When a user with a composite role logs in, the resulting access token’s role claims — realm_access and resource_access, as covered in earlier guides on JWTs — reflect the fully expanded set of roles, not merely the name of the composite role itself. This means an application checking the token doesn’t need to know or care that a particular permission arrived through a composite bundle rather than a direct assignment.
sequenceDiagram
participant U as User
participant K as Keycloak
participant App as Application
U->>K: Log in successfully
K->>K: Look up assigned composite role
K->>K: Expand into full set of included roles
K-->>App: Issue JWT with fully expanded role claims
App->>App: Check roles directly, unaware of bundling
This is a deliberate design choice — applications should be able to make access decisions by simply checking for the specific role they care about, without needing to understand how Keycloak’s administrators structured the underlying role bundles.
7Composite Roles vs. Groups: Choosing the Right Tool
Both features can achieve similar-looking outcomes — here’s how to decide which fits a given situation.
| Situation | Better Fit |
|---|---|
| Bundling permissions that logically define one role, regardless of who holds it | Composite Role |
| Organizing actual people by department, team, or reporting structure | Group |
| A permission bundle that should exist independently of any organizational chart | Composite Role |
| Applying the same set of roles to everyone in a particular team, which may change membership often | Group (with roles attached) |
A composite role is a defined job description — “Shift Supervisor” comes with a fixed, known bundle of responsibilities no matter who fills that position. A group is more like the actual roster of the night shift team — people move in and out of it, and the group itself can be handed roles that its current members receive for as long as they remain on the roster.
These two tools aren’t mutually exclusive — a group can itself have a composite role attached to it, combining both ideas: everyone in a particular team automatically receives a well-defined, bundled set of permissions.
8Security Considerations Around Composite Roles
A convenience feature that, used carelessly, can quietly obscure exactly what a user can actually do.
Hidden Permission Scope
A single composite role name can hide a long list of underlying permissions, making it harder to judge access at a glance.
Overly Broad Bundles
Including more roles inside a composite than a job genuinely requires quietly grants excess access to everyone who holds it.
Deep, Confusing Nesting
Composite roles that include other composite roles, several layers deep, become difficult to fully audit at a glance.
Unreviewed Drift Over Time
Roles quietly added to an existing composite bundle later can expand what many users can do without a fresh, deliberate review.
Periodically reviewing exactly what each composite role expands into — not just its name — is essential, since the convenience of bundling can otherwise make excessive access easy to overlook.
9Design Patterns and Anti-Patterns
Lessons learned from teams who’ve built composite role structures at scale.
Problem
Building composite roles many layers deep, where a composite includes another composite, which includes yet another.
Why It’s Harmful
Deep nesting makes it genuinely difficult for anyone reviewing access to understand exactly what a role actually grants without carefully tracing through every layer, increasing the chance of both accidental over-permissioning and auditing mistakes.
Correct Approach
Keep composite role structures as shallow as practically possible, favoring a small number of clear, well-named bundles over deeply layered hierarchies.
Problem
Adding roles to an existing, already-assigned composite role casually, without considering that every current holder immediately inherits the new permission.
Why It’s Harmful
Because expansion happens automatically, a seemingly small edit to a widely assigned composite role can silently and immediately widen access for every user who holds it, without any individual review of those users.
Correct Approach
Treat changes to an existing composite role’s contents as seriously as a direct permission change, reviewing who currently holds that role before adding anything new to its bundle.
Design Pattern: Descriptive, Job-Aligned Naming
Naming composite roles after real job functions — rather than vague, abstract labels — keeps the intent of a bundle clear to anyone reviewing assignments later, long after the original administrator who created it has moved on.
10Best Practices and Common Mistakes
Practical guidance for anyone designing or maintaining composite roles.
Design Bundles Around Real Job Functions
Build composite roles that map cleanly to an actual responsibility, rather than arbitrary or overly broad groupings.
Keep Nesting Shallow
Avoid composite roles built several layers deep whenever a flatter structure would work just as well.
Review Composite Contents Regularly
Periodically check what each composite role actually expands into, not just what it’s named.
Treat Bundle Edits as Access Changes
Remember that adding a role to a composite immediately affects everyone who already holds it.
Common missteps include assuming a composite role’s name fully describes its access, forgetting that nested composites can hide permissions several layers deep, and never revisiting old composite roles created early in a project’s life that may no longer match current needs.
11Advantages and Disadvantages of Composite Roles
A fair look at the trade-off between convenience and clarity.
Advantages
- Dramatically simplifies assigning consistent, repeated permission bundles
- Reduces the chance of forgetting to assign one of several related roles
- Keeps permission structures easier to update in one place as needs evolve
- Maps naturally onto real-world job titles and responsibilities
Disadvantages / Trade-offs
- Can obscure the full scope of what a role actually grants at a glance
- Deep nesting makes thorough auditing more difficult
- Editing a shared composite role affects every current holder immediately
- Requires more careful upfront design than simply assigning individual roles
12Monitoring and Auditing Composite Role Usage
Because bundled permissions can hide real scope, deliberate visibility matters more than usual.
Regular Composite Content Reviews
Periodically listing exactly what each composite role expands into helps catch scope that’s grown beyond its original intent.
Change Auditing on Role Definitions
Logging who added or removed roles from a composite bundle, and when, provides accountability for changes that affect many users at once.
Effective Permission Reporting
Generating reports of each user’s fully expanded, effective roles — not just their directly assigned composite role names — supports meaningful access reviews.
13Real-World and Industry Examples
Seeing composite roles applied in realistic scenarios.
Content Management Platforms
A publishing platform might define a “Senior Editor” composite role that includes a base “Editor” role’s permissions plus additional roles for managing other authors, giving experienced staff a natural superset of a more junior role.
Internal Admin Tools
An internal support tool might bundle “View Customer Records,” “Issue Refunds,” and “Escalate Tickets” into a single “Support Lead” composite role, rather than administrators repeatedly assigning all three individually to each new team lead.
Multi-Product Platforms
A company offering several connected products might create a composite role that bundles client roles from each individual product, so a single “Enterprise Admin” assignment grants coordinated access across the whole suite at once.
14Frequently Asked Questions
Yes — a composite role can bundle together client roles from several different applications registered within the same realm, alongside broader realm roles, all in one combined package.
No — the user is only ever directly assigned the single composite role. Keycloak expands its included roles automatically at token-generation time, rather than permanently recording each individual role against the user.
Yes, this is supported and can be useful for tiered access levels, but it should be used carefully, since deep nesting makes a role’s true scope harder to review at a glance.
Yes — because expansion happens automatically at login or token refresh, every current holder of that composite role effectively gains the newly added permission without any separate action needed.
No — a composite role bundles permissions together, while a group organizes users together. The two can be combined, since a group can itself be assigned a composite role, but they solve different organizational problems.
Reviewing a composite role’s associated roles list — and following any nested composites within it — reveals its full, effective scope; relying on the role’s name alone can be misleading, especially in more complex setups.
15Summary and Key Takeaways
A composite role is Keycloak’s way of letting one role stand in for a whole bundle of others, so administrators can assign a single, meaningful role — like “Manager” or “Support Lead” — instead of tracking and re-assigning a long list of individual permissions to every user who needs that combination. Used thoughtfully, with shallow nesting and regular review, composite roles make permission management dramatically simpler; used carelessly, they can quietly obscure exactly how much access a role really grants.
Key Takeaways
- A composite role bundles other roles together, so assigning it automatically grants everything included inside.
- Any role can become composite simply by having other roles associated with it — it isn’t a separate kind of object.
- Composite roles can mix realm and client roles, letting a bundle reflect a real job function across multiple applications.
- Expansion happens automatically at token-issuance time, so applications see a user’s full, effective role set directly.
- Composite roles and groups solve different problems — bundling permissions versus organizing people — and can be combined.
- Deep nesting and unreviewed bundle edits are the main risks, since they can quietly widen access without a clear audit trail.
- Regularly reviewing what each composite role actually expands into is essential to keeping its convenience from becoming a blind spot.