Keycloak Client Scopes: Default, Optional & Dedicated Explained

Keycloak client scopes group protocol mappers and role scope mappings that control what information can appear in tokens. Shared client scopes can be linked to multiple clients. Each OIDC client also has client-specific mappers and role scope mappings, which the Admin Console exposes through its non-shareable Dedicated scope.

A shared scope linked as Default is applied automatically when Keycloak issues tokens for that client. The same shared scope linked as Optional applies only when the client requests it using the OIDC scope parameter.

For example, profile and email are commonly linked as Default scopes, while phone can be linked as Optional. In the lab below, requesting scope=openid phone adds phone_number and phone_number_verified to the access token.

This guide explains Default and Optional scope assignment, how the per-client Dedicated scope differs from shared scopes, how to create and link a scope, and how to verify the resulting JWT claims. The examples use OIDC public client orders-api and test user tokenuser in the golinuxcloud realm. To reproduce the curl command token examples, enable Direct access grants on the client. The password grant is used here only to make scope testing easy from the command line. For full client registration steps, see Keycloak clients explained.

Four meanings of "scope" in Keycloak

Keycloak uses scope in more than one sense. The table below separates them so you do not open the wrong Admin Console screen.

This article is about client scopes. The other meanings appear only where they affect client-scope behavior.

What is a Keycloak client scope?

A client scope bundles configuration Keycloak applies when it builds OIDC tokens:

• Protocol mappers — map user attributes, roles, audiences, or hardcoded values into token claims
• Role scope mappings — restrict which of the user's roles are available when Keycloak builds tokens for the client
• Consent metadata — controls how a client scope is shown when Keycloak asks the user to approve requested access

Keycloak supports shared realm client scopes such as profile, roles, and phone. It also lets an OIDC client have its own protocol mappers and role scope mappings; the Admin Console exposes these through the {clientId}-dedicated scope. A client scope is the attachable container for shared scopes; a protocol mapper is one transform rule inside it. Editing a mapper under phone affects every client that links phone, not just orders-api.

Common OIDC mapper types inside scopes include:

• User attribute — map phoneNumber → phone_number
• User realm role — populate realm_access.roles
• User client role — populate resource_access.<clientId>.roles
• Hardcoded claim — static value such as tenant_id
• Audience — adjust aud for resource servers

Do not confuse a scope being applied with its name always appearing in the token's scope claim. The client scope setting Include in token scope controls whether Keycloak adds that scope name to the token's scope value. A default scope can still run its mappers when its name is omitted from scope.

  Client: orders-api
        │
        ├── Default scopes (applied automatically) ──► profile, email, lab-claims, roles, …
        │
        ├── Optional scopes (OIDC scope=) ──► phone, address, offline_access, …
        │
        └── orders-api-dedicated (per-client only)
                  └── protocol mapper lab-tenant-id ──► tenant_id claim

  Request flow:

  ┌───────────┐    scope param     ┌─────────────────┐    effective token    ┌──────────────┐
  │  Client   │ ────────────────►  │  Client scopes  │ ─── configuration ──► │ Access token │
  │ orders-api│                    │  linked to app  │                       │   (JWT)      │
  └───────────┘                    └─────────────────┘                       └──────────────┘

For deeper mapper configuration patterns, see Keycloak protocol mappers and custom claims.

Why does Keycloak use client scopes?

Without client scopes, you would configure the same token mappings separately for every application. If five applications all need the user's name, email address, and roles, repeating the same mapper configuration on five clients is hard to maintain.

A shared client scope lets you configure that token behavior once and link it to multiple clients:

                        ┌── storefront-web
  profile client scope ─┼── orders-api
                        └── support-portal

If you later change a mapper in the shared profile scope, linked clients use the updated configuration when that scope is applied.

Client scopes also let you control when that configuration runs:

