Role Mappers
Map PDC default roles to AW Custom Roles ..
Role Mappers
In this hands-on workshop, you'll learn how to configure Role Mappers in Keycloak to complete the critical bridge between identity management and data governance. We'll walk through configuring User Realm Role and Group Membership mappers that automatically include your Adventure Works custom roles in JWT tokens, enabling PDC to make proper authorization decisions based on complete identity context.
By the end of this workshop, you will be able to:
Configure User Realm Role mappers to include custom roles in JWT tokens
Set up Group Membership mappers for organizational hierarchy visibility
Understand the critical role of mappers in bridging WHO (Keycloak identity) and WHAT (PDC permissions)
Create the complete authentication-to-authorization pipeline for enterprise data governance
Troubleshoot missing role information in JWT tokens
Enable automatic role inheritance through proper mapper configuration
Establish scalable identity federation that supports complex organizational structures
The Critical Integration Challenge This Solves:
Keycloak knows about Adventure Works roles (
aw-sales-analyst,aw-data-steward, etc.)PDC needs to know about these roles to make authorization decisions
JWT tokens are the bridge between them, but custom roles aren't included by default
Role Mappers solve this by automatically including realm roles and group memberships in authentication tokens
Workshop Mapper Configuration: You'll create two essential mappers:
AdventureWorks-Realm-Rolesmapper for custom role inclusionAdventureWorks-Groupsmapper for organizational hierarchy context
This workshop completes the WHO + WHAT equation, ensuring that when users authenticate, PDC receives complete identity context to make sophisticated data governance decisions based on both functional permissions and domain-specific access rights.
Keycloak Role Mappers
Keycloak doesn't provide PDC default roles out of the box. The roles like Admin, Data_Steward, and Business_User in your realm are custom roles that were specifically created for your PDC application. Keycloak only provides basic built-in roles like offline_access and client management roles.
Role mapping is needed because it bridges authentication and authorization. When a user logs in, Keycloak authenticates them and issues a JWT token containing their assigned roles. PDC then reads these roles from the token and needs to understand what permissions to grant. For example, if someone has the aw-sales-analyst role, PDC needs to know that means "grant access to sales dashboards and customer data."
You need both functional and domain-specific roles working together. PDC functional roles like Business_User determine what features of the application you can use (dashboards, admin panels, etc.). Your custom AdventureWorks roles like aw-sales-analyst determine what data domains you can access (sales data, HR data, etc.). The combination gives users complete, appropriate permissions.
The mapping happens in PDC's configuration, not Keycloak. Keycloak's job is just to put the right roles in the JWT token. PDC reads those roles and maps them to specific application permissions. That's why you assign both types of roles to your groups - so users get the complete permission set they need when they authenticate.
Sarah Johnson's Journey:
Sarah logs into PDC
Keycloak checks: "Sarah is in Sales_Analysts group, which has aw-sales-analyst role"
Mapper activates: "I need to include aw-sales-analyst in the token"
JWT created with:
PDC receives token and thinks: "Ah! Sarah has aw-sales-analyst role, so I'll give her Data User permissions and add her to Sales Analytics community"
Keycloak Clients
Clients in Keycloak represent applications or services that need to authenticate users. Each client has a unique Client ID and represents a trust relationship between Keycloak and an application. When a user tries to access an application (like PDC), the application redirects them to Keycloak for authentication, then Keycloak redirects back to the application with an authentication token.
Clients configure how this flow works - what URLs are allowed for redirects, what type of authentication flow to use (like standard web flow or direct grants), and what scopes/claims should be included in the tokens. In your realm, you have clients like pdc-client (your main PDC application), admin-cli (for API access), and account (for user self-service), each configured for their specific authentication needs.
Log into Keycloak:
Username: admin
Password: admin
Ensure you select the Pentaho Data Catalog Realm.
In the Left Menu > Select: Clients
Search and click: pdc-client
Click: Client Scopes tab
What is Client Scope?
Change hint typeClient scopes in Keycloak define what information (claims) gets included in the tokens issued to applications. They act like templates that bundle together related user attributes, roles, and permissions that applications need.For example, the "profile" scope includes claims like name, username, and email, while the "roles" scope includes the user's role assignments. When a client requests a token, it specifies which scopes it needs, and Keycloak only includes those specific claims in the token - this follows the principle of least privilege by ensuring applications only get the user data they actually require.You can assign scopes as either "default" (automatically included) or "optional" (only included when specifically requested), allowing fine-grained control over what information each application receives about authenticated users.
Click: pdc-client-dedicated
Why set pdc-client- dedicated scope?
The "pdc-client-dedicated" scope is a client-specific scope created exclusively for your PDC application. This dedicated scope contains custom protocol mappers and claims that are specifically tailored for PDC's needs - such as the AdventureWorks group mappings, realm roles, tenant information, and other PDC-specific data that wouldn't be relevant to other applications.
You set this scope to ensure PDC gets exactly the claims it needs without affecting other clients. Instead of modifying the standard scopes (like "profile" or "roles") that other applications might use, the dedicated scope isolates PDC's requirements. This means you can include specialized mappings like your AdventureWorks organizational groups, compliance attributes, and data domain permissions without those claims appearing in tokens for other applications that don't need them.
It follows security best practices by implementing scope isolation. Each client only receives the specific claims it requires for its functionality, reducing token size and limiting data exposure. If you later add other applications to your realm, they won't accidentally receive PDC-specific claims, and changes to PDC's token requirements won't impact other applications.
Click: Mappers tab
Click Add Mapper → By Configuration.
What's the difference between 'From predefined mappers' and 'By configuration'?
"From predefined mappers" gives you pre-built, common protocol mappers that Keycloak provides out-of-the-box. These are standard mappers for typical claims like username, email, roles, groups, and other common user attributes. You simply select the ones you need from a list - for example, "User Realm Role" mapper automatically includes the user's realm roles in the token, or "User Email" mapper includes their email address.
"By configuration" lets you create completely custom protocol mappers from scratch. You choose the mapper type (like "User Attribute Mapper" or "Hardcoded Claim Mapper") and then manually configure all the details - what user attribute to read, what claim name to use in the token, whether it goes in ID tokens or access tokens, etc. This gives you full control to create specialized mappings that don't exist in the predefined options.
Use predefined mappers for standard claims, and custom configuration for specialized needs. For your PDC setup, you'd use predefined mappers for common things like email and basic roles, but you'd use custom configuration for specialized mappings like your Adventure Works compliance attributes, tenant information, or specific data domain permissions that are unique to your organization's requirements.
Click: User Realm Role.
Select the following options:
Name
AdventureWorks-Realm-Roles
Realm Role prefix
Leave blank
Multivalued
✅ ON
Token Claim Name
realm_roles
Claim JSON Type
String
Add to ID Token
✅ ON
Add to Access Token
✅ ON
Add to Userinfo
✅ ON
Click: Save.
Repeat the workflow to add: 'Group Membership' mapper:
Select the following options:
Name
AdventureWorks-Groups
Token Claim Name
groups
Full group path
✅ ON
Add to ID Token
✅ ON
Add to Access Token
✅ ON
Add to Userinfo
✅ ON
Click: Save.
As a result of these 2 mappers the JWT token
✅ AdventureWorks-Realm-Roles (includes user's roles)
✅ AdventureWorks-Groups (includes user's group membership)
Combined JWT Token Result:
When Sarah Johnson logs in, the token will contain:
Quick review: Its pretty straightforward to map an Organization to Groups in Keycloak. You just keep adding 'Child Groups' to the relevant 'Parent Group'. If Keycloak is your main authentication mechanism, you may need to create specific Roles that are defined by Attributes - key / value pairs, for example: "data_classification_access": ["public", "internal", "confidential"]
The Role is then added to the specific Group - bear in mind inheritance.
The final part is to 'map' the bridge between the specific custom user roles & the AW Group > default-pdc-roles in the PDC Realm. The result is once we've added our users to the relevant AW Group and AW custom role, which is also authorized in the PDC realm, the user has access to the PDC assets. Which PDC assets is now determined by mapping the PDC Community to a PDC default role. Permissions & Scope fine tune access to which PDC assets. Phew..!
Last updated
Was this helpful?