Claims and scripts

Prev Next

AppGate ZTNA supports scripting across most of the access control process flow. Scripts let the system interoperate with external systems and network environments, evaluate who might need access and when, and discover available hosts.

Scripts can perform complex logic, string manipulation, and calculations. They can also make limited HTTPS calls to external systems. For these calls, AppGate ZTNA includes a built-in Secrets store so credentials required for authentication are not exposed in scripts or related logs.

Claims are key-value pairs that describe the user, device, or session context. Scripts can collect, compute, or enrich these values, such as by gathering device information or querying an external system. The resulting claims are then used throughout the system to drive access control decisions.


Scripts

The following script types are used in AppGate ZTNA:

Requirements and considerations for using scripts

These advanced tools require structured design, engineering, and ongoing maintenance to avoid impacting system performance and end user experience. Consider the following before you start scripting:

Making calls to external systems

  • Pre-configure trusted certificates. Add certificates required for HTTPS communication with external systems to Trusted certificates.

  • Pre-configure any Secrets. Add credentials required to authenticate to external systems to the Secrets store. This ensures credentials are not exposed in scripts or related logs.

NOTE

This applies only to JavaScript-based scripts and does not apply to device claim scripts or resource names.

Security

Appliance JavaScript runs in a sandboxed Nashorn JavaScript engine built in to AppGate ZTNA. Sandboxing is enforced by the JavaScript engine configuration. For example, the engine does not allow access to the local file system and provides only a subset of Java functions (excluding btoa and atob).

Trust

Any script that passes through, or runs in, an untrusted environment should be treated as untrusted. For example, a device claim script is sent to an untrusted machine and harvests data that cannot be assumed to be reliable. The script may read a registry setting, but the device user may be able to set or influence that value.

Safety

The author of the JavaScript code and the customer are responsible for code safety and code review. For example, an endless loop can bring the system down because there is no execution time limit.

Audit

Scripts can inject log records into audit logs. This can help with diagnostics or provide an audit trail that shows how an access decision was reached. You can do this for:

  • Policy assignment scripts on Controllers

  • Condition and entitlement scripts on Gateways​

Include one or more audit log entries in your script, for example:

var result = true;
auditLog("OK");
return result;

NOTE

In audit logs, event_type is mandatory. For scripts, it appears as evaluation_log.

For more information about scripts, see:

Scripts supplied by AppGate​

Any script provided by the AppGate Professional Service team or as example scripts from the manual are delivered as is, without warranty of any kind.

AppGate disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose.

Any maintenance needs arising out of the use or performance of these sample scripts and related documentation remains the responsibility of the customer.


Claims

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.

The admin UI provides a dynamic list of claims you can use. Dialog boxes prompt you for the required parameter values.

System claims

These nonconfigurable claims are generated by the system. Some can be considered trusted (such as connectTime), but others should be evaluated case by case (such as clientSrcIP), which might be influenced by the user.

For information about the parameters, refer to Claims in detail.

User, device, and scripted claims

These include nonconfigurable claims, on-demand claims (which allow extra claims to be harvested), and scripts that generate custom claims. User claims are typically collected from authoritative sources such as LDAP and are generally trusted. Device claims should be evaluated case by case but are typically untrusted. The script, execution environment, and measurement points are all somewhat under the user’s control.

From a trust point of view, it can be better to use device and user claims together when you need to rely on claims about connecting devices. For example, a device script could collect a random 128-bit ID assigned to the device during an enterprise build process. The ID is untrusted because it comes from the device, but you can pass it in a user claim script to an authoritative external device database. If the database finds a matching ID, it can return trusted claims related to the device.  

The following sections explore device and user claims and explains how to configure the AppGate ZTNA system to gather additional claims.

For information about the parameters for each claim type, refer to their sections in Claims in detail.