• Default — apply it automatically for the client
• Optional — apply it only when the client requests that scope
• Dedicated — keep client-specific mappers and role scope mappings with one client instead of sharing them

For example, an application may always need basic profile and email claims but need a phone number only for a particular feature. Keep profile and email as Default scopes and phone as Optional, so phone-related claims are included only when phone is requested.

Default client scopes

A scope assigned to a client as Default is applied automatically whenever Keycloak issues tokens or assertions for that client. Default client scopes apply to both OIDC tokens and SAML assertions. Optional linking is OIDC-only.

For OIDC, default scope mappers run even when the client omits an explicit scope parameter in the token request. The built-in roles default scope is why many clients emit realm_access and resource_access without extra configuration.

After you link a custom scope as Default on orders-api, open Clients → orders-api → Client scopes and confirm it appears in the assigned list with type Default:

Typical default scopes on an OIDC client include:

• profile and email — name and email claims
• roles — realm and client role mappers
• acr — authentication context class reference metadata

Use a Default scope when its mappers and role mappings should apply automatically for that client without requiring an explicit scope request. Role scope mappings on a scope can still prevent that scope from applying to a particular user.

Optional client scopes

Optional scopes apply only when the OIDC client requests them in the scope parameter (authorization request or token request, depending on the grant). This pattern is OIDC-specific; SAML clients use attribute mappers differently.

Built-in optional scopes on orders-api include phone, address, offline_access, and microprofile-jwt. With phone linked as Optional, its mappers are applied only when the client requests phone in the scope parameter. If the user's phone attributes are populated and the mapper targets the access token, the resulting token can include phone_number and phone_number_verified.

Open Client scopes → phone → Mappers and confirm the User Attribute values on the built-in mappers before you set attributes on the user:

• phone number → claim phone_number (User Attribute phoneNumber)
• phone number verified → claim phone_number_verified (User Attribute phoneNumberVerified)

Set the matching attributes on tokenuser before you request the phone scope:

• phoneNumber = +1-555-0100
• phoneNumberVerified = true

If a mapper reads a custom user attribute such as phoneNumber, make sure the attribute exists on the user. With User Profile enabled, also check whether the attribute is declared there or whether your realm's unmanaged-attribute policy allows it. See Keycloak user attributes and User Profile for the full attribute workflow.

Request a token without phone in the scope parameter and decode the access token payload:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=tokenuser' -d 'password=TokenUser!2026' -d 'grant_type=password' -d 'client_id=orders-api' | python3 -c "import sys,json,base64; t=json.load(sys.stdin)['access_token']; p=t.split('.')[1]; p+='='*(-len(p)%4); c=json.loads(base64.urlsafe_b64decode(p)); print(json.dumps({k:c.get(k) for k in ('scope','phone_number','phone_number_verified')}, indent=2))"

Sample output without phone in the request:

{
  "scope": "profile email",
  "phone_number": null,
  "phone_number_verified": null
}

The token carries profile and email from default scopes. phone_number is absent because phone is optional and was not requested.

Add scope=openid phone to the same password grant:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=tokenuser' -d 'password=TokenUser!2026' -d 'grant_type=password' -d 'client_id=orders-api' -d 'scope=openid phone' | python3 -c "import sys,json,base64; t=json.load(sys.stdin)['access_token']; p=t.split('.')[1]; p+='='*(-len(p)%4); c=json.loads(base64.urlsafe_b64decode(p)); print(json.dumps({k:c.get(k) for k in ('scope','phone_number','phone_number_verified')}, indent=2))"

Sample output with optional phone requested:

{
  "scope": "openid phone profile email",
  "phone_number": "+1-555-0100",
  "phone_number_verified": true
}

The scope claim lists phone, and those two mappers added the claims shown above.

Create and assign a client scope

Creating and linking a scope is the core workflow most readers search for: build a scope, add a mapper, assign it to a client as Default or Optional, then verify the token.

