What Are Client Scopes in Keycloak? — The order form that decides what goes into a token
A complete, beginner-friendly breakdown of how Keycloak decides exactly what information ends up inside a token, and how you can control it precisely for every application.
Imagine ordering a sandwich at a busy deli counter. You don’t get handed every ingredient in the entire kitchen — you get exactly what you asked for: maybe lettuce, tomato, and cheese, but not onions, because you didn’t want them. The order slip tells the kitchen precisely what to include and what to leave out. A client scope in Keycloak works the same way for tokens: it’s a named, reusable “order” that decides exactly which pieces of information — which claims — get added into a token for a specific application, and nothing more than what was actually requested.
1What Are Client Scopes?
Let’s begin with a precise, plain-English definition before adding detail.
A client scope is a named, reusable bundle of settings that controls what information — claims, permissions, or other protocol details — gets included when Keycloak issues a token to a particular application. Instead of every application automatically receiving every possible piece of information about a user, client scopes let administrators define exactly what each application is allowed to see and request, and attach that bundle to one or many client applications.
Think of a restaurant’s set menus. The “Breakfast Menu” always includes eggs and toast. The “Lunch Menu” always includes soup and a sandwich. A customer can also add optional extras, like dessert, if they specifically ask for it. Each menu is defined once by the restaurant and then reused for every customer who orders it — exactly like a client scope is defined once in Keycloak and then reused across every application that needs it.
Client Scope
A named, reusable bundle controlling what claims and permissions a token includes.
Protocol Mapper
The specific rule inside a scope that maps a piece of user data to an actual claim in the token.
Claim
One individual fact placed inside a token, such as “email” or “roles.”
Consent
A user’s explicit approval, sometimes required before certain optional scopes are granted.
Client scopes are one of the ways Keycloak follows the industry-standard OAuth 2.0 and OpenID Connect specifications, both of which use the concept of “scope” to describe exactly what access or information is being requested during authentication — Keycloak simply gives administrators a friendly, configurable way to define and manage these scopes visually.
2Why Client Scopes Exist — The Problem They Solve
To appreciate client scopes, it helps to imagine the alternative — a world without them.
Without client scopes, an identity system would have two unappealing choices: either give every single application the exact same, fixed set of user information every time, or force a developer to hand-write custom logic for every application deciding exactly what data to expose. Neither option scales well as an organization grows to dozens or hundreds of connected applications.
A simple internal reporting tool and a sensitive HR payroll application would end up receiving identical, undifferentiated user information — far more than the reporting tool needs, and a real privacy and security concern for something as sensitive as payroll.
Client scopes solve this by making “what information does this token contain” a reusable, configurable setting rather than a hard-coded, one-size-fits-all decision. A single scope, like “profile,” can be defined once and then attached to fifty different applications — while a sensitive scope, like one exposing salary data, might be attached to only a single trusted payroll application.
3Core Concepts: Scopes, Protocol Mappers, and Claims
Let’s meet the small set of building blocks that make up every client scope.
Client Scope
The named, top-level container — for example, “email,” “profile,” or a custom scope like “billing-access.”
Protocol Mapper
Inside every client scope sit one or more protocol mappers, which are the actual rules that pull a specific piece of user or session data and place it into the token as a named claim.
Claim
The final piece of information that ends up visible inside the issued token — the direct result of a protocol mapper doing its job.
If the client scope is the restaurant’s set menu, each protocol mapper is like one specific instruction to the kitchen (“add two eggs,” “add one slice of toast”), and the claim is the actual food item that ends up on the plate as a result. Multiple protocol mappers work together inside one scope, just as multiple kitchen instructions combine to build one complete dish.
profile
Adds claims like name, username, and locale to the token.
Adds the user’s email address and whether it’s verified.
roles
Adds the user’s assigned realm and client roles to the token.
address
Adds structured address information, when available for the user.
4Architecture — Where Client Scopes Fit Inside Keycloak
Zooming out to see how scopes connect to realms, clients, and tokens.
Realm-Level Scope Definitions
Client scopes are defined once at the realm level, making them available to be reused across any client in that realm.
Client Scope Assignment
Each client application is configured with a list of assigned scopes — some Default, some Optional — determining what it can request.
Protocol Mapper Engine
The internal logic that actually executes each mapper’s rule when a token is being built, pulling data and placing it into the token.
Consent Screen
An optional user-facing prompt that can appear when a scope requires the user’s explicit approval before being granted.
Because scopes live at the realm level rather than being copied into every client individually, updating a shared scope — like adding a new claim to “profile” — automatically applies to every application using it, without needing to touch each application’s configuration one by one.
5How Client Scopes Work Internally, Step by Step
Let’s trace exactly what happens behind the scenes when a token is being built.
Application Initiates Login
The application sends a request to Keycloak, optionally listing specific scopes it wants, alongside its own default scopes.
Keycloak Resolves Applicable Scopes
Default scopes assigned to the client are always included; requested Optional scopes are added if permitted.
Consent Is Checked, If Required
If any resolved scope requires user consent and hasn’t already been granted, the user is shown a consent screen.
User Completes Authentication
The normal login flow runs, verifying the user’s identity as usual.
Protocol Mappers Execute
For every resolved scope, its protocol mappers run, pulling the relevant data and building the corresponding claims.
Claims Are Assembled Into Tokens
The resulting claims are combined into the ID token and/or access token, depending on each mapper’s configuration.
Tokens Are Returned to the Application
The application receives tokens containing exactly the claims its assigned and requested scopes allowed.
sequenceDiagram
participant App as Application
participant KC as Keycloak
participant U as User
App->>KC: Request login with default + optional scopes
KC->>KC: Resolve which scopes apply
KC->>U: Show consent screen (if required)
U->>KC: Approve requested scopes
KC->>KC: Run protocol mappers for each scope
KC-->>App: Return tokens with resolved claims
6Data Flow — From Scope Definition to Final Claim
A broader view of how a scope, once designed, flows all the way into a real token.
flowchart TD
A[Admin Defines Client Scope] --> B[Protocol Mappers Added to Scope]
B --> C[Scope Assigned to One or More Clients]
C --> D[Client Marks Scope as Default or Optional]
D --> E[User Logs In, Scope Resolved]
E --> F[Mappers Execute, Claims Built]
F --> G[Claims Appear Inside Issued Token]
Notice that the scope’s definition — what claims it can produce — is entirely separate from its assignment to a client. This separation is what makes scopes reusable: the same “email” scope definition can be a Default (always included) scope for one application and an Optional (only-if-requested) scope for another, without duplicating any configuration.
7Default Scopes vs Optional Scopes
This single setting shapes exactly how a scope behaves for a given application.
| Type | Behavior | Example Use |
|---|---|---|
| Default Scope | Always included automatically, with every login, no request needed | “profile” and “email” for most everyday applications |
| Optional Scope | Only included if the application explicitly asks for it during login | A “billing-access” scope requested only by the billing dashboard |
Default scopes are like the standard sides that automatically come with every meal at a restaurant, no need to ask. Optional scopes are like add-ons listed on the menu that you only get if you specifically request them — the kitchen won’t add extra bacon unless you actually ask for it.
A single client scope definition can be marked Default for one client and Optional for another. The scope’s contents don’t change — only how eagerly it’s applied to each specific application.
8Advantages, Disadvantages, and Trade-offs
Client scopes are powerful, but like any configuration layer, they carry real design responsibility.
Advantages
- Reusable — define once, attach to many applications
- Fine-grained control over exactly what data each application receives
- Supports the principle of least privilege for token contents
- Built directly on the OAuth 2.0 / OpenID Connect standard, so it’s portable knowledge
- Updating a shared scope automatically updates every client using it
Disadvantages / Trade-offs
- Too many overlapping custom scopes can become confusing to manage
- Misconfigured Default scopes can accidentally expose more data than intended
- Consent screens, if overused, can create friction for end users
- Requires deliberate design discipline — it’s easy to just leave everything as Default
The flexibility client scopes offer is only useful if it’s actually exercised. A realm where every scope is marked Default for every client provides no real benefit over having no scopes at all — the value comes from deliberately tailoring what each application receives.
9Security Considerations for Client Scopes
Since scopes decide what sensitive information ends up in a token, their configuration deserves careful thought.
Apply the Principle of Least Privilege
Each application should only receive the claims it genuinely needs to function — a marketing analytics tool shouldn’t receive the same detailed claims as an internal HR system.
A hotel’s front desk doesn’t need to know a guest’s medical history, even though the hotel’s own database might contain it somewhere. Client scopes work the same way — they ensure each application only receives the specific slice of information relevant to its job, not everything the identity system happens to know.
Use Consent for Sensitive Optional Scopes
Requiring explicit user consent for particularly sensitive Optional scopes adds a layer of transparency, letting the user knowingly approve what’s being shared with a given application.
Isolate Sensitive Scopes to Trusted Clients Only
A scope exposing highly sensitive claims should be assigned only to the small number of applications that genuinely require it, never broadly enabled as a Default scope across the entire realm.
Problem
Marking a sensitive scope (like one exposing internal employee IDs or salary bands) as a Default scope across every application in the realm, for convenience.
Why It’s Harmful
This exposes sensitive information far more broadly than necessary, increasing the risk if any one of those many applications is ever compromised.
Correct Approach
Restrict sensitive scopes to only the specific applications that genuinely require that data, and consider requiring explicit consent for them.
10Monitoring, Logging, and Metrics
Watching how scopes are actually used in practice helps confirm the design is working as intended.
Scope Grant Frequency
Tracking how often each Optional scope is actually requested helps identify unused or overly niche scopes worth cleaning up.
Consent Approval Rate
A low approval rate on a consent screen may indicate users find a requested scope confusing or excessive.
Token Size Over Time
Growing token size can signal that too many claims are being included, worth reviewing against actual application needs.
Scope Assignment Audit
Periodically reviewing which clients have which scopes assigned helps catch overly broad Default scope assignments before they become a problem.
Because scope resolution happens as part of every login and token issuance, it naturally shows up in Keycloak’s event logs, giving administrators visibility into exactly which claims were granted to which application for any given login.
11Design Patterns and Anti-Patterns
A few tested habits for designing scopes well, and a few traps worth avoiding.
Pattern: Group Related Claims Into Purpose-Named Scopes
Create clearly named scopes like “billing-read” or “support-tools” rather than one giant, generic scope containing every possible claim.
Pattern: Keep Default Scopes Minimal
Reserve Default status for genuinely universal claims (like basic profile info), and use Optional scopes for anything more specific or sensitive.
Pattern: Reuse Built-in Scopes Where Possible
Lean on Keycloak’s existing “profile,” “email,” and “roles” scopes instead of recreating equivalent custom ones, keeping the realm’s scope list easier to manage.
Problem
Creating a separate, nearly identical custom scope for every single application instead of reusing shared, well-named scopes.
Why It’s Harmful
This leads to scope sprawl — dozens of overlapping, redundant scopes that are hard to audit and easy to misconfigure, undermining the whole point of having reusable definitions.
Correct Approach
Design a smaller number of well-thought-out, purpose-based scopes that can be shared across applications with similar needs, adding new ones only when a genuinely distinct need arises.
12Best Practices and Common Mistakes
A practical checklist for anyone designing or reviewing client scopes.
Name Scopes Clearly
Use descriptive names that make a scope’s purpose obvious at a glance, months or years later.
Review Assignments Periodically
Regularly check which clients have which scopes, catching outdated or overly broad assignments before they become a liability.
Document Custom Protocol Mappers
Keep clear notes on why a custom mapper was added and what claim it produces, so future administrators understand its purpose.
Test Token Contents After Changes
After editing a scope, inspect a freshly issued token to confirm the claims look exactly as expected.
Frequent mistakes include marking every scope as Default out of convenience, never auditing which applications have access to sensitive scopes, duplicating scopes instead of reusing existing ones, and forgetting that a scope change immediately affects every client that uses it.
13Real-World Examples
Seeing client scopes applied to real situations makes the concept concrete.
Standard Web Application
Uses the built-in “profile” and “email” scopes as Default, giving it just enough information to greet the user by name without requesting anything extra.
Internal Billing Dashboard
Has a custom “billing-access” scope assigned as Optional, requested only when the application specifically needs to view or manage invoice data.
Public-Facing Mobile App
Deliberately avoids requesting sensitive scopes like internal roles, keeping its tokens lean and reducing what would be exposed if a device were ever compromised.
Partner Integration with Consent
A third-party partner application requests an Optional scope exposing limited profile data, with a consent screen ensuring the user explicitly approves sharing that information.
14Frequently Asked Questions
Yes. A client scope is defined once at the realm level and can be assigned to as many client applications as needed, each independently deciding whether it’s Default or Optional for them.
A role represents what a user is permitted to do. A client scope controls what information — including, potentially, which roles — is exposed inside a token for a specific application. They’re related but solve different problems.
Not necessarily. Whether consent is shown depends on how the scope and client are configured — some Optional scopes can be granted silently, while others are explicitly marked to require user approval.
The change applies immediately to every client using that scope, since the definition lives centrally at the realm level rather than being duplicated per application.
Yes. Each protocol mapper inside a scope can be configured to add its claim to the ID token, the access token, or both, depending on where that information is actually needed.
Yes. Administrators can define entirely new client scopes with custom protocol mappers, tailored to whatever specific claims an organization’s applications require beyond the built-in options.
15Summary and Key Takeaways
Client scopes in Keycloak are the mechanism that decides exactly what claims and permissions end up inside a token for any given application, built directly on the industry-standard OAuth 2.0 and OpenID Connect concept of “scope.” Defined once at the realm level and made up of protocol mappers that translate user data into token claims, they can be reused across many applications, marked as Default for information every login should include, or Optional for information only granted when specifically requested — sometimes with the user’s explicit consent. Used thoughtfully, client scopes let an organization apply the principle of least privilege to every token it issues, ensuring each application receives exactly the information it needs and nothing more. Used carelessly, they can either expose more data than intended or sprawl into an unmanageable pile of overlapping, redundant definitions.
Key Takeaways
- A client scope is a reusable bundle controlling what claims a token contains. — Defined once, it can be attached to many applications.
- Protocol mappers are the rules that turn user data into actual claims. — Each mapper inside a scope produces one specific piece of information in the token.
- Default scopes are always included; Optional scopes must be requested. — This distinction lets the same scope behave differently across different applications.
- Client scopes support least privilege by design. — Each application can be limited to exactly the claims it genuinely needs.
- Scopes live at the realm level, not duplicated per client. — Editing a shared scope updates every application using it at once.
- Consent screens add transparency for sensitive Optional scopes. — Users can knowingly approve what information is being shared.
- Well-named, purpose-based scopes avoid sprawl. — Reusing shared scopes beats creating a near-identical one for every new application.