如何通过Keycloak JavaScript适配器获取客户端角色自定义属性？

Alright, let's get those client role attributes showing up in your token. The problem here is that Keycloak doesn’t automatically include custom role attributes in access/ID tokens by default—you need to set up a custom mapper to pull those values into the token claims. Here’s exactly how to do it, tailored to your special_agent role and its approve_leave/raise_leave attributes:

Step 1: Navigate to Your Client’s Mappers #

1. Log into your Keycloak admin console, go to your target Realm.
2. Select the client you’re using for authentication (the one where you defined the special_agent role).
3. Switch to the Mappers tab, then click Create to make a new mapper.

Option 1: Map Individual Role Attributes (Simple) #

If you want to add each attribute as a separate claim in the token:

• Name: Pick something descriptive, like Special Agent - Approve Leave
• Mapper Type: Select User Client Role Attribute
• Client ID: Choose the client that owns the special_agent role (this should be the same client you’re working in)
• Role: Select special_agent from the dropdown
• Role Attribute Name: Enter approve_leave (repeat this entire step for raise_leave to add that attribute too)
• Token Claim Name: You can use the same name as the attribute (approve_leave) or customize it
• Claim JSON Type: Match your attribute’s type (e.g., Boolean if it’s a true/false value, String if it’s text)
• Check the boxes: Add to ID token, Add to access token, and Add to userinfo (whichever you need for your app)
• Click Save

Repeat this process to create a second mapper for the raise_leave attribute.

Option 2: Map All Role Attributes at Once (Cleaner) #

If you want to bundle all attributes for the special_agent role into a single claim, use a Script Mapper:

• Name: Special Agent Role Attributes Bundle
• Mapper Type: Select Script Mapper
• Script Language: Choose JavaScript
• Script: Paste this code to collect all attributes for the special_agent role and add them to a single claim:

  // Get the special_agent role for the current client
  var specialAgentRole = user.getClientRole(client.getId(), "special_agent");
  if (specialAgentRole) {
      // Extract all custom attributes from the role
      var roleAttributes = specialAgentRole.getAttributes();
      // Add the attributes to the token under a custom claim
      token.setClaim("special_agent_attributes", roleAttributes);
  }
  

• Check the boxes: Add to ID token, Add to access token, Add to userinfo
• Click Save

Option 3: Map Attributes for All Client Roles (Comprehensive) #

If you ever need to pull attributes for all client roles assigned to the user, use this script mapper instead:

var roleAttributes = {};
// Get all client roles assigned to the user
var clientRoles = user.getClientRolesStream(client.getId()).collect(Collectors.toList());

clientRoles.forEach(function(role) {
    var attrs = role.getAttributes();
    if (Object.keys(attrs).length > 0) {
        roleAttributes[role.getName()] = attrs;
    }
});

// Add all role attributes to the token
token.setClaim("client_role_attributes", roleAttributes);

Step 3: Test the Changes #

• Log out of your app completely, then log back in (old tokens won’t have the new claims).
• Now check keycloak.tokenParsed—you should see your custom attributes either as individual claims (Option 1) or under a bundled claim like special_agent_attributes (Option 2/3).

Quick Troubleshooting Tips #

• Make sure your client’s Full Scope Allowed is enabled (or that you’ve added the roles scope to your client’s default scopes if it’s disabled).
• Double-check that you selected the correct Client ID and Role in the mapper configuration—mixing these up is a common mistake.
• If attributes are showing up as strings when they should be booleans/numbers, verify the Claim JSON Type in your mapper matches the attribute’s actual type in Keycloak.

内容的提问来源于stack exchange，提问作者Sahil Khanna