---
description: >-
  Client scopes allow administrators to define and group a set of protocol
  mappers and roles that can be shared and reused across multiple clients.
---

# Client Scopes

#### What is Client Scope in ZTrust?

In **ZTrust**, **Client Scopes** represent a set of permissions, claims, protocol mappers, and role mappings that can be assigned to one or more clients.\
They help avoid duplication by allowing **multiple clients** to use the same configuration.

Client Scopes are particularly useful in **OpenID Connect (OIDC)** and **OAuth2** flows, as they define what information (claims) will be included in tokens such as the **ID token** or **Access token**.

### **Key Features of Client Scopes**

* Group reusable **permissions** and **claims** for multiple clients.
* Avoid duplicate configuration across clients.
* Control what information is included in tokens.
* Assign roles, protocol mappers, and other attributes to tokens.
* Manage claims and transformations easily from a single place.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2Fv84mdDGCpskAXxXq3q50%2Fimage.png?alt=media&#x26;token=be68b3f4-69bf-42da-9d61-7c11a5f06e81" alt=""><figcaption></figcaption></figure>

### **Filtering Client Scopes**

You can filter client scopes based on:

* **Name** → Unique name of the client scope.
* **Assigned Type** → Whether the client scope is **Default** or **Optional** for new clients.
* **Protocol** → Defines whether the scope uses **OpenID Connect (OIDC)** or **SAML**.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FYJHbZmEUE6NeT9Cx82ut%2Fimage.png?alt=media&#x26;token=34bfb614-8d8c-441b-a76d-a4387c0e33e6" alt=""><figcaption></figcaption></figure>

#### Client Scope Attributes:&#x20;

* **Name** : A unique name for the client scope within the realm.
* **Assigned Type:** Defines whether the scope is added **by default** to all new clients or can be added manually.
* **Protocol**: The protocol configuration (**OIDC** or **SAML**) associated with the client scope.
* **Display Order**: Determines the position of the scope in the admin console UI.
* **Description**: A short description of the purpose of the client scope.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F2nWUqEZm30kOO1WhKPbd%2Fimage.png?alt=media&#x26;token=8408b54c-7a0a-48cd-9660-40b933954701" alt=""><figcaption></figcaption></figure>

### **Managing Client Scopes**

### **1.Creating a Client Scope**

1. Click on **Create Client Scope**.
2. Fill in the following details:
   * **Name** → Must be unique and cannot contain spaces.
   * **Description** → Purpose of the client scope.
   * **Type** → Choose whether the scope is **Default** or **Optional**.
   * **Protocol** → Select the desired protocol (OIDC/SAML).
   * **Display on Consent Screen** → Enable if you want users to see this scope during consent.
   * **Consent Screen Text** → Text displayed to users during consent (defaults to scope name if empty).
   * **Include in Token Scope** → Enable if you want this scope included in access tokens.
   * **Display Order** → Set the UI display priority.
3. Click **Save** to create the client scope.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FkpfyZG5tOagrOMFBPvOa%2F9.png?alt=media&#x26;token=4fed5c63-eaa8-4f3e-ae4e-6d7ccb0126c4" alt=""><figcaption></figcaption></figure>

#### **What are Protocol Mappers?**

Protocol mappers transform and map data between the **authentication server** and **tokens**.\
They define **which claims** are included in tokens and how user attributes or roles are represented.

#### **Managing Protocol Mappers**

* **Add a New Mapper**
  1. Open a client scope.
  2.  Go to the **Mappers** tab.

      <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FgIw9a4NyeE8qM3bpOoPq%2Fimage.png?alt=media&#x26;token=8b646cc2-1e7f-482f-84c4-50700fd5497f" alt=""><figcaption></figcaption></figure>
  3.  Click **Configure a New Mapper**.

      <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FPVFI2i5nMYO6TTjS6FkK%2Fimage.png?alt=media&#x26;token=ee8587fc-37d0-40e6-8f4c-983d51047115" alt=""><figcaption></figcaption></figure>



      <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FvIObNb948zyR6C6cEFyH%2Fimage.png?alt=media&#x26;token=df040db1-4d46-49e1-b617-8e6fbb2d09a7" alt=""><figcaption></figcaption></figure>
  4. Select a mapper type (e.g., **User Property**, **Role Name Mapper**, etc.).
  5. Customize settings and click **Save**.
* **Add Predefined Mappers**
  1.  Click **Add Predefined Mapper**.

      <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FdDtGhiaqN131rdoxNCIJ%2Fimage.png?alt=media&#x26;token=da2f6d65-e77b-4270-b1dc-39186a83a6e9" alt=""><figcaption></figcaption></figure>
  2. Choose from the list of **29 predefined mappers**.
  3. Select the desired mappers and click **Add**.

You can view the same settings here that you previously configured.

If any changes are made and you want to save them, click Save. Otherwise, click Cancel.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FepdFBqRvM5vWpoy5U0qK%2F16.png?alt=media&#x26;token=ef71dd88-a811-43ea-89d3-dc8d755944a7" alt=""><figcaption></figcaption></figure>

