> 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-v2.0/guide-to-navigation/client-scopes.md). # Client Scopes

You can filter the client scopes based on Name, Assigned type, and Protocol, as indicated above. #### **Name** This indicates the name of the client scope, which must be unique within the Realm. #### **Assigned type**

It specifies whether the defined client scope will be incorporated by default into the configuration of each newly created client. #### **Protocol** This defines the protocol configuration provided by this client scope. #### **Display order** It defines the provider's position in the GUI as an integer. #### **Description** It refers to the description for the client scope, which will be helpful in identifying the purpose of the client scope.

When you click on the three dots next to any client scope, you'll find the Delete option. If you want to remove a client scope that is no longer needed, simply click on Delete. After clicking Delete, you will receive the following prompt asking for confirmation.

Select Delete if you want to proceed with the deletion, otherwise click Cancel. You can search for any specific client scope by using the search box. Click the Refresh button to see the latest settings.

You can also modify the number of client scopes displayed per screen by choosing your preferred option from the dropdown menu.

You can select a specific client scope by clicking on the checkbox next to it. This is particularly useful if you want to make changes to multiple client scopes simultaneously. If you wish to delete multiple client scopes, simply click on the checkboxes next to them, then click on the three dots next to Change Type to and select Delete.

To change the Assigned type of multiple client scopes simultaneously, first select all the relevant scopes. Then, click on Change type to, and choose the preferred option based on your requirements.

If you want to establish a new client scope, click on Create client scope. Upon clicking Create client scope, you will be directed to the following screen.

#### **Name** This indicates the name of the client scope, which must be unique within the Realm. The name should not include space characters, as it is utilized as the value of the scope parameter. #### **Description** It refers to the description for the client scope, which will be helpful in identifying the purpose of the client. #### Type

It indicates whether the defined client scope will be incorporated by default into the configuration of each newly created client. #### **Protocol** This defines the protocol configuration provided by this client scope.

You can choose the most suitable option from the dropdown based on your needs. #### **Display on consent screen** This toggle button, when activated (toggled ON), will display the text specified by Consent Screen Text on the consent screen if this client scope is added to a client with consent required. If deactivated (toggled OFF), this client scope will not appear on the consent screen. You can toggle it ON or OFF according to your needs. #### **Consent screen text** This pertains to the text that will be shown when this client scope is added to a client with consent required. By default, it displays the name of the client scope if left empty. #### **Include In Token Scope** This toggle button, when activated (toggled ON), will include the name of this client scope in the access token property scope and in the Token Introspection Endpoint response. If deactivated (toggled OFF), this client scope will be excluded from the token and from the Token Introspection Endpoint response. You can toggle it ON or OFF according to your needs. #### **Display order** It defines the provider's position in the GUI as an integer. #### **Save** If you want to create a client scope with all the specified details, click on Save to apply your changes. #### **Cancel** If you do not create the client scope with the provided details, click on Cancel to discard the changes. After clicking on Save, you will be taken to the following screen.

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.

#### **Mappers** Protocol Mappers facilitate transformations on tokens and documents. They are capable of tasks such as mapping user data into protocol claims or transforming any requests exchanged between the client and authentication server. #### **Configure a new mapper** To create a new Protocol Mapper, simply click on Configure a new mapper. When you click on Configure a new mapper, a prompt will be displayed as shown below.

You can choose the specific mapper you wish to configure. For example, here, the Claims parameter Token is selected. Clicking on Claims parameter Token will redirect you to the screen shown below.

#### **Mapper Type** This indicates the type of mapper that you have selected. #### **Name** This denotes the name of the mapper, which you can customize according to your needs. #### **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 userinfo** This toggle button determines whether the claim should be added to the userinfo. When activated (toggled ON), the claim will be included in the userinfo. If deactivated (toggled OFF), the claim will not be added to the userinfo. 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 also add predefined mappers by clicking on Add predefined mapper to select the necessary mappers. When you click on Add predefined mapper, the prompt shown below will be displayed.

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.

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.

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.

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.

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