Pentaho Academy Beta site ..
Start your 30-day Pentaho Enterprise Evaluation ..

Role Mappers

Map PDC default roles to AW Custom Roles ..

Role Mappers

Why do we need to configure Role Mappers .. What issue does this solve?

This part is crucial .. It completes the picture:

WHO (Identity + Organizational Structure) + WHAT (PDC Data Governance + Communities)

  • Keycloak knows about Adventure Works roles (aw-sales-analyst, aw-data-steward, etc.)

  • PDC needs to know about these Roles - mapped to default PDC Roles - to make authorization decisions

  • JWT tokens are the bridge between them - but by default, custom roles aren't included ..

The User Realm Role Mapper automatically includes a user's realm roles in JWT tokens sent to PDC.

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:

  1. Sarah logs into PDC

  2. Keycloak checks: "Sarah is in Sales_Analysts group, which has aw-sales-analyst role"

  3. Mapper activates: "I need to include aw-sales-analyst in the token"

  4. JWT created with:

{
  "sub": "sarah-uuid",
  "preferred_username": "sarah.johnson",
  "realm_roles": ["aw-sales-analyst"],
  "groups": ["/AdventureWorks_Organization/Sales_Division/Sales_Analysts"]
}

  1. 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.

  1. Log into Keycloak:

https://pdc.pentaho.lab/keycloak/adminpdc.pentaho.lab

Username: admin

Password: admin

Ensure you select the Pentaho Data Catalog Realm.

  1. In the Left Menu, Select: Clients

  2. Search and click: pdc-client

pdc-client

  1. Add Client Scope Mappers

  2. 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.

Set the Client scope

  1. Click: pdc-client-dedicated

Set pdc-client-dedicated scope
Why set pdc-client- dedicated scope?

The "pdc-client-dedicated" scope is a client-specific scope created exclusively for your PDC application. Looking at your realm configuration, this dedicated scope likely 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.

  1. Click Mappers tab

Select: By configuration

  1. 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.

  1. Click: User Realm Role.

By Configuration mappers

  1. Select the following options:

Configuration
Value

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

  1. Click Save.

Add realm-roles mapper

  1. Repeat the workflow to add: 'Group Membership' mapper:

  2. Select the following options:

Configuration
Value

Name

AdventureWorks-Groups

Realm Role prefix

Leave blank

Multivalued

✅ ON

Token Claim Name

groups

Full group path

✅ ON

Add to ID Token

✅ ON

Add to Access Token

✅ ON

Add to Userinfo

✅ ON

Add groups mapper

  1. 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:

{
  "preferred_username": "sarah.johnson",
  "realm_access": {
    "roles": ["aw-sales-analyst","default-roles-pdc"]
  },
  "realm_roles": ["aw-sales-analyst"],
  "groups": ["/AdventureWorks_Organization/Sales_Division/Sales_Analysts"]
}
PreviousAW Roles to GroupsNextAW Users

Last updated

Was this helpful?