#### **Add to ID Token**

This toggle button controls whether the claim can be added to the ID Token.

When activated (toggled ON), the claim can be included in the ID Token.

Conversely, when deactivated (toggled OFF), the claim is not added to the ID Token.

You can adjust this setting as needed by toggling it ON or OFF.

#### **Add to user info**

This toggle button determines whether the claim should be added to the user info.&#x20;

When activated (toggled ON), the claim will be included in the user info.

If deactivated (toggled OFF), the claim will not be added to the user info.

You can toggle this setting ON or OFF according to your requirements.

#### **Save**

To apply the changes you've made, click on Save.

#### **Cancel**

If you prefer not to incorporate the changes, click on Cancel to discard them.

You can review the table below to observe the various types of mappers and their respective purposes.

<table><thead><tr><th width="224">Mapper Type</th><th>Description</th></tr></thead><tbody><tr><td>Claims parameter Token</td><td>The claims specified by the claims parameter are included in the tokens.</td></tr><tr><td>User Realm Role</td><td>Associate the user realm role with a token claim.</td></tr><tr><td>User Session Note</td><td>Connect a custom user session note to a token claim.</td></tr><tr><td>Claims parameter with value ID Token</td><td>Claims specified with a value by the claims parameter are included in an <a href="../../../user-manual-ztrust-v2.0/key-terminologies#identity-token">ID Token</a>.</td></tr><tr><td>User Address</td><td>Associate user address attributes (street, locality, region, postal_code, and country) with the OpenID Connect ‘address’ claim.</td></tr><tr><td>Role Name Mapper</td><td>Assign a role to a new name or position in the token.</td></tr><tr><td>User Client Role</td><td>Associate a user client role with a token claim.</td></tr><tr><td>User Property</td><td>Map a built-in user property (email, firstName, lastName) to a token claim.</td></tr><tr><td>Authentication Context Class Reference (ACR)</td><td>Assign the achieved <a href="../../../user-manual-ztrust-v2.0/key-terminologies#level-of-authentication-loa">Level of Authentication (LoA)</a> to the ‘acr’ claim of the token.</td></tr><tr><td>Hardcoded Role</td><td>Hardcode a role into the access token.</td></tr><tr><td>Hardcoded claim</td><td>Hardcode a claim into the token</td></tr><tr><td>Pairwise subject identifier</td><td>Generates a pairwise subject identifier using a <a href="../../../user-manual-ztrust-v2.0/key-terminologies#salted-sha-256-hash">salted SHA-256 hash</a>.</td></tr><tr><td>User’s full name</td><td>Associates the user's first and last name with the OpenID Connect 'name' claim.</td></tr><tr><td>Allowed Web Origins</td><td>Includes all permitted web origins in the 'allowed-origins' claim within the token.</td></tr><tr><td>Audience</td><td>Append the specified audience to the 'audience' (aud) field of the token.</td></tr><tr><td>User Attribute</td><td>Connect a custom user attribute with a token claim.</td></tr><tr><td>Group Membership</td><td>Map user group membership.</td></tr><tr><td>Audience Resolve</td><td>Include all client_ids of 'allowed' clients in the audience field of the token. An 'allowed' client refers to a client for which the user has at least one client role.</td></tr></tbody></table>

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FUs0J6W6LsW67ZyuxuL0O%2F17.png?alt=media&#x26;token=b2c81e16-e3f4-4b2f-a4e1-8bc5654a33c9" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F946p60H1GwHdbOnAJ2fx%2F18.png?alt=media&#x26;token=99447f8e-6236-4815-af4b-84574d9d0229" alt=""><figcaption></figcaption></figure>

You can use the search box to find a specific mapper.&#x20;

Click the Refresh button to see the latest settings.

There are 29 predefined mappers available for you to choose from.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FEhQ9FSDA4KQiVXnkFarm%2F19.png?alt=media&#x26;token=e6edb5bf-a40c-4f2d-a41b-0211cafafff4" alt=""><figcaption></figcaption></figure>

You can also choose how many mappers you want to display on one screen. Select your preferred option from the dropdown menu as shown below.

If you want to select a specific mapper from the predefined mapper list, click on the checkbox for that particular mapper.

This will select the corresponding mapper.&#x20;

At the bottom, there's an option to Add. Click on Add to add the chosen predefined mappers.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F4pBBjK1JqmBs8SnIOFVR%2F20.png?alt=media&#x26;token=b632bf3c-190e-4a2e-ac9f-6552608a0986" alt=""><figcaption></figcaption></figure>

Once added, the particular mapper will be visible under the Mappers tab, as shown below.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FOBjLpZutFUgYOMQppbaM%2F21.png?alt=media&#x26;token=3b366c80-45bc-4a28-ae7c-bdc7b2848545" alt=""><figcaption></figcaption></figure>

#### **Name**

This displays the names of the existing predefined mappers.

#### **Category**

This section categorizes the mentioned mappers.

#### **Type**

This specifies the type of the predefined mappers.

#### **Priority**