A shared client scope such as lab-claims is created at the realm level first. You then link that same scope to individual clients as Default or Optional.

This walkthrough uses shared scope lab-claims, which maps user attribute department into claim department. Skip the create steps if the scope already exists in your realm.

Create scope lab-claims

1. Open Client scopes → Create client scope.
2. Set Name to lab-claims, protocol OpenID Connect, and save.
3. Open Mappers → Configure a new mapper → User Attribute.
4. Set Name to department-claim, User Attribute to department, Token Claim Name to department, and enable Add to access token.

At the realm level, lab-claims can exist without being a realm default or optional scope. None in the realm list means the scope is available but not automatically assigned to every new client:

None here does not mean the scope is unusable. It means Keycloak does not attach it automatically to newly created clients as a realm Default or realm Optional scope.

Assign the scope to orders-api

Before you link lab-claims, the client's assigned scope list does not include it:

Link the scope to the client:

1. Open Clients → orders-api → Client scopes.
2. Click Add client scope and select lab-claims.
3. Choose Default so the mapper runs automatically when Keycloak issues tokens for this client without an extra scope= parameter.

After assignment, lab-claims appears with type Default in the assigned list (see the screenshot in Default client scopes).

Request a token and read department:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=tokenuser' -d 'password=TokenUser!2026' -d 'grant_type=password' -d 'client_id=orders-api' | python3 -c "import sys,json,base64; t=json.load(sys.stdin)['access_token']; p=t.split('.')[1]; p+='='*(-len(p)%4); c=json.loads(base64.urlsafe_b64decode(p)); print(json.dumps({k:c.get(k) for k in ('scope','department')}, indent=2))"

Sample output with lab-claims linked as Default:

{
  "scope": "profile email",
  "department": "Platform Engineering"
}

department appears even though lab-claims is not listed in the scope claim, because this scope keeps Include in token scope off while still running its mappers as a default scope.

Test the same scope as Optional

Remove lab-claims from the client's Default list, then add it again through Add client scope → Optional.

Request a token without naming lab-claims in scope=:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=tokenuser' -d 'password=TokenUser!2026' -d 'grant_type=password' -d 'client_id=orders-api' | python3 -c "import sys,json,base64; t=json.load(sys.stdin)['access_token']; p=t.split('.')[1]; p+='='*(-len(p)%4); c=json.loads(base64.urlsafe_b64decode(p)); print(json.dumps({k:c.get(k) for k in ('scope','department')}, indent=2))"

Sample output when lab-claims is optional and not requested:

{
  "scope": "profile email",
  "department": null
}

Add scope=openid lab-claims:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=tokenuser' -d 'password=TokenUser!2026' -d 'grant_type=password' -d 'client_id=orders-api' -d 'scope=openid lab-claims' | python3 -c "import sys,json,base64; t=json.load(sys.stdin)['access_token']; p=t.split('.')[1]; p+='='*(-len(p)%4); c=json.loads(base64.urlsafe_b64decode(p)); print(json.dumps({k:c.get(k) for k in ('scope','department')}, indent=2))"

Sample output when the optional scope is requested:

{
  "scope": "openid profile email",
  "department": "Platform Engineering"
}

Notice that department appears even though lab-claims does not appear in the token's textual scope claim. Include in token scope remains disabled for lab-claims. Requesting an optional scope controls whether its configuration is applied; Include in token scope separately controls whether the scope name is written into the resulting scope claim.

Default scopes run automatically. Optional scopes run only when the client includes them in scope=. Link lab-claims back as Default on orders-api if you continue with the sections below.

Dedicated client scope

On an OIDC client, the Admin Console shows a dedicated client scope named {clientId}-dedicated on the Client scopes tab. For orders-api, the link reads orders-api-dedicated.

