A Client Scope in Keycloak is a named, reusable bundle of configuration — primarily Protocol Mappers (rules that decide which claims get written into a token) and, in some cases, Role Scope Mappings — that can be attached to one or many Clients. Instead of configuring “include the user’s email in the token” separately for every single application, an administrator defines that behavior once, inside a Client Scope named something like email, and then simply attaches that scope to whichever Clients need it.

Once a Client Scope exists, it can be assigned to a specific Client in one of two ways, and this is exactly where our central distinction lives:

Keycloak’s Built-In Client Scopes

Out of the box, a fresh Keycloak realm ships with several ready-made Client Scopes, already sensibly categorized. Commonly included as Default scopes are profile (basic identity fields like name), email, roles (the role claims discussed in earlier guides), web-origins (CORS-related configuration), and acr (authentication context class reference, describing how strongly the user authenticated). Commonly included as Optional scopes are offline_access (long-lived refresh capability), address, phone, and microprofile-jwt (a claim format tailored for certain Java microservice frameworks).

This default categorization reflects a sensible general principle: information nearly every application needs (basic profile, email, roles) is bundled automatically, while more specialized or privacy-sensitive information (a phone number, a physical address, long-lived offline access) is only included when an application specifically asks for it and, depending on configuration, the user explicitly consents to sharing it.

Why This Distinction Exists At All

It would be technically possible for Keycloak to simply include every conceivable piece of user data in every token, all the time. The Default/Optional split exists instead because of three converging concerns: token size (larger tokens cost more bandwidth and parsing time on every single request), data minimization (a well-designed system shares only what’s actually needed, reducing exposure if a token is ever intercepted), and user consent (certain categories of personal data — like a phone number or physical address — are often subject to explicit consent requirements that shouldn’t apply to basic login information).

flowchart TB
    Realm["Realm: Client Scopes Catalog"] --> ScopeA["Client Scope: profile"]
    Realm --> ScopeB["Client Scope: email"]
    Realm --> ScopeC["Client Scope: phone"]
    Realm --> ScopeD["Client Scope: offline_access"]
    ClientX["Client: Web App"] -->|"Default"| ScopeA
    ClientX -->|"Default"| ScopeB
    ClientX -->|"Optional"| ScopeC
    ClientX -->|"Optional"| ScopeD
    ScopeA --> MapperA["Protocol Mappers"]
    ScopeC --> MapperC["Protocol Mappers"]
    MapperA --> Token["Issued Token"]
    MapperC -.->|"only if requested"| Token
    

Let’s unpack each labeled piece in this architecture.

The Realm-Level Client Scope Catalog

Every Client Scope is defined once, at the realm level, inside a central catalog visible under the realm’s “Client Scopes” section in the Admin Console. This is where the scope’s name, description, and attached Protocol Mappers live — completely independent of any specific Client until it’s assigned to one.

Protocol Mappers Inside a Client Scope

Each Client Scope typically bundles one or more Protocol Mappers — the actual rules that pull specific pieces of data (a user attribute, a role, a group membership) and write them into a token claim with a specific name and format. A single Client Scope like profile might bundle several mappers together: one for given_name, one for family_name, one for preferred_username, and so on.

Per-Client Assignment

Each individual Client has its own configuration listing which Client Scopes are assigned to it, and — critically — whether each assignment is Default or Optional. This is managed in the Client Scopes tab of a specific Client’s settings in the Admin Console, and it’s entirely independent from how that same Client Scope might be assigned to a different Client.

Role Scope Mappings

Beyond claims like email or phone number, Client Scopes can also carry Role Scope Mappings — restricting which of a Client’s available roles are actually eligible to appear in tokens issued under that scope. This gives administrators a second axis of control: not just “which claims appear” but “which roles are even allowed to surface” for a given scope.

The Full Scope Allowed Toggle

Separately from this model entirely, each Client also has a Full Scope Allowed setting. When enabled, it bypasses fine-grained scope-based role filtering altogether, granting the Client access to every realm and client role the user holds, regardless of Client Scope configuration. This is a powerful but coarse setting, discussed further in the Design Patterns chapter, and is generally discouraged for production Clients that don’t genuinely need such broad access.

The scope Parameter in the Authorization Request

When an application initiates a login, it typically includes a scope parameter in its request to Keycloak — a space-separated list of scope names it wants included, such as openid profile email phone. Every OpenID Connect request implicitly includes the special openid scope, which triggers ID Token issuance in the first place.

How Default Scopes Are Resolved

Regardless of what the application explicitly requests in its scope parameter, every Client Scope marked as Default for that Client is automatically included in the resolution process. There’s no need for the requesting application to name them — Keycloak applies them unconditionally as part of that Client’s baseline token contract.

How Optional Scopes Are Resolved

A Client Scope marked as Optional is only included if its exact name appears in the incoming scope parameter of that specific authorization request. If the application never requests phone, the phone Client Scope’s mappers simply never run for that login, and no phone-related claims appear in the resulting token — even though the scope is technically available to that Client if it chose to ask for it.

Mapper Execution and Claim Assembly

