What Is a Realm Role in Keycloak?
The complete beginner-to-production guide to the broadest permission label Keycloak offers — one that speaks across every application in a Realm at once.
Picture a university campus ID card again, but this time look closely at the fine print stamped across the very top of it, above any department-specific stickers: “Enrolled Student.” That single stamp isn’t specific to the library, the gym, or the dining hall — it’s a fact recognized by every single building on campus at once. Show that card anywhere, and every door reads that same top-line stamp the same way. In Keycloak, that campus-wide stamp — a permission label that means the same thing to every single application connected to a Realm — is called a Realm Role.
This guide zooms in specifically on Realm Roles: what makes them different from the narrower Client Roles, how they’re structured, how they travel into a user’s token, the built-in Realm Roles Keycloak creates automatically, and the design mistakes that cause Realm Role systems to become unmanageable as an organization grows. No prior identity or security background is assumed — every term is explained the moment it appears.
1Core Concepts
What Is a Realm Role?
A Realm Role is a named permission label defined at the top level of a Realm — not tied to any single application — that can be assigned to a user and is understood identically by every Client registered inside that Realm. Names like “employee,” “verified-customer,” or “premium-subscriber” are typical Realm Roles: broad facts about a user’s overall status, not permissions scoped to one particular piece of software.
A Realm Role answers a question like “is this person an employee at all?” A Client Role answers a much narrower question like “can this person approve refunds specifically inside the billing application?” Realm Roles describe broad, organization-wide facts; Client Roles describe fine-grained, application-specific permissions.
Realm Roles Live One Level Above Applications
Recall that a Realm is Keycloak’s isolated universe of users and settings, and that individual applications register as Clients inside it. A Realm Role is defined at that same top Realm level — sitting conceptually above every individual Client — which is exactly why it’s automatically recognized by all of them without needing to be separately configured application by application.
Think of a large hospital campus again. “Hospital Staff” printed across the top of every badge is a Realm Role — recognized identically at the front gate, the cafeteria, and the parking garage, because it was issued by the campus authority itself, not by any single department. A sticker added only by the radiology department saying “Can Operate Scanner” is a Client Role — meaningful only inside that one department, understood nowhere else.
Assigned Directly or Through Groups
Like any Role, a Realm Role can be attached straight to an individual user account, or attached to a Group so that every member of that Group automatically receives it. Because Realm Roles frequently represent broad organizational facts, assigning them via Groups (mirroring departments or membership tiers) is by far the more common and more maintainable pattern in practice.
2Architecture & Components
graph TD
Realm["Realm"] --> RR1["Realm Role: employee"]
Realm --> RR2["Realm Role: verified-customer"]
Realm --> Grp["Group: Engineering-Dept"]
Grp --> RR1
User["User: sara"] -->|"assigned via Group"| Grp
User -->|"assigned directly"| RR2
User -->|"has effective realm roles"| Eff["employee, verified-customer"]
Eff -->|"written into token as"| Claim["realm_access.roles claim"]
Claim --> AppA["Client A checks role"]
Claim --> AppB["Client B checks role"]
Claim --> AppC["Client C checks role"]
Realm-Wide
Defined once at the Realm level, automatically visible to every current and future Client registered inside it.
realm_access.roles
The standard claim inside an issued token where a user’s Realm Roles are listed, distinct from the separate location used for Client Roles.
Groups
The common mechanism for attaching Realm Roles to many users at once, mirroring departments, tiers, or cohorts.
Composite Realm Role
A Realm Role that automatically includes other Realm Roles (and even Client Roles) when assigned, covered in Chapter 4.
3Built-In Realm Roles
| Realm Role | What It Governs |
|---|---|
| offline_access | Whether a user’s application can request a long-lived Refresh Token that survives even after the user’s browser session ends |
| uma_authorization | Whether a user can participate in Keycloak’s fine-grained, resource-based permission features (User-Managed Access) |
| default-roles-<realm-name> | A special composite Realm Role automatically assigned to every new user, bundling together whatever baseline access an administrator has configured as standard |
The default-roles-<realm-name> Realm Role is itself a composite — administrators customize what “every brand-new user automatically gets” simply by adding or removing Roles from inside this one default composite, rather than manually assigning a starter set of Roles to each new account.
4Composite Realm Roles
A composite Realm Role is a Realm Role with one or more other Roles attached underneath it as children — and critically, those children aren’t limited to other Realm Roles. A single composite Realm Role can bundle in Client Roles from several different applications at once, letting a broad organizational label like “department-head” quietly grant a mix of Realm-wide and application-specific access in one step.
A composite Realm Role is like a “New Manager Starter Pack” issued by HR: handing someone that one pack automatically includes the “Manager” campus badge stamp (a Realm Role) plus a spa-access sticker and a parking-garage sticker (two separate Client Roles) — all bundled into a single handover instead of assembling three separate items.
Because composite Realm Roles can reach into Client Roles belonging to applications the Realm-level administrator may not personally manage day-to-day, changes to a widely used composite Realm Role can have a much larger blast radius than expected — a single edit can silently ripple permissions into applications far outside the team that made the change.
5Internal Working
Realm Role Defined
An administrator creates the Realm Role at the top Realm level, giving it a name and an optional description.
Assigned to a User or Group
The Realm Role is attached directly to a user, or to a Group — with Group-based assignment being the far more common approach at any real scale.
User Logs In
During login, Keycloak computes the user’s full set of effective Realm Roles, combining direct assignments, Group memberships, and any composite expansions.
Written into the Token
The resulting Realm Role names are placed into the issued token’s realm_access.roles claim — one shared location every Client can read, regardless of which application actually requested the login.
Applications Check It Independently
Every application receiving that token can independently inspect the realm_access.roles claim and decide, using its own internal logic, what a given Realm Role should permit inside that specific app.
6Data Flow & Lifecycle
Creation. A Realm Role is defined once as part of an organization’s broader identity model, ideally representing a stable, long-lived fact about users, rather than a narrow, application-specific permission.
Assignment. Attached to users or Groups, with Groups strongly preferred for anything beyond a handful of individual accounts.
Propagation. Because a Realm Role is recognized by every Client automatically, adding a new application to the Realm requires no extra configuration for that new application to start understanding existing Realm Roles.
Modification. Renaming or restructuring a widely used Realm Role (especially a composite one) needs careful review, since its effects can ripple across many unrelated applications at once.
Revocation. Removing a Realm Role (or removing a user from a Group carrying it) takes effect the next time that user’s token is issued, exactly like any other Role.
graph LR
A["Realm Role Created
(top Realm level)"] --> B["Assigned
(directly, or via Group)"]
B --> C["Recognized Automatically
by every current & future Client"]
C --> D["Written into Token
(realm_access.roles)"]
D --> E["Each Application
Checks it Independently"]
7Advantages, Disadvantages & Trade-offs
Advantages
- Define a broad organizational fact once, and every current and future application automatically understands it — no per-application setup required
- Ideal for facts that genuinely span the whole organization, like “employee,” “contractor,” or “premium-subscriber”
- Simplifies onboarding new applications into an existing Realm, since they inherit an already-established Realm Role vocabulary
Disadvantages & Trade-offs
- Because they’re visible everywhere, a poorly scoped Realm Role can accidentally leak meaning into applications where it was never intended to apply
- Composite Realm Roles reaching into many Client Roles can produce a large, hard-to-audit blast radius when changed
- Overusing Realm Roles for permissions that are really application-specific blurs the clean separation Client Roles are meant to provide
8Security
Problem
A team needing a narrow permission like “can-approve-invoices” for just one billing application sometimes defines it as a Realm Role out of convenience, rather than a Client Role scoped to that one application.
Why It Fails
Every other application in the Realm now also sees this Role name inside every user’s token, even though it’s meaningless to them — increasing the risk that a different, unrelated application’s code mistakenly checks for or misinterprets that Role, granting access it never should have.
Correct Approach
Reserve Realm Roles for facts genuinely meaningful across the whole organization. Scope anything specific to one application as a Client Role on that Client instead.
Auditing the Default Composite
Because default-roles-<realm-name> is automatically granted to every single new user, any Role quietly added inside that composite becomes standard-issue access for the entire user base going forward. Reviewing what’s bundled inside this default composite periodically is a meaningful security check in its own right.
9Best Practices & Common Mistakes
Best Practices
- Reserve Realm Roles strictly for broad, organization-wide facts — push anything application-specific down into Client Roles
- Assign Realm Roles through Groups that mirror real organizational structure, not individually to each user
- Periodically review what’s bundled inside the
default-roles-<realm-name>composite - Document what each Realm Role is meant to represent, since its meaning is interpreted independently by every connected application
Common Mistakes
- Creating a new Realm Role for every narrow, single-application need instead of using Client Roles
- Letting composite Realm Roles grow deep and tangled, mixing many unrelated Client Roles together
- Assigning Realm Roles directly to individual users at scale instead of through Groups
- Never reviewing the default composite, letting it silently accumulate access over time
10Real-World & Industry Examples
Enterprise Employee Directories
A company Realm often defines Realm Roles like “employee,” “contractor,” and “manager,” assigned via Groups that mirror the HR org chart, so every internal tool automatically recognizes an employee’s baseline status without separate configuration.
SaaS Subscription Tiers
A software-as-a-service product frequently uses Realm Roles like “free-tier” and “premium-subscriber” to reflect a customer’s account-wide subscription status, letting every module of the product — billing, support, the core application — consistently recognize the same subscription level.
Educational Platforms
A university’s identity system commonly uses Realm Roles such as “student,” “faculty,” and “alumni” to represent a person’s overall relationship to the institution, recognized identically by the library system, the course portal, and the campus events site.
11Frequently Asked Questions
realm_access.roles claim, a location distinct from where Client Roles are placed, so applications can read each kind of Role from its own dedicated spot.12Summary and Key Takeaways
Key Takeaways
- A Realm Role is a permission label defined at the top Realm level, automatically recognized by every current and future Client inside that Realm.
- It’s meant for broad, organization-wide facts (“employee,” “premium-subscriber”) — narrow, application-specific permissions belong in Client Roles instead.
- Realm Roles show up inside an issued token’s realm_access.roles claim, a shared location every connected application can read.
- Keycloak automatically creates a few built-in Realm Roles, including the special default-roles-<realm-name> composite granted to every new user.
- Composite Realm Roles can bundle in Client Roles from multiple applications at once — powerful, but with a wider blast radius when changed.
- Assign Realm Roles through Groups mirroring real organizational structure, rather than directly to individual users.
- Reserve Realm Roles strictly for facts that would still make sense with any single application removed from the picture — everything else belongs in a Client Role.