Client Scopes
What is a client scope?
Section titled “What is a client scope?”A client scope is a named, reusable bundle of mappers — and optionally audience or resource restrictions. It lets you define a set of claims once and attach it to multiple clients. Instead of configuring the same mappers on every client individually, you configure them once on a scope and assign the scope to many clients.
Think of a client scope as a named package that says: “when this scope is requested, add these claims to the token.”
Default vs optional scopes
Section titled “Default vs optional scopes”Client scopes come in two types:
Default scopes are always included in every token issued by the client, regardless of what the application requests. The client does not need to ask for them — they are on by default.
Optional scopes are only included when the authorization request explicitly asks for them via the scope request parameter. If the client does not request an optional scope, its claims do not appear in the token. This keeps tokens small and avoids leaking unnecessary information.
Built-in scopes
Section titled “Built-in scopes”Keycloak ships with a set of built-in client scopes that cover the most common needs:
| Scope | Claims added |
|---|---|
openid | Required for OIDC. Signals that the response is an ID token. |
profile | name, given_name, family_name, preferred_username |
email | email, email_verified |
roles | realm_access, resource_access |
address | address (structured postal address) |
phone | phone_number, phone_number_verified |
offline_access | Grants a refresh token that persists beyond the normal SSO session. |
microprofile-jwt | Adds claims for MicroProfile JWT compatibility. |
Assigning an optional scope to a client
Section titled “Assigning an optional scope to a client”- In the admin console, navigate to Clients and select your client.
- Click the Client scopes tab.
- You will see two sections: Assigned client scopes and Setup. The table shows scopes with their type (Default or Optional).
- To add a scope, click Add client scope (top-right of the assigned list).
- Select the scope name from the list, choose Default or Optional, and click Add.
- To request an optional scope at login time, include it in the
scopeparameter of the authorization request:scope=openid profile email address
Creating a custom client scope
Section titled “Creating a custom client scope”- In the left sidebar, click Client scopes.
- Click Create client scope (top-right).
- Enter a Name (e.g.,
orders:read) and set Type to Optional. - Click Save. You will land on the scope’s detail page with tabs: Settings, Mappers, Scope, Evaluate.
- Add mappers in the Mappers tab (see the Protocol Mappers lesson).
- Assign the scope to your client as described above.
Authorization request with scope parameter
Section titled “Authorization request with scope parameter”When requesting an optional scope, include it in the scope query parameter of the authorization request:
https://auth.example.com/realms/my-app/protocol/openid-connect/auth?client_id=my-app-frontend&response_type=code&redirect_uri=https://app.example.com/callback&scope=openid%20profile%20email%20addressThe %20 characters are URL-encoded spaces. Each scope name is space-separated (or %20-separated in the URL). Keycloak will only include the claims for the scopes listed here — and only if those scopes are assigned to the client (default or optional).