> For the complete documentation index, see [llms.txt](https://ztrust.gitbook.io/ztrust-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ztrust.gitbook.io/ztrust-documentation/user-manual-ztrust-v4.2/3.-guide-to-navigation/3.2-client-scopes.md). # 3.2 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.

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

#### Client Scope Attributes: * **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.

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

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

3. Click **Configure a New Mapper**.

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

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

Mapper Type	Description
Claims parameter Token	The claims specified by the claims parameter are included in the tokens.
User Realm Role	Associate the user realm role with a token claim.
User Session Note	Connect a custom user session note to a token claim.
Claims parameter with value ID Token	Claims specified with a value by the claims parameter are included in an ID Token.
User Address	Associate user address attributes (street, locality, region, postal_code, and country) with the OpenID Connect ‘address’ claim.
Role Name Mapper	Assign a role to a new name or position in the token.
User Client Role	Associate a user client role with a token claim.
User Property	Map a built-in user property (email, firstName, lastName) to a token claim.
Authentication Context Class Reference (ACR)	Assign the achieved Level of Authentication (LoA) to the ‘acr’ claim of the token.
Hardcoded Role	Hardcode a role into the access token.
Hardcoded claim	Hardcode a claim into the token
Pairwise subject identifier	Generates a pairwise subject identifier using a salted SHA-256 hash.
User’s full name	Associates the user's first and last name with the OpenID Connect 'name' claim.
Allowed Web Origins	Includes all permitted web origins in the 'allowed-origins' claim within the token.
Audience	Append the specified audience to the 'audience' (aud) field of the token.
User Attribute	Connect a custom user attribute with a token claim.
Group Membership	Map user group membership.
Audience Resolve	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.

You can use the search box to find a specific mapper. Click the Refresh button to see the latest settings. There are 29 predefined mappers available for you to choose from.

Fig 3.2.j: Show number of client scopes per page

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. At the bottom, there's an option to Add. Click on Add to add the chosen predefined mappers.

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

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

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.

#### **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. Upon clicking this, you will be presented with the prompt shown below.

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

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

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

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

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. To view inherited roles, simply uncheck this option.

Fig 3.2.v: List of available roles display per page

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.

Fig 3.2.w: Opition to delete client scope

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.

Fig 3.2.x: Conformation to delete the client scope

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