Learn Keycloak - OIDC Claims & User Profile

#Introduction

In episode 9 you saw the ID token containing claims like name and email. Episode 10 opens the hood: where those claims come from, what standard claims exist, how to add custom claims via user attributes and protocol mappers, and how to choose a strategy — load everything into the token, or fetch it from the UserInfo endpoint.

#Standard OIDC Claims

OIDC defines a set of standard claims grouped by category:

• Profile claims — name, given_name, family_name, picture, and others.
• Email claims — email and email_verified.
• Address claims — address containing formatted, street_address, locality, region, postal_code, and country.
• Phone claims — phone_number and phone_number_verified.

These claims are mapped from Keycloak's user data by built-in protocol mappers already attached to the profile, email, address, and phone client scopes.

#From User Attributes to Claims

User data in Keycloak is stored in two layers:

• Built-in attributes — standard fields like first name, last name, and email.
• User attributes — custom fields created by admins, e.g. department or employee_id.

Custom attributes are added on the user page, then elevated into claims via a mapper:

1. Create a user attribute in the Attributes tab on the user page.
2. Create a protocol mapper of type User Attribute in the client scope or client.
3. Set the mapper name, the claim name, and which token carries it.

{
  "sub": "9c4d5e6f-...",
  "preferred_username": "budi",
  "department": "engineering",
  "employee_id": "EMP-1042"
}

Above, department and employee_id are custom claims resulting from user attribute mapping. Applications can then read these claims for business logic — e.g. deciding which menu to show.

#Protocol Mappers

A protocol mapper is the bridge between Keycloak data and tokens. Keycloak provides several mapper types:

Mappers can be attached to a client scope (applies to all clients using that scope) or directly to a client (only that client). Choose the client scope when many clients need the same claim.

#Hardcoded Claims and JavaScript Mappers

Two mappers often overlooked despite being practical:

• Hardcoded claim — inserts a constant value without reading user data. Great for tagging a version or environment, e.g. "tier": "gold" for all tokens from one client.
• JavaScript mapper — runs a small script to transform one or more attributes into a single claim. Example: combining firstName and lastName into display_name, or reformatting a number.

const fullName = user.getFirstName() + " " + user.getLastName();
token.setClaim("display_name", fullName);

Use the JavaScript mapper carefully and only when the built-in mappers aren't enough — a broken script can slow down token issuance or introduce bugs that are hard to trace.

#Claims Mapping

Claim mapping isn't only about attributes. Four mapping patterns are common in production:

• Client scope mappers — attach claims to a scope so they apply to many clients at once.
• Audience mapper — adds an aud value so the token can be used across more than one resource server, or conversely narrows the audience.
• Role mapper — controls how roles (realm and client) are represented in the token.
• Group mapper — maps user group membership into a claim, useful for organizational attribution.

#ID Token vs Access Token vs UserInfo

Three different claim paths, with different consequences:

To read a profile via UserInfo, the application simply calls its endpoint with the access token:

curl -s -H "Authorization: Bearer eyJhbGciOi..." \
  "https://kc.example.com/realms/my-realm/protocol/openid-connect/userinfo"

protocol/openid-connect/userinfo returns the claims allowed by the scopes the user approved — the opposite of the ID token, whose contents are locked in once the token is issued.

#Claims Strategy

Choosing where to place claims is a design decision with three considerations:

• ID token vs UserInfo — keep claims needed for first-page render in the ID token; pull additional data from the UserInfo endpoint only when needed.
• Performance — every claim enlarges the token, and the access token is sent with every API request. Don't load data that isn't used on every call.
• Privacy — avoid putting sensitive data like national ID numbers or medical details in tokens. Tokens can appear in logs and be stored at various layers; keep tokens lean wherever possible.

Size is also a cost: bloated tokens slow requests and waste memory. As a rule of thumb, load into the token only what's truly used per request; the rest goes through the UserInfo endpoint.

#Closing

Episode 10 covered OIDC claims and the user profile: standard claims from profile to phone, user attributes as a source of custom data, the protocol mapper types including hardcoded and JavaScript mappers, claims mapping patterns, and strategies for balancing the ID token, access token, and UserInfo endpoint.

Key takeaways:

• Claims start from data and are elevated by mappers — user attributes become claims via protocol mappers.
• Tokens must be lean — load only the essentials, pull the rest from UserInfo.
• Tokens can't be revoked retroactively — don't store changing decisions inside tokens.
• Client scope mappers win for reuse — one scope, many clients.

In the next episode (episode 11), you'll learn session management — how Keycloak tracks login sessions across many applications at once, how single logout works, and how to monitor and revoke sessions from the admin console.