Client Scopes
Client scopes allow administrators to define and group a set of protocol mappers and roles that can be shared and reused across multiple clients.
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
Click on Create Client Scope.
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.
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
Open a client scope.
Go to the Mappers tab.
Click Configure a New Mapper.
Select a mapper type (e.g., User Property, Role Name Mapper, etc.).
Customize settings and click Save.
Add Predefined Mappers
Click Add Predefined Mapper.
Choose from the list of 29 predefined mappers.
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.
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.
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.
Last updated