Once Keycloak has determined the final, resolved set of scopes for a given request — combining every Default scope with whichever Optional scopes were explicitly requested — it runs every Protocol Mapper attached to each of those resolved scopes, writing their resulting claims into the appropriate token (ID Token, Access Token, or both, depending on each mapper’s own configuration).

The Resulting scope Claim

Interestingly, the final set of resolved scopes is itself reported back inside the issued token, typically as a scope claim — giving both the client application and any resource server inspecting the token a clear, explicit record of exactly which scopes were actually granted for that specific token, Default and Optional alike.

flowchart LR
    A["1. App builds authorization request with scope parameter"] --> B["2. Keycloak identifies the Client"]
    B --> C["3. Every Default Client Scope for this Client is included"]
    C --> D["4. Requested scopes checked against Client's assigned Optional scopes"]
    D --> E["5. Matching Optional scopes added to resolved set"]
    E --> F["6. Consent screen shown if required for Optional scopes"]
    F --> G["7. Protocol Mappers for all resolved scopes executed"]
    G --> H["8. Token issued with resulting claims + scope claim"]
    

It’s worth noting this resolution happens fresh on every login and every token refresh — an application that starts requesting an additional Optional scope it hadn’t asked for before will simply begin receiving that scope’s claims on its next fresh authentication, without any change needed on Keycloak’s configuration side, as long as the scope was already assigned to that Client as Optional.

Data Minimization as a Security Control

Keeping sensitive or rarely needed claims as Optional — rather than Default — reduces the amount of personal data present in every single token, directly shrinking what’s exposed if any individual token is ever intercepted, logged inappropriately, or leaked.

Review Default Scopes for Over-Sharing

It’s worth periodically reviewing exactly which claims are bundled into each Client’s Default scopes — a scope that made sense as Default early in an application’s life might, as the application’s scope of use grows, actually warrant being downgraded to Optional and requested only where genuinely needed.

Consent as a Transparency Mechanism

Requiring user consent for Optional scopes that carry more sensitive claims gives users direct visibility into what a specific application is requesting beyond the baseline — an important transparency and trust-building mechanism, particularly for third-party or less-familiar applications connecting to a realm.

Role Scope Mappings as an Additional Filter

Beyond claim-level control, using Role Scope Mappings within a Client Scope to restrict which roles can even appear in that Client’s tokens provides an extra layer of defense — ensuring that even if a role is broadly assigned to a user elsewhere, it doesn’t automatically leak into every application’s token unless that specific Client genuinely needs visibility into it.

Tracking Token Size Over Time

As Client Scopes are added or reconfigured, it’s worth periodically monitoring the size of issued tokens for high-traffic Clients — a steadily growing token size can indicate scope creep, where claims that are rarely used by the application are nonetheless being included in every single request.

Auditing Scope Requests via Events Logging

Keycloak’s Events Logging system (covered in a companion guide) can be reviewed to understand which scopes applications are actually requesting in practice, helping identify Optional scopes that are consistently requested (and might be better promoted to Default for that Client) versus scopes that are rarely or never used despite being configured.

Consent Screen Analytics

For realms with consent enabled, tracking how often users decline or hesitate on a consent screen listing a specific Optional scope can surface user-experience friction — if a particular scope’s request consistently causes drop-off, it may be worth reconsidering whether that data is genuinely necessary for the flow it supports.

Alerting on Unexpected Scope Requests

In higher-security environments, monitoring for authorization requests attempting to request scope names that aren’t assigned to the requesting Client at all can be a useful, low-noise signal — while such requests are simply ignored rather than granted, a pattern of them might indicate misconfigured or misbehaving client integrations worth investigating.

Good Pattern: Default for Baseline, Optional for Feature-Specific Data

Keep Default scopes limited to what nearly every part of an application genuinely needs on every login — identity and basic profile information, typically — while pushing anything tied to a specific feature (like requesting a phone number only for an SMS-notification opt-in flow) into an Optional scope requested only where that feature is actually used.

Good Pattern: Mirror Scope Names to Their OpenID Connect Meaning

Where possible, align custom Client Scope names and behavior with the standard OpenID Connect scope conventions (like profile, email, phone) rather than inventing entirely bespoke naming — this keeps integrations predictable for developers already familiar with the broader OAuth 2.0 and OpenID Connect ecosystem.

Good Pattern: Separate Scopes by Sensitivity, Not Just Feature

Group claims into Client Scopes based partly on how sensitive they are, not purely on which feature uses them — this makes it easier to apply consent requirements or stricter review specifically to the more sensitive scopes without needing to touch less sensitive, more universally needed ones.

Common Mistakes to Avoid

• Assuming a scope is Default when it’s actually Optional: A developer integrating with a new Client may reasonably assume claims they’ve seen in another application’s tokens will “just be there,” without realizing that Client configured the scope differently.
• Not reviewing scope assignments during Client provisioning: New Clients cloned from a template may inherit Default/Optional assignments that don’t actually fit their specific use case.
• Overloading a single Client Scope with unrelated mappers: Bundling unrelated claims into one large scope makes it harder to selectively include only what’s genuinely needed for a specific use case.
• Ignoring consent screen wording: Poorly named or described Optional scopes can confuse users during consent, undermining the very transparency the consent mechanism is meant to provide.