# Role Mappers

{% hint style="success" %}

#### 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-Roles` mapper for custom role inclusion
* `AdventureWorks-Groups` mapper 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.
{% endhint %}

<figure><img src="/files/beazFGwx22H9gKWQIDqs" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

#### 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.
{% endhint %}

**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:

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

5. 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"

***

{% hint style="info" %}

#### 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.&#x20;

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.
{% endhint %}

1. Log into Keycloak:

{% embed url="<https://pdc.pentaho.lab/keycloak/admin>" %}

Username: admin

Password: admin

{% hint style="danger" %}
Ensure you select the Pentaho Data Catalog Realm.
{% endhint %}

1. In the Left Menu > Select: Clients
2. Search and click: pdc-client

<figure><img src="/files/p1K7o3ZJp1IcvJw3kQyT" alt=""><figcaption><p>pdc-client</p></figcaption></figure>

3. Click: Client Scopes tab

<details>

<summary>What is Client Scope?</summary>

Change hint type**Client 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.

</details>

<figure><img src="/files/9MBFUYPPEDBQH3Kic7kV" alt=""><figcaption><p>Set the Client scope</p></figcaption></figure>

4. Click: pdc-client-dedicated

<figure><img src="/files/BzYhSC4P7sFiBU4avASj" alt=""><figcaption><p>Set pdc-client-dedicated scope</p></figcaption></figure>

<details>

<summary>Why set pdc-client- dedicated scope?</summary>

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

</details>

5. Click: Mappers tab

<figure><img src="/files/n6qsDkhv3E18bYIrRMyo" alt=""><figcaption><p>Select: By configuration</p></figcaption></figure>

6. Click Add Mapper → By Configuration.

<details>

<summary>What's the difference between 'From predefined mappers' and 'By configuration'?</summary>

**"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.

</details>

7. Click: User Realm Role.

<figure><img src="/files/BKD9Ud225hIyQP6pyGIz" alt=""><figcaption><p>By Configuration mappers</p></figcaption></figure>

8. Select the following options:

<table><thead><tr><th width="254">Configuration</th><th>Value</th></tr></thead><tbody><tr><td>Name</td><td>AdventureWorks-Realm-Roles</td></tr><tr><td>Realm Role prefix</td><td>Leave blank</td></tr><tr><td>Multivalued</td><td>✅ ON</td></tr><tr><td>Token Claim Name</td><td>realm_roles</td></tr><tr><td>Claim JSON Type</td><td>String</td></tr><tr><td>Add to ID Token</td><td>✅ ON</td></tr><tr><td>Add to Access Token</td><td>✅ ON</td></tr><tr><td>Add to Userinfo</td><td>✅ ON</td></tr></tbody></table>

9. Click: Save.

<figure><img src="/files/LpQ4kB9M7Jsu4RKC6vnW" alt=""><figcaption><p>Add realm-roles mapper</p></figcaption></figure>

10. Repeat the workflow to add: 'Group Membership' mapper:
11. Select the following options:

<table><thead><tr><th width="254">Configuration</th><th>Value</th></tr></thead><tbody><tr><td>Name</td><td>AdventureWorks-Groups</td></tr><tr><td>Token Claim Name</td><td>groups</td></tr><tr><td>Full group path</td><td>✅ ON</td></tr><tr><td>Add to ID Token</td><td>✅ ON</td></tr><tr><td>Add to Access Token</td><td>✅ ON</td></tr><tr><td>Add to Userinfo</td><td>✅ ON</td></tr></tbody></table>

<figure><img src="/files/5BsfPXzmDj5genXfAr4L" alt=""><figcaption><p>Add groups mapper </p></figcaption></figure>

11. Click: Save.

{% hint style="info" %}
As a result of these 2 mappers the JWT token

✅ AdventureWorks-Realm-Roles (includes user's roles)

✅ AdventureWorks-Groups (includes user's group membership)

&#x20;

Combined JWT Token Result:

When Sarah Johnson logs in, the token will contain:

```json
{
  "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"]
}
```

{% endhint %}

{% hint style="info" %}
**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.&#x20;

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\..!
{% endhint %}

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://academy.pentaho.com/pentaho-data-catalog-en/data-catalog/aw-organization/role-mappers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.