Claims are key-value pairs that relate to the identity and context of the user or device and are specific to each session.
There are several types of claims:
Context. Based on helpers that evaluate things like is in the IP range.
User. Static, non-changing claims such as username from the IdP, user claims script, or 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.
And two classes of availability within the system:
Built-in (formerly Fixed). Set by the system; will always be gathered.
Scripted (formerly On-demand). Configured by the admin; gathered when required.
You can see specific users claims at any time from the dashboard. Under Active Sessions just click on the user's name to reveal all the session details.
Context based
As well as user-, device- and system-claims, there are helper functions to check user/device context.
Context based helpers (non-configurable)
Name | Description | Example usage | Return values | Usage^ |
|---|---|---|---|---|
System clientSrcIP in network | Uses the method isClientInNetwork to check if the system-claim clientSrcIp is in the specified subnet. | claims.system.isClientInNetwork('10.0.0.0/24') returns True if clientSrcIP is in the address range 10.0.0.0/24. | true/false | P C CS |
System clientSrcIP not in network | Uses the method isClientInNetwork to check if the system-claim clientSrcIp is not in the specified subnet. | claims.system.isClientInNetwork('10.0.0.0/24') returns True if clientSrcIP is not in the address range 10.0.0.0/24. | true/false | P C CS |
Device clientIPs in network | Uses the method isClientInNetwork to check if one of the device-claim clientIPs is on the specified subnet. | claims.device.isClientInNetwork('10.1.0.0/24') returns True if one of the clientIPs is in the address range 10.1.0.0/24. | true/false | P C CS |
Time is between | Uses the method inTimeRange to check if the time now (on UTC) is between specific start and end times. | inTimeRange(9, 15, 17, 30) returns True if the time now is between 09:15 and 17:30 | true/false | P C CS |
Day of week | Uses the method isDayOfWeek to check if it is one of the specified days. | isDayOfWeek(['mon','tue']) returns True if the day is Monday OR Tuesday | true/false | P C CS |
Identity Provider | Checks the claims.user.ag.identityProviderId and compares it to the UUID of the IdP. | Simply pick the IdP from the list of IdPs | true/false | P C CS |
ZTP Risk Rule | Uses the claims.user.ag.risk.score derived from a chosen ZTP rule name. | Pick the rule name and then the risk score for the access criteria to evaluate to true. | true/false | C |
Criteria Script | Uses the value from a script | Allows script value to be AND/ORed with other claims | true/false | 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, the format for user claims is: claims.user.#claim-name#
For example: ag.distinguishedName is used as claims.user.ag.distinguishedName
Name | Description and usage | Example usage |
|---|---|---|
ag.certValidTo | When a user signs in using a certificate then the "valid to" field is used to create a claim. | "certValidTo":"2018-07-11T15:58:34.596Z" |
ag.connectorSubnets | 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. | "connectorSubnets": [ "10.0.0.10/32" ] |
ag.distinguishedName | A unique combination of device, user and Idp which defines every session. The format comprises 3 claims concatenated together (see below). | "distinguishedName": "CN=864b8a5c-326e-4de3-acbc-db7762742e47,CN=john.smith,OU=ldap" |
ag.deviceId | Is a unique number that comes from the specific device (or is generated when one is not available) | 864b8a5c-326e-4de3-acbc-db7762742e47 |
ag.username | The username used by the AppGate ZTNA system. | john.smith |
ag.identityProviderName | In some cases this is a system generated name such as with a Connector resource group which will always be Connector | ldap |
ag.loginTime | 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 (i.e. sleeping device) | "loginTime":"2018-07-11T15:58:34.596Z" |
ag.passwordWarning | When a user signs in the AD the password expire warning can be read and used in warn the user. | true/false |
Default user-claims (configurable)
Default user claims collect information related to the user / device. Typically these are associated with the identity provider, user claim script or other trusted sources.
There is a default claim mapping for attributes that come from the Identity Providers. These can be changed using the Identity Providers > Map Attributes function.
Idp based attributes must be mapped for them to be available in AppGate ZTNA.
The table below provides example values for the default mapping.
If you are editing Conditions or Policy assignment expressions using script returns true mode, the format for user claims is: claims.user.#claim-name#
For example: a users first name would be held in claims.user.firstName; the return from a user claim script finding a user's shoe size would be held in claims.user.agScripted.shoe_size
Name | Usage | Description | Example usage |
|---|---|---|---|
agScripted | user claims script | Value returned after running a user claim script which will require some sort of javascript logic since the format is non-deterministic. | name:value(s) |
applianceName | Connector | The name given to the Connector appliance | 'appliance1' |
clientName | Connector | The client name within the Connector | 'client1' |
emails | local db & external IdP |
| 'john.smith@company.com' |
firstName | local db & external IdP |
| 'John' |
groups | external IdP |
| 'CN=Dev,CN=Test,OU=Group,DC=company' |
hostname | Connector | The hostname of the Connector appliance | 'appliance1.mycompany.com' |
id | local db & Connector | For users: the unique user id | '59057581-a0a0-4013-af0a-da422cc22eef' |
labels | k8s service Client | Value of any environmental labels associated with the Client which will require some sort of javascript logic since the format is non-deterministic. | name:value(s) |
lastName | local db & external IdP |
| 'Smith' |
phone | local db |
| '0123456789' |
tags | local db & Connector | For Users: tags set for that user (in local db) | 'admin' |
userId | external IdP |
| '864b8a5c-326e-4de3-acbc-db7762742e47' |
username | local db & external IdP | Default mapped claim from the IdP. | 'john.smith' |
User response claims (configurable)
Each user interaction has an associated internal claim: user.otpAuthentication.#name# user.passwordAuthentication.#name#
The claim name suffix is the #name# string defined in the Condition expression enabling 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 hasOtp to check the time when the user last entered a valid OTP for a particular user interaction. hasOtp requires two parameters: the "name" suffix of the OTP user interaction claim, and the maximum number of minutes before a new MFA must be entered. | Named - text string, no spaces Time interval - minutes
| claims.user.hasOtp( 'github', 60 ) Returns True if a valid MFA response to a user interactions was made less than 60 minutes ago. Checks the the claim otpAuthentication.github which includes the time when the MFA was entered. | true/false | no |
Retyped password | Uses the method hasPassword to check the time when the user last entered their password in response to a particular user interaction. hasPassword requires two parameters: the "name" suffix of the Password user interaction claim, and the maximum number of minutes before the user needs to re-enter their password. | Named - text string, no spaces Time interval - minutes | claims.user.hasPassword( 'finance', 60) Returns True if a valid Password response to a user interactions was made less than 60 minutes ago. Checks the claim passwordAuthentication.finance which includes the time when the password was entered. | true/false | 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, the format to use device claims is: claims.device.#claim-name#
For example: os.name is used as claims.device.os.name
Refer to Device Claims for more information about using these.
Name | Description | Example Usage | Return value | Use to assign Policy | Win | macOS | Linux | Android Chrome OS | iOS iPadOS^ | Connector | Portal |
|---|---|---|---|---|---|---|---|---|---|---|---|
browser.cpuArch | The CPU architecture | 'and64' | string | yes | - | - | - | - | - | - | ✓ |
browser.deviceType | The type of device in use | 'mobile' | string | yes | - | - | - | - | - | - | ✓ |
browser.engine | The underlying engine in use | 'Gecko' | string | yes | - | - | - | - | - | - | ✓ |
browser.isJavaEnabled | Checks if Java is enabled | false | true/false | yes | - | - | - | - | - | - | ✓ |
browser.name | The brand of browser in use | 'Firefox' | string | yes | - | - | - | - | - | - | ✓ |
browser.plugins | List of any plugins installed | 'Webkit built-in PDF' | string array | yes | - | - | - | - | - | - | ✓ |
browser.screenWidth | The width of the screen | '2560' | string | yes | - | - | - | - | - | - | ✓ |
browser.screenHeight | The height of the screen | '1440' | string | yes | - | - | - | - | - | - | ✓ |
browser.timezone | The browser's timezone | 'UTC' | string | yes | - | - | - | - | - | - | ✓ |
browser.version | The browser version | '87' | string | yes | - | - | - | - | - | - | ✓ |
clientIPs | List of the active interface IPs | '10.1.2.3' | string array | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ |
clientType *** | Type of Client being used | full Client | full | yes | ✓ | full | ✓ | full | full | connector | web |
clientVersion | AppGate ZTNA version | '1.0.2.230' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
crowdstrikeAid | This is the unique id that is included in the Crowdstrike data. This is only reported if there is a Crowdstrike agent installed. | '7f36913499434091b7ea55ad1c5a9fd5' | string | yes | ✓ | ✓ | - | - | - | - | - |
currentUser | The name of the user using the device. | 'Fred' | string | yes | ✓ | ✓ | ✓ | ✕ | ✕ | ✕ | ✕ |
deviceScriptsDisabled | Are device scripts disable | true | true-false | yes | ✓ | ✓ | ✓ | ✕ | ✕ | ✕ | ✕ |
dnsSuffixes | List of any local domain suffixes set. | abc.local | string | yes | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | ✕ |
domainName | The enrolled domain of the device | 'int.myco.com' | string | yes | ✓ | - | - | - | - | - | - |
fullDiskEncryption | The system disk is encrypted (requires >6.1.2 Client) | true | true/false | yes | ✓ | ✓ | - | - | - | - | - |
intuneDid | This is the unique id that is included in the Intune data. This is only reported if there is a Intune agent installed. | '7f36913499434091b7ea55ad1c5a9fd5' | string | yes | ✓ | ✓ | ✓ | - | - | - | - |
isAlwaysOn | Always-on has been installed. (Run Headless installer on macOS.) | true | true/false | yes | ✓ | ✓ | - | - | - | - | - |
isAzureDomain | Sets 'true' when | true | true/false | yes | ✓ | - | - | - | - | - | - |
isDomain | Domain registered device. | false | true/false | yes | ✓ | - | - | - | - | - | - |
isFirewallEnabled | Is the firewall enabled | true | true/false | yes | ✓ | ✓ | ✓ ^ | false | false | false | false |
isMultiUser | Is this in multi-user mode | true | true/false | yes | ✓ | - | - | - | - | - | - |
isUserAdmin | Does the user have Admin rights | true | true/false | yes | ✓ | true | false | false | false | false | false |
language | The language and region of the device | 'en_us' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | en-us | ✓ |
macAddresses | List of the interfaces mac addresses | '45e3e31264aa' | string array | yes | ✓ | ✓ | ✓ | ✕ | ✕ | ✓ ^^ | ✕ |
mdm_claim | Any MDM claims set when MDM is used to install a mobile Client | 'whatever' | string | yes | - | - | - | ✓ | ✓ | - | - |
os.family | Family of OS | 'macOS' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | linux | ✓ |
os.hostname * | The hostname of the connecting device | 'CZ-1234', Freds-MacBook.local | string | yes | ✓ | ✓ | ✓ | not available on newer OSs | not available on newer OSs | ✓ | ✓ |
os.name | Full name of operating system (OS) | 'Microsoft Windows 7 Professional' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | AppGate ZTNA | ✓ |
os.platform | Platform type of the OS | 'x64' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | x64 | unknown |
os.parent | Parent OS family (in Linux) | 'debian' | string | yes | - | - | ✓ | - | - | debian | - |
os.type | Type of OS | 'desktop' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | desktop | ✓ |
os.version | Version of OS | '12.0.0' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | 1.0 | unknown |
profileHostnames | Lists the hostnames from each profile | a.com, b.com, c.com | String | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
profileName | Name of the Client profile | 'corporate' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
reason.<name> ** | Value of the user response reason claim entered by the user | 'maintenance' | string | no | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ |
sentinelOneid | 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. | '7f36913499434091b7ea55ad1c5a9fd5' | string | yes | ✓ | ✓ | - | - | - | - | - |
spaKey | The name of the SPA key in use | 'myspakey' | string | yes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Where the returned value is: [shown] it's hard coded; [-] it's not collected; [✓] it returns measured value; [✕] it will not return any value.
* Windows always returns upper case.
** This claim will only appear on the drop down list once the Reason user interaction has been configured within the Condition.
*** The Always-on Client will report full or headless depending on the mode it is running in.
^ lsmod | grep ip_tables is used to evaluate this.
^^ The Connector reports the MAC of the veth for the namespace it runs in.
Scripted device claims (Formerly on-demand device-claims) (configurable)
Scripted claims can have the command and parameters passed to them to make them configurable. These are configured per identity provider, so will only be collected and reported when that IdP is used. If you are editing Condition or Policy assignment expressions using script returns true mode, the format to use device claims is: claims.device.#claim-name#
Where the #claim-name# is the name you assigned to it when you were configuring the scripted claim. Refer to Device Claims for more information about using these.
Command | Parameters | Measures | Return values | Use to assign Policy | Win | macOS | Linux | Android Chrome OS | iOS |
|---|---|---|---|---|---|---|---|---|---|
File Size | file path* | size of a file | integer in bytes | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
File Exists | file path* | checks if the file exists | true/false | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
File Created Timestamp | file path* | create date of the file | iso 8601 | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
File Updated Timestamp | file path* | last modification date of the file | iso 8601 | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
File SHA512 | file path* | sha512 of file | string | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
Process Running | process name | checks if a process is running | true/false | yes | ✓ | ✓ | ✓ | ✓ | ✕ |
File Version | file path* | [win] dll/exe version | string | yes | ✓ | ✕ | ✕ | ✕ | ✕ |
Registry Exists | query | [win] checks registry exists | true/false | yes | ✓ | ✕ | ✕ | ✕ | ✕ |
Registry Query | query | [win] checks value in registry | string | yes | ✓ | ✕ | ✕ | ✕ | ✕ |
Service Running | service name | [win] checks if a service is running | true/false | yes | ✓ | ✕ | ✕ | ✕ | ✕ |
✕ means it will not return any value.
* Paths may be defined using Environment Variables:
macOS - for files below the users home directory use %HOME% to resolve the users home directory; i.e.
%HOME%/Desktop/pic.jpg.Windows - for files below the users home directory use %HOMEPATH%, and then USE / AND NOT \ in your expressions; i.e.
%HOMEPATH%/Desktop/pic.jpg.
Custom scripted (formerly on-demand) device-claims (configurable):
By choosing 'Run Device Claim Script' it is possible to use a tailored script that returns a specific claim (using std out) to the AppGate ZTNA system.
These will only be collected and reported when configured.
These are configured per Identity Provider so will only be collected and reported when that IdP is used.
If you are editing Condition or Policy assignment expressions using script returns true mode, the format to use device claims is: claims.device.#claim-name# where the #claim-name# is the name you assigned to it when you were configuring the scripted claim. Refer to Device Claims for more information about using these.
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 will not return any value.
NOTE
Custom scripted device claims are not supported on Headless Clients.
User response claims (configurable)
The reason user interaction has an associated internal claim: device.reason.#name#
The claim name suffix is the #name# string 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# become exposed once the user has performed the user interaction. Conditions can therefore be based on the text entered by users in response to the Reason user interaction. The session details will show any reason claim under Device Claims as "#name#": "value". For more information refer to user interactions.
Name | Description | Parameters | Example usage | Return values | Use for Policy assignment |
|---|---|---|---|---|---|
Provided reason | Uses the method hasReason to check whether the user has typed in a reason in response to a particular user interaction. hasReason requires one parameter: the "name" suffix of the Reason user interaction claim. | Named - text string, no spaces | claims.device.hasReason( 'global' ) Returns True if the user has entered their reason in response to a user interaction. Checks the claim reason.global which includes the text the user entered. | true/false | no |
System claims
System claims (non-configurable)
All system claims are hardcoded 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, the format to use system claims is:
claims.system.#claim-name#
For example: clientSrcIp is used as claims.system.clientSrcIp
When using Connector care needs to be taken as the appliance itself will be reported in some of the System claims. By example, clientSrcIP will be public IP of the appliance or the network if it sits behind a NATing firewall.
Name | Description | Example usage | Return values | Use to assign Policy |
|---|---|---|---|---|
alert | 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 | true/false | no |
clientSrcIP | The IP of the Client as seen by the AppGate ZTNA system. claims.system.clientSrcIP is used in the Context Method <IP of client is in network> (see the Contextual Information section below) | '80.234.12.3' | string | yes |
connectTime | The timestamp when the Client connected to a specific Gateway. This claim is only available for use in Conditions, not Policies. | '2015-11-28T10:16:42Z' | iso 8601 | no |
geoIp.continentCode | 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 | 'EU' | string | yes |
geoIp.countryCode | A two-character ISO 3166-1 country code for the country associated with the IP address. | 'GB' | string | yes |
geoIp.latitude | The reported latitude of the device based on its geo IP location. | 51.8000 | double floating | yes |
geoIp.longitude | The reported longitude of the device based on its geo IP location. | -0.1900 | double floating | yes |
geoIp.stateCode | The short code for subdivisions or regions such as Northamptonshire | 'NTH' | string | yes |
mappedTunIPv4 | The IPaddress allocated to the user for a given Site - which has been mapped from the original user's IP pool address. | '10.1.2.3' | string | no |
mappedTunIPv6 | The IPaddress allocated to the user for a given Site - which has been mapped from the original user's IP pool address. | 'fd30::1:ff2e:3e:9:e' | string | no |
tunIPv4 | The IPaddress allocated to the user from one of AppGate ZTNA's IP pools. | '10.1.2.3' | string | no |
tunIPv6 | The IPaddress allocated to the user from one of AppGate ZTNA's IP pools. | 'fd30::1:ff2e:3e:9:e' | string | no |