Mapper implementations are prioritized based on their order in the list of mappers.

Priority order is not the configuration property of the mapper. It is the property of the concrete implementation of the mapper.

This order dictates the sequence in which changes to the token or assertion are applied, with the lowest priority mappers being processed first.

This ensures that implementations dependent on others are executed in the required order.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F3PLCQqR8BPX7x36aYDMS%2F28.png?alt=media&#x26;token=72d33ebb-27b5-46ac-8dd1-a2518a3bc863" alt=""><figcaption></figcaption></figure>

After clicking on the three dots, you will see an option to delete the specific mapper.

If you wish to delete that particular mapper, click on Delete.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FIJjdY7V2QQqUqzdzmR2Q%2F22.png?alt=media&#x26;token=655bbd9a-3904-4012-a957-43a55de2908e" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FT8zTMzYFUSTxdoYUEyCj%2F23.png?alt=media&#x26;token=a90d5849-1c18-436a-a54d-0501162def82" alt=""><figcaption></figcaption></figure>

#### **Scope**

This configuration enables you to limit the user role mappings included in the access token requested by the client.

To assign roles, select Assign role.&#x20;

Upon clicking this, you will be presented with the prompt shown below.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FNLi6JLk0pU00GxLAB5Ji%2F24.png?alt=media&#x26;token=5f19622c-ea39-4b1a-902a-6597b18e9401" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FErH3Nytyyn8h44qZvwXM%2F25.png?alt=media&#x26;token=9a712f6e-429c-4f1d-96e0-8cae4ba24ba8" alt=""><figcaption></figcaption></figure>

Here, you can filter roles based on clients or realm roles.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FH9whUlBuE0UtvDmSVNhm%2F26.png?alt=media&#x26;token=c76764ed-4b76-4cce-92a0-b2031ed21d01" alt=""><figcaption></figcaption></figure>

If you want to select a specific role from the list, click on the checkbox for that particular role.

This will select the corresponding role.&#x20;

At the bottom, there's an option to Assign. Click on Assign to add the chosen roles.

Once added, the particular role will be visible in the scope list, as shown below.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FVGuZquMFYBOdc6rHbMJG%2F27.png?alt=media&#x26;token=c9302245-fe18-4b6f-aa9d-c8ea0ad91b31" alt=""><figcaption></figcaption></figure>

#### **Name**

It includes the list of all the different roles that are already assigned to this client.

#### **Inherited**

This pertains to roles explicitly assigned to users and those inherited from composite roles. It can have two values: True (indicating the role is inherited from composites) or False (indicating it is not inherited from any composite role).

#### **Description**

It refers to the description for the role which will aid you in identifying its purpose.

This field can be localized by specifying a substitution variable with **${var-name}** strings.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FkvlGioWURlULDbKS8cQx%2F1.png?alt=media&#x26;token=6eb85ae2-0edf-4cbe-99aa-88643a79d11f" alt=""><figcaption></figcaption></figure>

By clicking on the three dots, you can access the option to unassign. If a role is no longer needed for any client, simply click on Unassign.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FetpP5LwIOW5Zq5fHRWq2%2F2.png?alt=media&#x26;token=7f59c43b-bc2c-43d4-9e46-942987377601" alt=""><figcaption></figcaption></figure>

Upon clicking Unassign, you will receive a confirmation prompt. To remove a specific role, click Remove; otherwise, click Cancel.

If you wish to unassign multiple roles, simply click on the checkbox next to each role you want to select. Once selected, click on Unassign to proceed.

You will receive the following prompt requesting confirmation.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FNCXWXku4absHcXlvPMji%2F3.png?alt=media&#x26;token=acc31a88-78cf-458d-bf68-e7f71471a6ff" alt=""><figcaption></figcaption></figure>

To remove a specific role, click Remove; otherwise, click Cancel.

#### **Hide inherited roles**

Selecting this checkbox hides inherited roles, preventing you from seeing roles inherited from composites.&#x20;

To view inherited roles, simply uncheck this option.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F18aRQDwZ7s1jAZ1m9e0y%2F4.png?alt=media&#x26;token=52fa2a56-70cd-4ba1-93b1-9fbd273f35dd" alt=""><figcaption></figcaption></figure>

You can also choose how many roles you want to display on one screen. Select your preferred option from the dropdown menu as shown above.

You can search for any specific role by using the search box.

Click the Refresh button to see the latest settings.

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FRoSIilyYPaM8ViaJL4ze%2F5.png?alt=media&#x26;token=69f5674e-272a-4569-b89d-686fca185ed6" alt=""><figcaption></figcaption></figure>

You can also delete the entire client scope by clicking on Action at the top right corner and selecting Delete.

Upon clicking Delete, you will receive the following prompt requesting confirmation.&#x20;

<figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FDAsYYefuwjxIqesiD5zt%2F6.png?alt=media&#x26;token=6ddbf423-3df5-4f44-b868-755662208158" alt=""><figcaption></figcaption></figure>

Click Delete to proceed with the removal, or click Cancel to retain it.

