Keycloak Protocol Mappers: Add Custom Claims to Tokens (2026)

Protocol mappers are how Keycloak injects custom information into tokens, and the surprising truth is that they don’t actually add claims to the token itself; they transform existing user attributes or roles into claims that the token endpoint then includes.

Let’s see this in action. Imagine we have a user, "alice," with an email alice@example.com and a custom user attribute department set to "Engineering." We want to add a department claim to our ID and Access tokens.

Here’s a simplified flow:

1. Client Request: A client requests a token for "alice."
2. Keycloak Processing: Keycloak authenticates "alice" and fetches her user information.
3. Protocol Mapper Execution: A configured protocol mapper intercepts this process. If we’ve set up a mapper to add the department attribute as a claim named department, Keycloak looks up "alice’s" department attribute.
4. Token Generation: Keycloak then constructs the ID and Access tokens, embedding the retrieved department: "Engineering" as a claim.

The Problem They Solve

OIDC and SAML tokens are often expected to carry specific user information beyond just identity. For instance, an application might need to know a user’s department, their roles within the system, or other custom attributes to make authorization decisions. Keycloak, by default, provides standard claims like sub, iss, aud, name, email, etc. Protocol mappers bridge the gap, allowing you to tailor the token content to your application’s specific requirements without modifying Keycloak’s core logic.

How They Work Internally

Keycloak’s token generation process involves several stages. When a token is requested, Keycloak gathers user information, applies authentication flows, and then enters the token mapping phase. Protocol mappers are plugins that hook into this phase. Each mapper type is designed to extract specific types of information from the user session or user profile and format it into a claim that adheres to the expected token format (JWT for OIDC, SAML assertions for SAML).

There are several built-in mapper types:

• User Attribute Protocol Mapper: This is the most common. It directly maps a user’s attribute (like department, employeeId) to a claim. You specify the user attribute name and the desired claim name.
• Role Name Protocol Mapper: Maps user roles (realm roles or client roles) to claims. You can choose to map the role name, the role ID, or a composite role name.
• Group Membership Protocol Mapper: Adds claims indicating which groups a user belongs to.
• Hardcoded Claim Protocol Mapper: Allows you to add static, predefined claims to every token issued for a specific client. Useful for flags or constant values.
• OIDC Groups Claim Protocol Mapper: A specialized mapper for adding group information in a format compatible with OIDC group claims.

Configuring a User Attribute Mapper

Let’s walk through adding the department claim.

1. Navigate to Client: In your Keycloak realm, go to "Clients" and select the client you want to configure (e.g., your web application).
2. Go to Mappers Tab: Click on the "Mappers" tab for that client.
3. Create New Mapper: Click "Create."
4. Select Mapper Type: Choose "User Attribute."
5. Configure:
   • Name: Department Claim (a descriptive name for your reference)
   • User Attribute: department (this is the exact name of the user attribute Keycloak stores)
   • Claim Name: department (this is how it will appear in the token)
   • Add to ID token: Yes
   • Add to Access token: Yes
   • Add to Userinfo: Yes (optional, but good practice for OIDC consistency)
6. Save: Click "Save."

Now, when "alice" logs in via this client and requests a token, the department claim with the value Engineering will be present.

Example Token Snippet (JWT)

{
  "sub": "...",
  "email": "alice@example.com",
  "department": "Engineering", // Our custom claim
  "iss": "http://localhost:8080/realms/myrealm",
  "aud": "my-client-id",
  // ... other standard claims
}

The surprising part is how flexible this is. You can create mappers that combine multiple user attributes, transform their values, or even inject claims based on complex logic by creating custom protocol mapper SPIs. For instance, you could map a user’s employeeId attribute to a claim named emp_id and simultaneously map their department attribute to a claim named user_dept.

The next concept you’ll likely encounter is how to manage fine-grained access control within Keycloak using these custom claims and roles, often by integrating with Authorization Services.