Claims in detail

Prev Next

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^

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.
The claim clientSrcIP returns the IP of the client as seen by the AppGate ZTNA system.

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.
The claim clientSrcIP returns the IP of the client as seen by the AppGate ZTNA system.

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.
The claim clientIPs returns the list of the active interface IPs.

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, 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

ag.certValidTo

When a user signs in using a certificate, 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 that defines every session. The format comprises three claims concatenated together (see below).
CN=ag.deviceId,CN=ag.username,OU=ag.identityProviderName

"distinguishedName": "CN=864b8a5c-326e-4de3-acbc-db7762742e47,CN=john.smith,OU=ldap"

ag.deviceId

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

"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 to warn the user.
Refer to LDAP provider settings.

true/false

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

agScripted

User claims script

Value returned after running a user claim script which will require some sort of JavaScript logic since the format is nondeterministic.

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
For Connector: the appliance 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 nondeterministic.

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)
For Connector: tags set for that appliance

'admin'
'connector-uk'

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, 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 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 reenter 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, 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

browser.cpuArch

The CPU architecture

'and64'

string

yes

-

-

-

-

-

-

✓

browser.deviceType

The type of device in use. Possible values are desktop, mobile, tablet, tv, and bot.

'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
Lite client
Headless (Windows & Linux)
SSO (Windows SSO)
(Connector)
Portal user

Full
Lite
Headless
SSO
Connector
Web

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 disabled

True

true-false

yes

✓

✓

✓

✕

✕

✕

✕

deviceSerial

The device's hardware serial number, when the platform can provide one.

'ABC1234567'

string

no

✓

✓

✓^^^

-

-

-

-

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
DSREG_DEVICE_JOIN has the value 1

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

The CPU architecture of the device, not the operating system. Possible values are x64, arm64, and arm. The Portal returns unknown. To identify the operating system, use os.family.

'x64'

string

yes

✓

✓

✓

✓

✓

x64

unknown

os.parent

Parent OS family (in Linux)

'debian'

string

yes

-

-

✓

-

-

debian

-

os.type

The type of device. Native clients return desktop or mobile. On the Portal, this claim returns the same value as browser.deviceType.

'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

✓

✓

✓

✓

✓

✓

✓

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
iPadOS

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 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 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)

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

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>

'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 IP address 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 IP address allocated to the user from one of AppGate ZTNA's IP pools.

'10.1.2.3'

string

no

tunIPv6

The IP address allocated to the user from one of AppGate ZTNA's IP pools.

'fd30::1:ff2e:3e:9:e'

string

no