Dedicated scopes hold mappers and role scope mappings that belong to one client only. You cannot unlink this scope and attach it to a different client, and you cannot share it across the realm like profile or phone. In the Admin Console this appears as a dedicated scope, but internally its mappers and role scope mappings belong directly to the client; the dedicated scope is a UI abstraction.

Use a dedicated scope when:

• One application needs a claim no other client should receive
• You are prototyping a mapper before promoting it to a shared realm scope

Use a shared realm client scope when:

• Several clients need the same mapper configuration
• You want consent text and scope assignment managed in one place

Add hardcoded claim mapper lab-tenant-id on orders-api-dedicated:

1. Open Clients → orders-api → Client scopes.
2. Click the orders-api-dedicated link.
3. Open Mappers → Configure a new mapper → Hardcoded claim.
4. Set Name to lab-tenant-id, Token Claim Name to tenant_id, Claim value to golinuxcloud-lab, and enable Add to access token.

Request a fresh access token and read tenant_id:

curl -s -X POST 'http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=tokenuser' -d 'password=TokenUser!2026' -d 'grant_type=password' -d 'client_id=orders-api' | python3 -c "import sys,json,base64; t=json.load(sys.stdin)['access_token']; p=t.split('.')[1]; p+='='*(-len(p)%4); c=json.loads(base64.urlsafe_b64decode(p)); print('tenant_id:', c.get('tenant_id'))"

Sample output:

tenant_id: golinuxcloud-lab

Mappers and role scope mappings configured in the Dedicated scope apply directly to that client; the client does not request scope=orders-api-dedicated.

Realm default client scopes

Do not confuse realm default client scopes with a client's assigned default scopes. They operate at different layers.

Realm-level defaults seed new clients with profile, email, roles, and siblings. Changing a scope's realm-level Assigned type does not automatically change existing clients; it controls how that scope is linked when new clients are created. You still edit each client's Client scopes tab for one-off differences.

When a new client is missing claims that older clients have, compare both the realm default tabs and the per-client Assigned client scope lists.

Role scope mappings and missing roles

Client scopes can include role scope mappings that restrict which of the user's roles are available when Keycloak builds tokens for the client. When a scope defines role mappings, the user must hold at least one matching effective role. Otherwise Keycloak skips that scope — including its protocol mappers — and the scope name may be absent from the token's scope claim.

That is separate from assigning roles under Users → Role mapping. If a claim mapper runs but a role claim is missing, or Full scope allowed on the dedicated scope is limiting token roles, see Keycloak realm roles vs client roles for realm_access, resource_access, and token decode examples with the same orders-api lab client.

Evaluate client scopes and token claims

The Evaluate tab on a client's Client scopes screen simulates token output without running a full browser login flow. Pick a user, set a Scope parameter, and inspect generated access token, ID token, and UserInfo payloads.

Open Clients → orders-api → Client scopes → Evaluate. Select Users tokenuser. In this lab, the Scope parameter already contains openid; add phone so both appear as selected entries.

Scroll down on the same page to inspect the generated access token JSON. It should include phone_number, department, tenant_id, and the scope list you expect for that user and scope parameter.

Use Evaluate when a claim appears in Admin Console mappers but your application still sees an old payload. Compare generated JSON to a live token before chasing application-side caching.

Troubleshooting missing client scope claims

Summary

Keycloak client scopes group protocol mappers and role scope mappings that control what information can appear in tokens. Shared scopes link to clients as Default (applied automatically) or Optional (applied when requested in scope=). Each OIDC client also has client-specific configuration exposed through its Dedicated scope in the Admin Console.

When claims are missing, check the client's assigned scopes, whether optional scopes were requested in scope=, mapper Add to access token toggles, and role scope mappings on the linked scopes. Use Evaluate to inspect the effective token before you chase application-side caching. For role claim shape and Full scope allowed, use the realm roles guide linked above.

References

• Keycloak Server Administration Guide — Client scopes
• Keycloak Server Administration Guide — Protocol mappers
• OpenID Connect Core — scope values