What Are Default Roles in Keycloak? — The welcome kit every new user automatically gets
A beginner-friendly, ground-up explanation of how Keycloak automatically hands every new user a starting set of permissions, and how to design that starting set safely.
Imagine starting a new job. On your very first day, without anyone having to think about it individually, you’re automatically given a building access badge, an email account, and access to the company’s general announcements channel. Nobody manually decides this for each new hire — it just happens, every time, because it’s the standard starting kit for anyone who joins. A default role in Keycloak is exactly this “standard starting kit,” except instead of new employees, it’s applied automatically to every new user account the moment it’s created.
1What Are Default Roles?
Let’s start with a precise, plain-English definition before layering on detail.
A default role is a role that Keycloak automatically assigns to every new user the instant their account is created, without any administrator needing to manually grant it. Rather than starting every user with zero permissions and requiring someone to assign a baseline role one account at a time, default roles guarantee that every user begins with a consistent, predictable starting set of access.
Think of a public library. The moment you get a library card, you’re automatically allowed to borrow books and use the reading room — nobody has to manually approve those two basic privileges for you personally. Only if you later want to reserve a private study room or access the rare-books archive would you need something extra, granted individually. A default role is that automatic, no-questions-asked starting privilege every new library member receives.
Role
A named permission or label that can be assigned to a user, representing what they’re allowed to do.
Default Role
A role automatically assigned to every newly created user in a realm.
Composite Role
A role that automatically includes one or more other roles bundled inside it.
Role Mapping
The actual record connecting a specific user to a specific role they hold.
In Keycloak, this feature lives under the special composite role usually named default-roles-[realm name]. Rather than being a strange, separate mechanism, a default role is really just an ordinary composite role that Keycloak has been told to automatically attach to every new user behind the scenes.
2Why Default Roles Exist — The Problem They Solve
To appreciate default roles, picture what user management would look like without them.
Without default roles, every single time a new user account is created — whether by an administrator, through self-registration, or via an automated system — someone or something would need to remember to manually assign the baseline permissions that account should have. Multiply this by hundreds or thousands of new users over time, and it’s easy to see how mistakes and inconsistencies creep in.
A forgotten manual step means some users end up with baseline access they need to function normally, while others — created on a busy day, or through a slightly different process — end up missing it entirely, leading to confusing support tickets and inconsistent behavior across the user base.
Default roles solve this by making the baseline permission set a guarantee enforced by the system itself, not a manual step that depends on someone remembering to do it correctly, every single time, forever.
3Core Concepts: Roles, Composite Roles, and Default Assignment
A handful of simple ideas combine to make default roles work.
Role
A role is simply a named label representing a set of permissions — like “user,” “viewer,” or “billing-manager.” On its own, a role is meaningless until it’s assigned to a user.
Composite Role
A composite role is a role that automatically brings other roles along with it. Assigning a single composite role to a user can quietly grant them several underlying roles all at once, without needing to assign each one individually.
The Default Roles Composite
Keycloak represents the default role set as a special composite role, and any role placed inside this composite becomes part of what every new user automatically receives. Adding or removing a role from this composite immediately changes what future new users will start with.
Picture a “starter pack” gift box at a gym. Inside the box are several separate items — a water bottle, a gym towel, a welcome guide. The “starter pack” itself is the composite role; the water bottle, towel, and guide are the individual roles bundled inside it. Handing someone the starter pack (assigning the default roles composite) automatically gives them everything packed inside, in one single action.
offline_access
A common built-in role often included by default, allowing long-lived offline token usage.
uma_authorization
Another common built-in role, related to Keycloak’s fine-grained authorization services.
Custom Baseline Role
An organization-specific role, like “basic-user,” representing the minimum access every account needs.
4Architecture — Where Default Roles Fit Inside Keycloak
A look at the moving pieces involved in this feature.
Realm Default Roles Composite
The special, per-realm composite role holding every role that should be automatically granted to new users in that realm.
User Creation Handler
The internal process responsible for setting up a brand-new user account, which also triggers the default role assignment.
Role Mapping Store
Where Keycloak records exactly which roles each individual user holds, including the ones granted automatically.
Token Builder
The component responsible for including a user’s roles — default and otherwise — as claims inside their issued tokens.
Because this composite is scoped to a single realm, different realms can define entirely different default starting privileges — a customer-facing realm might default new users to a simple “customer” role, while an internal employee realm might default new users to a “pending-approval” role that grants very limited access until a manager approves further permissions.
5How Default Roles Are Assigned, Step by Step
Let’s trace exactly what happens behind the scenes the moment a new user is created.
A New User Account Is Created
This might happen through the admin console, self-registration, or an automated provisioning process.
Keycloak Checks the Realm’s Default Roles Composite
It looks up whatever roles are currently configured inside the default roles composite for that realm.
The Composite Role Is Assigned to the User
The new user is automatically mapped to the default roles composite, without any manual step.
Composite Expansion Happens
Any individual roles bundled inside the composite are effectively granted to the user as well.
User Logs In Later
When the user authenticates, their effective roles — including the default ones — are gathered together.
Roles Appear in the Token
These roles are included as claims in the resulting token, ready for applications to check against.
flowchart TD
A[New User Account Created] --> B[Keycloak Checks Realm Default Roles Composite]
B --> C[Composite Assigned to New User]
C --> D[Bundled Roles Inside Composite Expand]
D --> E[User Now Effectively Holds All Default Roles]
E --> F[Roles Included in Future Login Tokens]
6Data Flow and Lifecycle — From Assignment to Token Claim
A broader view of how a default role, once granted, actually shows up when a user interacts with an application.
sequenceDiagram
participant Admin as Administrator
participant KC as Keycloak
participant U as New User
participant App as Application
Admin->>KC: Configure default-roles-[realm] composite
U->>KC: Account created
KC->>KC: Assign default roles composite automatically
U->>KC: Log in later
KC->>KC: Expand composite into effective roles
KC-->>App: Issue token with role claims included
App->>App: Check roles to decide what user can access
An important detail here: default roles are only applied automatically at the moment an account is created. Changing the default roles composite later does not retroactively update users who already existed before the change — it only affects users created afterward, unless an administrator deliberately updates existing accounts as well.
7Realm Default Roles vs Client Roles vs Manually Assigned Roles
It helps to clearly separate default roles from the other kinds of role assignment Keycloak supports.
| Type | How It’s Assigned | Typical Use |
|---|---|---|
| Default Role | Automatically, the moment a new user account is created | Baseline access every user should start with |
| Client Role | Manually assigned, scoped to one specific application | Permissions specific to a single application’s functionality |
| Manually Assigned Realm Role | Deliberately granted by an administrator after account creation | Elevated or specialized access, like “admin” or “billing-manager” |
Default roles are like the standard employee badge everyone gets on day one. Client roles are like a special keycard that only opens the door to one particular department’s equipment room. Manually assigned realm roles are like a promotion — something a manager has to deliberately decide and grant, rather than something that happens automatically for everyone.
8Advantages, Disadvantages, and Trade-offs
Default roles are convenient, but that convenience comes with real design responsibility.
Advantages
- Guarantees every user starts with a consistent, predictable baseline
- Removes the risk of a forgotten manual step during account creation
- Works automatically across every account creation method — admin console, self-registration, or automation
- Centrally editable — one change updates what future new users will receive
- Reduces support overhead caused by inconsistent starting access
Disadvantages / Trade-offs
- An overly generous default role set grants that access to everyone, without exception
- Changes don’t retroactively apply to existing users, which can create inconsistency over time
- Easy to overlook during a security review, since it doesn’t require a deliberate action per user
- A poorly chosen default can quietly grant more access than intended to self-registered accounts
Whatever is placed inside the default roles composite is granted to literally every new user, with zero exceptions and zero review — this makes it one of the highest-leverage settings in a realm, for better or worse.
9Security Considerations for Default Roles
Because default roles apply so broadly and automatically, their configuration deserves special care.
Keep the Default Set Minimal
Following the principle of least privilege, the default roles composite should contain only what every single user genuinely needs from the very first moment — nothing sensitive, nothing elevated.
A new employee’s day-one badge should open the front door and the break room — not the server room and the finance office. Anything sensitive should require a deliberate, individually reviewed decision, not be handed out automatically to everyone who happens to sign up.
Be Especially Careful with Self-Registration
When a realm allows users to register themselves without administrator review, the default roles composite effectively becomes the maximum access an unverified stranger can obtain just by filling out a form. This makes minimal defaults especially important in self-registration scenarios.
Review After Adding New Realm Roles
When a new role is created for a specific purpose, double-check it hasn’t been accidentally nested inside a composite role that’s part of the default set, which would silently grant it to every future user.
Problem
Adding a powerful or sensitive role directly into the default roles composite, intending it as a temporary convenience during initial setup or testing.
Why It’s Harmful
Temporary shortcuts like this are frequently forgotten, quietly granting excessive access to every new user indefinitely, especially in realms with self-registration enabled.
Correct Approach
Keep sensitive roles out of the default set entirely, assigning them individually and deliberately instead, even if it means a bit more manual work upfront.
10Monitoring, Logging, and Metrics
Even an automatic feature benefits from ongoing visibility.
Default Roles Composite Changes
Tracking every edit to this composite is especially important, since a single change affects every future new user.
New User Creation Volume
A sudden spike in new accounts, especially through self-registration, means the current default role set is being applied at scale — worth double-checking it’s still appropriate.
Users Missing Expected Roles
Accounts created before a default role change won’t have it automatically — monitoring for this gap helps catch inconsistencies across older accounts.
Periodic Composite Content Audit
Regularly reviewing exactly what roles currently live inside the default composite confirms nothing sensitive has crept in unnoticed.
Because the default roles composite silently shapes every new account’s starting access, it deserves the same level of monitoring attention as any other high-impact administrative setting, not less.
11Design Patterns and Anti-Patterns
A few tested habits for designing default roles well, and a few traps to avoid.
Pattern: Use a Dedicated “Basic User” Role
Create a single, clearly named custom role representing the genuine baseline, and place only that inside the default composite, rather than several loosely related roles.
Pattern: Pair Defaults with a Review Step for Sensitive Access
Use a limited default role (like “pending-approval”) for self-registered users, requiring a deliberate administrator action before granting anything further.
Pattern: Document What’s in the Default Set and Why
Keep a short written record of every role in the default composite and the reasoning behind including it, making future audits far easier.
Problem
Never reviewing the default roles composite after the realm’s initial setup, treating it as a “set once and forget” configuration.
Why It’s Harmful
As an organization’s applications and roles evolve, a stale default set can drift out of alignment with actual needs — either granting outdated access or missing something every new user genuinely requires now.
Correct Approach
Revisit the default roles composite as part of periodic access reviews, treating it as living configuration rather than a one-time setup step.
12Best Practices and Common Mistakes
A practical checklist for anyone configuring or reviewing default roles.
Start Minimal, Expand Deliberately
Begin with the smallest reasonable default set, adding more only when a genuine, well-understood need arises.
Separate Realms for Separate Trust Levels
Consider using distinct realms for customer-facing and internal employee users, since their appropriate default access is often very different.
Test New User Creation After Changes
After editing the default roles composite, create a test account and confirm the resulting roles match expectations before relying on it in production.
Include Default Roles in Access Reviews
Treat the default composite as a first-class item in any periodic security or access audit, not an afterthought.
Frequent mistakes include placing a sensitive role in the default set for temporary convenience and forgetting to remove it, assuming a change to the composite automatically updates existing users, and never revisiting the default set as the organization’s needs change over time.
13Real-World Examples
Seeing default roles applied to concrete situations makes the concept click.
Customer-Facing E-Commerce Platform
Every self-registered shopper automatically receives a simple “customer” role, sufficient to browse and purchase, with nothing sensitive included.
Internal Employee Portal with Approval Workflow
New employee accounts default to a limited “pending-approval” role, with department-specific access granted manually only after HR or a manager confirms the hire.
SaaS Product with Free Trial Signups
New trial users automatically receive a “trial-user” role, deliberately excluded from any billing-related or administrative roles until they convert to a paid plan.
Multi-Tenant Platform with Separate Realms
Each tenant’s own realm defines its own default roles composite, allowing different customer organizations to have entirely different baseline access without affecting one another.
14Frequently Asked Questions
No. Default roles are only applied automatically at the moment a new user account is created. Existing users don’t retroactively receive changes made to the default roles composite afterward.
Yes. Once assigned, a default role behaves like any other role mapping — an administrator can remove it from an individual user’s account just as they would remove any manually assigned role.
No. Each realm has its own independent default roles composite, so different realms can automatically grant completely different baseline access to their new users.
Yes. A composite role can bundle together both realm roles and client roles, meaning default assignment can technically include client-specific permissions as well, though this should be done carefully.
Generally, no. Doing so would grant administrative access to every single new user automatically, which is almost always far more than intended and a serious security risk, especially with self-registration enabled.
The realm’s default roles composite is visible and editable directly in Keycloak’s admin console under the realm’s roles section, where its current contents can be reviewed at any time.
15Summary and Key Takeaways
Default roles in Keycloak guarantee that every new user, the moment their account is created, automatically receives a consistent, predictable baseline set of permissions — no manual step required, no risk of a forgotten assignment. Implemented as a special composite role scoped to each realm, they can bundle together several individual roles into one automatic grant, applied uniformly across every account creation method, from admin-console creation to self-registration. This consistency and convenience is genuinely valuable, but it comes with real weight: whatever lives inside the default composite is handed to literally every new user without exception, making it one of the most impactful — and most easily overlooked — settings in an entire realm. Treated with the same care as any other high-leverage security decision, default roles become a reliable foundation; treated as a forgotten setup detail, they become a quiet, growing risk.
Key Takeaways
- A default role is automatically assigned to every new user at creation. — No manual step is needed, and none can be forgotten.
- It’s implemented as a special composite role per realm. — Multiple individual roles can be bundled together into one automatic grant.
- Assignment happens only at account creation time. — Changing the composite later does not retroactively affect users created before the change.
- Different realms can have entirely different defaults. — Each realm’s default roles composite is independent of every other realm’s.
- The principle of least privilege matters most here. — Whatever is included applies to literally every user, so the default set should stay minimal.
- Self-registration raises the stakes further. — In that scenario, the default set is effectively the maximum access an unverified stranger can gain instantly.
- Regular review keeps default roles trustworthy over time. — Treat the composite as living configuration, not a one-time setup detail to forget about.