User claims are typically used as criteria in Policies to control to whom the Entitlements are assigned; but can also be used elsewhere in the system such as in Conditions to decide when Entitlements are allowed.
A number of default database attributes from the IdP are mapped to user claims in the AppGate ZTNA system. The actual attributes mapped depend on the type of IdP selected. AppGate ZTNA allows you to make changes to these default mappings and also to create new user claims that can be mapped from other attributes.
By creating several Policy expressions using different claims, administrators can be very precise about how Entitlements are allocated to prevent over-provisioning.
Default user claims
For the local provider and Connector provider, a default list of mapped attributes is included. For the LDAP providers an example list of AD mapped attributes is included. As well as adding your own attributes, the included attributes can be edited/deleted.
To configure
To view (or edit) any default attribute mapping go to the bottom of any configuration form in Identity Providers.
The new claim can be selected from the criteria drop downs in Policies, Conditions and Criteria Scripts under User Claims.
The operator is then selected.
Groups
The groups match operator: use this option to check for membership of an LDAP group. The match operator uses exact match; while testing the LDAP "groups" claim with contains operator, you need to provide the whole FQDN of the group name. For example: CN=group3,OU=sweden,DC=myzone,DC=com", "CN=group4,OU=sweden,DC=myzone,DC=com
It is not recommend to use partial matches for security reasons but you can do this in JavaScript. You can flatten "groups" claim to a single string: var all_groups = claims.users.groups.toString() then check the group name var match= all_group.indexOf('CN=Developers,') > -1;
NOTE
The inclusion of the trailing comma for security reasons - this prevents any un-intentional matches like
CN=Developers Inactive, OU= vs CN=Developers, OU=..
Mapping to array-based user attributes
AppGate ZTNA can map a single claim-name to an attribute with multiple values (multiple lines). The Controller will generate multiple instances of that particular user claim. The value of each instance is populated by the next value in the array in order.
For example, where the array attribute "otherHomePhone" is mapped to claim name "Phone", a user who has two other phone numbers will have a claims token containing two instances of the claim "Phone".
For details about the default attribute mapping of user-claims, refer to: Claims in detail.
Adding user claims
It is possible to create new claims in order to utilize other database attributes.
NOTE
To create user-claims, the administrator will need to have an admin role that includes create identity provider privileges.
To configure
They are enabled by Identity Provider. From Identity Providers, choose an IdP. Under Map Attributes to User Claims, click on <Add New> to add a new claim.
The new claim can be selected from the top section of the criteria drop downs in Policies, Conditions, and Criteria Scripts under User Claims.
If you delete a claim that is used as a criteria in a Policy or Condition, then the expression will always return False.
User Claim Script
Use the user claim scripts UI to create a new script.
User Claim Scripts are so called because they create additional user claims. User claim scripts are run AFTER both user sign-in and running the device claim scripts but BEFORE the Policy assignment. Scripts can include existing user, device and system claims, and the additional user claims it generates can be used elsewhere in the system. Within the Controller the new claims can be used as assignment criteria within Policies. These new claims are also added to the claims token; so within the Gateway, they can be used as access criteria in Conditions and used in Entitlement scripts to define protected hosts.
Why use user claim scripts?
This type of script would typically be used this to query external systems in order to collect additional information about the user and/or their device. It should be used for making external calls in preference to doing this in the (Assignment) Criteria Script. The User Claim Script will be run just the once whereas the Assignment Criteria Script will be run once for every Policy.
This script can also help to reduce the load on your Gateways considerably. Claim values (from the script) may be used straight from the claims token rather than the Gateway having to query the external system (again) for every new TCP stream initiated by every user.
Functionality
The JavaScript can include existing user, device and system claims. It runs in a sandboxed JavaScript engine which supports external httpGet/Post/Put/Delete calls. This script should be as efficient as possible and execute promptly - the user/device sign-in process will be waiting for this script to finish.
After three seconds a warning message will be posted to the dashboard naming the offending script.
After ten seconds the script times out.
The Client will also fail-over to the next Controller after 15 seconds (where this process might be repeated!)
To configure
User Claim Scripts are added in User Claim Scripts
They are enabled by Identity Provider. To run a script go to Identity Providers > User Claim Scripts. The output from the script must include a specific user claim and its value.
The results from the user claim scripts can be included by selecting agScripted from the list of user claims in the criteria drop downs in Policies, Conditions and Criteria Scripts.
A JavaScript expression is required to evaluate the returned value as the system has no way of knowing the type of value that has been returned. The new claim will appear in the system as
claims.user.agScripted.claim_name:claim_value
For more information about device claims refer to Device claims.