Claims are session specific, key-value pairs that describe the user, device, and connection context.
Claim types include:
Context. Based on helpers that evaluate parameters such as is in the IP range.
User. Static, unchanging claims such as username from the IdP, a user claims script, or a Connector.
Device. Dynamic, changeable claims such as the IP address of the connecting device.
System. Dynamic, changeable claims such the country code from the Gateway.
Claims have two availability classes:
Built-in (formerly Fixed). Set by the system and always gathered.
Scripted (formerly On-demand). Configured by the admin and gathered when required.
You can see view a user’s claims at any time from the dashboard. In Active Sessions (Usage > Active Sessions), select the user's name to view the session details.
Context claims
In addition to user, device, and system claims, helper functions are available to evaluate user and device context.
Context-based helpers (non-configurable)
Name | Description | Example usage | Return values | Usage^ |
|---|---|---|---|---|
| Uses the method |
returns |
| P |
| Uses the method |
returns |
| P C CS |
| Uses the method |
returns |
| P C CS |
| Uses the method |
returns |
| P C CS |
| Uses the method |
returns |
| P C CS |
| Checks the | Simply pick the IdP from the list of IdPs |
| P C CS |
| Uses the | Pick the rule name and then the risk score for the access criteria to evaluate to |
| C |
| Uses the value from a script | Allows script value to be AND/ORed with other claims |
| P CS |
^ P=Policy, C=Condition, CS=Criteria Script
User claims
System user claims (non-configurable)
These claims are generated and used by the AppGate ZTNA system.
If you are editing conditions or policy assignment expressions using script returns true mode, use the following format for user claims: claims.user.#claim-name#
For example, ag.distinguishedName is used as claims.user.ag.distinguishedName
Name | Description and usage | Example usage |
|---|---|---|
| When a user signs in using a certificate, the |
|
| Passes any local resourced defined in the Connector to the Gateways. Will not exist if Source NAT from local resource is enabled as the Connector clients tun IP address will be used to route traffic. |
|
| A unique combination of device, user, and IdP that defines every session. The format comprises three claims concatenated together (see below). |
|
| A, unique number that comes from the specific device (or is generated when one is not available) |
|
| The username used by the AppGate ZTNA system. |
|
| In some cases this is a system generated name such as with a Connector resource group which will always be Connector |
|
| Client sign-in timestamp, set when the claims token is issued. Renewal of the claims token does not override this claim unless the previous claims token has expired |
|
| When a user signs in, the AD the password expire warning can be read and used to warn the user. |
|
Default user claims (configurable)
Default user claims collect information about the user or device. Typically, they come from the identity provider, a user claim script, or other trusted sources.
A default claim mapping exists for attributes that come from identity providers. You can change these mappings using Identity Providers > Map Attributes.
IdP-based attributes must be mapped before they are available in AppGate ZTNA.
The following table provides example values for the default mappings.
If you are editing conditions or policy assignment expressions using script returns true mode, use the following format for user claims: claims.user.#claim-name#
For example, a user’s first name is held in claims.user.firstName, and the return from a user claim script that finds a user's shoe size is held in claims.user.agScripted.shoe_size
Name | Usage | Description | Example usage |
|---|---|---|---|
| User claims script | Value returned after running a user claim script which will require some sort of JavaScript logic since the format is nondeterministic. |
|
| Connector | The name given to the Connector appliance |
|
| Connector | The client name within the Connector |
|
| Local DB & external IdP |
| |
| Local DB & external IdP |
| |
| External IdP |
| |
| Connector | The hostname of the Connector appliance |
|
| Local DB & Connector | For users: the unique user ID |
|
| k8s service client | Value of any environmental labels associated with the client which will require some sort of JavaScript logic since the format is nondeterministic. |
|
| Local DB & external IdP |
| |
| Local DB |
| |
| Local DB & Connector | For users: tags set for that user (in local DB) |
|
| External IdP |
| |
| Local DB & external IdP | Default mapped claim from the IdP. |
|
User response claims (configurable)
Each user interaction has an associated internal claim, for example: user.otpAuthentication.#name# and user.passwordAuthentication.#name#
The claim name suffix is the #name# string defined in the condition expression. This allows multiple independent claims to be created for one type of user interaction. For more information, refer to user interactions.
Name | Description | Parameters | Example usage | Return values | Use to assign Policy |
|---|---|---|---|---|---|
Provided MFA | Uses the method
| Named - text string, no spaces Time interval - minutes |
Returns Checks the the claim |
| no |
Retyped password | Uses the method
| Named - text string, no spaces Time interval - minutes |
Returns Checks the claim |
| no |
Device claims
Built-in device claims (formerly fixed device-claims) (non-configurable)
Built-in device claims collect information from the user's device. They are hard-coded, non-configurable, and always collected (depending on platform) and reported for all users. If you are editing condition or policy assignment expressions using script returns true mode, use the following format for device claims: claims.device.#claim-name#
For example, os.name is used as claims.device.os.name
For more information, see Built-in device claims.
Name | Description | Example Usage | Return value | Use to assign Policy | Win | macOS | Linux | Android Chrome OS | iOS iPadOS^ | Connector | Portal |
|---|---|---|---|---|---|---|---|---|---|---|---|
| The CPU architecture |
| string | yes | - | - | - | - | - | - | ✓ |
| The type of device in use. Possible values are |
| string | yes | - | - | - | - | - | - | ✓ |
| The underlying engine in use |
| string | yes | - | - | - | - | - | - | ✓ |
| Checks if Java is enabled |
| true/false | yes | - | - | - | - | - | - | ✓ |
| The brand of browser in use |
| string | yes | - | - | - | - | - | - | ✓ |
| List of any plugins installed |
| string array | yes | - | - | - | - | - | - | ✓ |
| The width of the screen |
| string | yes | - | - | - | - | - | - | ✓ |
| The height of the screen |
| string | yes | - | - | - | - | - | - | ✓ |
| The browser's timezone |
| string | yes | - | - | - | - | - | - | ✓ |
| The browser version |
| string | yes | - | - | - | - | - | - | ✓ |
| List of the active interface IPs |
| string array | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ |
| Type of client being used |
| Full | yes | ✓ | full | ✓ | full | full | connector | web |
| AppGate ZTNA version |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| This is the unique id that is included in the Crowdstrike data. This is only reported if there is a Crowdstrike agent installed. |
| string | yes | ✓ | ✓ | - | - | - | - | - |
| The name of the user using the device. |
| string | yes | ✓ | ✓ | ✓ | ✕ | ✕ | ✕ | ✕ |
| Are device scripts disabled |
| true-false | yes | ✓ | ✓ | ✓ | ✕ | ✕ | ✕ | ✕ |
| The device's hardware serial number, when the platform can provide one. |
| string | no | ✓ | ✓ | ✓^^^ | - | - | - | - |
| List of any local domain suffixes set. |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | ✕ |
| The enrolled domain of the device |
| string | yes | ✓ | - | - | - | - | - | - |
| The system disk is encrypted (requires >6.1.2 client) |
| true/false | yes | ✓ | ✓ | - | - | - | - | - |
| This is the unique id that is included in the Intune data. This is only reported if there is a Intune agent installed. |
| string | yes | ✓ | ✓ | ✓ | - | - | - | - |
| Always-on has been installed. (Run Headless installer on macOS.) |
| true/false | yes | ✓ | ✓ | - | - | - | - | - |
| Sets 'true' when |
| true/false | yes | ✓ | - | - | - | - | - | - |
| Domain registered device. |
| true/false | yes | ✓ | - | - | - | - | - | - |
| Is the firewall enabled |
| true/false | yes | ✓ | ✓ | ✓ ^ | false | false | false | false |
| Is this in multi-user mode |
| true/false | yes | ✓ | - | - | - | - | - | - |
| Does the user have admin rights |
| true/false | yes | ✓ | true | false | false | false | false | false |
| The language and region of the device |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | en-us | ✓ |
| List of the interfaces mac addresses |
| string array | yes | ✓ | ✓ | ✓ | ✕ | ✕ | ✓ ^^ | ✕ |
| Any MDM claims set when MDM is used to install a mobile client |
| string | yes | - | - | - | ✓ | ✓ | - | - |
| Family of OS |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | linux | ✓ |
| The hostname of the connecting device |
| string | yes | ✓ | ✓ | ✓ | not available on newer OSs | not available on newer OSs | ✓ | ✓ |
| Full name of operating system (OS) |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | AppGate ZTNA | ✓ |
| The CPU architecture of the device, not the operating system. Possible values are |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | x64 | unknown |
| Parent OS family (in Linux) |
| string | yes | - | - | ✓ | - | - | debian | - |
| The type of device. Native clients return |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | desktop | ✓ |
| Version of OS |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | 1.0 | unknown |
| Lists the hostnames from each profile |
| String | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Name of the client profile |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Value of the user response reason claim entered by the user |
| string | no | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ |
| This is the unique id that is included in the Sentinel One data. This is only reported if there is a Sentinel One agent installed. |
| string | yes | ✓ | ✓ | - | - | - | - | - |
| The name of the SPA key in use |
| string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Legend: [shown] is hard-coded; [-] is not collected; [✓] returns a measured value; [✕] does not return a value.
* On Windows, this claim always returns uppercase.
** This claim appears in the drop-down list only after the Reason user interaction is configured in the condition.
*** The always-on client reports Full or Headless depending on the mode it is running in.
^ This is evaluated using lsmod | grep ip_tables
^^ The Connector reports the MAC address of the veth for the namespace it runs in.
^^^ On Linux, only the root user can read product_serial. It's populated for headless and service installs, but it’s null in user mode.
Scripted device claims (Formerly on-demand device-claims) (configurable)
Scripted claims are made configurable when the command and parameters are passed to them. These are configured by identity provider, so they are collected and reported when that IdP is used. If you are editing condition or policy assignment expressions using script returns true mode, use the following format for device claims: claims.device.#claim-name#
The #claim-name# is the name assigned to it when you the scripted claim was configured. For more information, see Built-in device claims.
Command | Parameters | Measures | Return values | Use to assign Policy | Win | macOS | Linux | Android Chrome OS | iOS |
|---|---|---|---|---|---|---|---|---|---|
| file path* | size of a file | integer in bytes | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
| file path* | checks if the file exists | true/false | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
| file path* | create date of the file | iso 8601 | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
| file path* | last modification date of the file | iso 8601 | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
| file path* | sha512 of file | string | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
| process name | checks if a process is running | true/false | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
| file path* | [win] dll/exe version | string | yes | ✓ | ✕ | ✕ | ✕ | ✕ |
| query | [win] checks registry exists | true/false | yes | ✓ | ✕ | ✕ | ✕ | ✕ |
| query | [win] checks value in registry | string | yes | ✓ | ✕ | ✕ | ✕ | ✕ |
| service name | [win] checks if a service is running | true/false | yes | ✓ | ✕ | ✕ | ✕ | ✕ |
✕ means it does not return a value.
* Paths can be defined using environment variables:
macOS: For files below the user’s home directory, use
%HOME%to resolve the user’s home directory, for example:%HOME%/Desktop/pic.jpg.Windows: For files below the user’s home directory, use
%HOMEPATH%, and then use/(not \\) in your expressions, for example:%HOMEPATH%/Desktop/pic.jpg.
Custom scripted (formerly on-demand) device-claims (configurable):
When you select Run Device Claim Script, you can use a tailored script that returns a specific claim to the AppGate ZTNA system.
These will only be collected and reported when configured.
These are configured per identity provider, so they are collected and reported only when that IdP is used.
If you are editing condition or policy assignment expressions using script returns true mode, use the following format for device claims: claims.device.#claim-name#
The #claim-name# is the name assigned to it when the scripted claim was configured. For more information, see Built-in device claims.
Parameters > Script | Parameters > Args | Measures | Return values | Use to assign Policy | Win | macOS | Linux | Android | iOS |
|---|---|---|---|---|---|---|---|---|---|
name of the script | args for the script | what the script is designed to measure | string (from stdout) | yes | ✓ | ✓ | ✓ | ✕ | ✕ |
✕ means it does not return a value.
NOTE
Custom scripted device claims are not supported on headless clients.
User response claims (configurable)
The Reason user interaction has the following associated internal claim: device.reason.#name#
The #name# string is the claim name suffix defined in the condition expression, enabling multiple independent claims to be created for one type of user interaction. These internal claims, such as reason.#name#, are exposed when the user performs the user interaction. Conditions are then based on the text entered by users in response to the Reason user interaction. The session details show the reason claim under Device Claims as "#name#": "value". For more information, see user interactions.
Name | Description | Parameters | Example usage | Return values | Use for Policy assignment |
|---|---|---|---|---|---|
Provided reason | Uses the method
| Named - text string, no spaces |
Returns Checks the claim |
| no |
System claims
System claims (non-configurable)
System claims are hard-coded and assigned by the system, usually by the Gateway, at run time. If you are editing condition or policy assignment expressions using script returns true mode, use the following format for system claims:
claims.system.#claim-name#
For example, clientSrcIp is used as claims.system.clientSrcIp
When you use a Connector, take care because some system claims report the appliance instead of the user device. For example, clientSrcIP can be the public IP of the appliance, or the network IP if it sits behind a NATing firewall.
Name | Description | Example usage | Return values | Use to assign Policy |
|---|---|---|---|---|
| An action alert is triggered by the Gateway (ALERT must be selected in an entitlement). This claim is only available for use in conditions, not policies. |
| true/false | no |
| The IP of the client as seen by the AppGate ZTNA system.
|
| string | yes |
| The timestamp when the client connected to a specific Gateway. This claim is only available for use in conditions, not policies. |
| iso 8601 | no |
| A two-character code for the continent associated with the clientSrcIP address. The possible codes are: AF - Africa AN - Antarctica AS - Asia EU - Europe NA - North America OC - Oceania SA - South America |
| string | yes |
| A two-character ISO 3166-1 country code for the country associated with the IP address. |
| string | yes |
| The reported latitude of the device based on its geo IP location. |
| double floating | yes |
| The reported longitude of the device based on its geo IP location. |
| double floating | yes |
| The short code for subdivisions or regions such as Northamptonshire |
| string | yes |
| The IPaddress allocated to the user for a given Site - which has been mapped from the original user's IP pool address. |
| string | no |
| The IP address allocated to the user for a given Site - which has been mapped from the original user's IP pool address. |
| string | no |
| The IP address allocated to the user from one of AppGate ZTNA's IP pools. |
| string | no |
| The IP address allocated to the user from one of AppGate ZTNA's IP pools. |
| string | no |