Several built-in device claims (formerly known as fixed device claims) are collected from connecting devices automatically and used to populate device claims. These are used in policies and conditions as criteria to control the assignment and authorization of Entitlements based on context.
AppGate ZTNA allows you to add additional device claims. Along with built-in device claims, these are harvested when the user signs in and are checked every five minutes thereafter by the client. They are then reported to the Gateway when a change is detected.
By creating several policy expressions using different claims, administrators can be precise about how entitlements are allocated to prevent over-provisioning.
For full details of how real-time changes in device claims affect users' access rights, refer to Real-time (re)evaluations.
Fixed device claims
AppGate ZTNA clients automatically collect a fixed list of claims from every device that connects to the system.
To configure
These claims can be selected in Policies, Conditions and Criteria Scripts from the middle section of the criteria drop-downs under Device claims - Builtin (previously Device Claims) or Device Claims - Scripted (previously On-Demand claims).
Device claims examples
"os.family": use this option to include devices with a particular OS.
"isFirewallEnabled": use this option to check for a device firewall
For detailed information about all the claims types available, refer to Claims in detail.
Adding scripted device claims
When built-in device claims do not harvest the required information from the user's device, then you can add extra scripted (formerly on-demand) device claims.
Scripted claims are configured by identity provider. This is important for large or multi-tenant environments, as it means an IdP can be configured to harvest (and check) sensitive information only from devices used for a specific purpose (like administration). Remember, this information (the claims) will end up in the logs.
Scripted device claims will run a device script; this script, the execution environment, and measurement points are all somewhat in the control of the user, so device claims should be considered as untrusted and not relied on for making critical security decisions.
To configure
They are enabled by identity provider. From Identity Providers, choose an IdP type. Under Scripts Mapped to Device Claims, click <Add> to add a new claim.
Choose the command you require from the dropdown list and configure the required fields including the device claim name.
The new claim can be selected under Device claims, from the assignment criteria drop downs in Policies and Criteria Scripts, and from the access criteria dropdown in Conditions.
Device Claim Script
Use the Device claim scripts UI to create a new script.
Device claim scripts are intended to harvest specific information that is not available by default. After the user signs in, specified native executable scripts are pushed to the user's device. The client runs these executables which return information (about the devices) that ends up as a claim in the Controller. These claims can then be used in the (assignment) criteria scripts within policies.
As of AppGate ZTNA version 6.6, verification of profile DNS names is required to execute device claim scripts. Follow the steps to verify your profiles below.
WARNING
If you have not yet updated to version 6.6 and you intend to continue using device claim scripts after you upgrade, you must obtain an updated license file before upgrading your Collective to 6.6.
Why use device claim scripts?
Over 20 built-in claims and scripted device claim commands are available. When the specific information required is not available using the built-in commands, you may write and upload native executable scripts. The supplemental device information provided by the script will be saved as a claim by the Controller and can be used as basis for assignment decisions in the (assignment) criteria scripts within policies. The supplemental device information will also be treated as a claim by the Gateways and can be used in a condition’s access criteria scripts to allow (or block) a specific entitlement.
Functionality
The script may be any form of file that executes on the designated client platform (such as a native Win32 binary for Windows, a .bat file for Windows, or a Bourne-shell script for Unix). It will be run with the same rights as the user. The Controller will also send a checksum for the executable and the client always checks the executable to see if it has been changed and re-downloads if required. The scripts are effectively saved on the user's device (such as in Windows in %homepath%\appdata\appgate\). Remember that the script, execution environment, and measurement points are all somewhat in the control of the user, so device claims should be considered as untrusted and not relied on for making critical security decisions.
A script can be designed with a single function requiring no arguments, or be more versatile providing lots of options depending on the argument(s) provided. It must complete within 12 seconds, otherwise it will time out. It must return exit code zero if the claim should be set. The claim is then set to the last line of output on stdout.
Example device claim script
1#!/bin/sh
set -e
case "$1" in
'--pathexists')
[ -e "$2" ]
;;
'--process')
ps -C "$2" 2>&1 > /dev/null
;;
*)
echo "Usage: $0"
echo " --pathexists <file>"
echo " --process <name>"
exit 1
;;
esacIn this example you can check if a file exists or if a process is running on Linux. The -pathexists option checks for a file in a given location and the -process will for the process name to see if it is currently running.
This returns yes or no which can then be evaluated in a condition.
NOTE
If you have created a script, such as an sh file; you need to have #!/bin/sh at the beginning, otherwise the AppGate ZTNA will not receive the output.
Profile DNS name verification
Before you can execute device claim scripts, you must verify the profile DNS name for the profiles executing the scripts.
To verify:
Send a request to AppGate Support for an updated license file, which will enable device claim scripts for your Collective.
AppGate Support will verify your identity and ensure the provided list of profile DNS names is owned by your team. AppGate Support will then export a license from your customer account in the SDP License Server.
Once you have received the license, upload it to your Controller (Settings > Licenses > Upload License button).
After uploading the license, log out and log back in to the AppGate client. When the client connects to your Controller it will send the relevant section of the license file with the device claim script to the client.
The AppGate client verifies the signature of the license and confirms that the profile DNS name is on the list. If validation succeeds, the device claim scripts will be executed.
To configure
Device claim scripts are uploaded in the Device Claim Scripts page.
They are enabled by identity provider. To run a script, go to Identity Providers > Configure Scripted Device Claims and select Run Device Script from the Command drop down. Here you specify where (platform) the script should be run. The output from the script will be mapped to the device claim specified.
The new claim can be selected from the middle section of the criteria drop downs in Policies, Conditions and Criteria Scripts under Device claims - Builtin (previously Device Claims) or Device Claims - Scripted (previously On-Demand claims).
NOTE
Any device claims which return yes/no or true/false will be evaluated as a string. Any values that should not be treated as a string need to be handled using <script returns true> mode.
NOTE
Custom scripted device claims are not supported on headless clients.
For information about user claims, refer to User claims.