Entitlement scripts

Prev Next

Entitlement scripts define the app shortcuts and related actions in an entitlement. The three types are:

  • App Shortcut. Defines the name, description, URL, and icon color for the app shortcut displayed in the client.

  • Host. Defines a resolvable name or IP address. If the script returns resource names, the name resolver later resolves them to IP addresses.

  • Port or Type. Defines one or more port numbers or ICMP types.

Entitlements that include scripts (based on user or device claims) run when the user connects to each Gateway. A script can create a resource name by concatenating a claim value (such as an AD attribute) with static syntax or a value returned from an external system. For example, if the result is esx://vm:<VALUE>, it is later resolved to IP addresses using the vSphere name resolver. This ability to resolve different VMs based on <VALUE> lets a single entitlement adapt at use time, which can significantly reduce the number of policies and entitlements required.


Functionality of entitlement scripts

Entitlement scripts can use any existing user, device, and system claims, including claims provided by the Controller in the claims token. Scripts run in a sandboxed JavaScript engine that supports external httpGet/httpPost/httpPut/httpDelete calls. They must return the appropriate response for the selected script type. For a host entitlement script, this can include IP addresses, hostnames, and resource names, allowing the system to populate Hosts, which is then used for Gateway firewall rules and client routes.

Scripts can request information from external systems that require credentials, which must be included in the JavaScript. Scripts used in entitlements and conditions are passed in the encrypted portion of the entitlement token.


Configuring entitlement scripts

To configure an entitlement script:

  1. Go to the Entitlement Scripts page (Access > Entitlement Scripts).

  2. Select +Add and select the script type. Then complete the following fields:

    • Name. Enter a name that uses only lowercase alphanumeric characters plus an underscore or dash. When you create actions in entitlements, host and port scripts are referenced using the syntax script://<name>. Editing the name of an existing script may break existing entitlements.

    • Notes. Optional. Add notes for the script.

    • Tags. Select +Add to add tags to the script.

    • Expression. An example expression is provided. Typically, the script should return same information you would enter when creating an entitlement manually.

  3. Save the script.


Managing entitlement scripts

On the Entitlement Scripts page, use the action button—the three dots icon (Three circular shapes stacked vertically on a dark background, selected to access a menu.) to the right of each line item—to access the following option:

  • View Linked Entitlements. Displays the entitlements linked to that script.

On the Add/Edit Entitlement Script page, use the Actions button to:

  • Clone. Creates a copy of the entitlement script.

  • Test. Tests the script and opens the Test Expression window. Enter values to simulate claims, or switch to active session mode to test agains an active session.


Examples

Host entitlement script example

onst tags = [];
const len = claims.user.groups ? claims.user.groups.length : 0;
for (let i = 0; i < len; i++) {
      tags.push("aws://tag-value:" + claims.user.groups[i].replace(/ /g, ''));
}
return tags;

In this example, the claims.user.groups value is taken from the claims token, parsed and cleaned, and then concatenated with aws://tag-value: to return aws://tag-value:<ad-groupname>.

This output matches a name resolver format that the system can use. In this case, it retrieves the IP addresses of hosts tagged with the same name as the user’s identity provider group attribute.

App shortcut entitlement script example

const name = "RDP-MyWorkstation";
const description = "App Shortcut to RDP to users workstation";
const fqdn = claims.user.MyWorkstation 
const url = "rdp://full%20address=s:" + fqdn + ":3389" 
const colorCode = 1
return [{ 
"name": name,
"description": description,
"url": url,
"groupName": "Workstation",
"colorCode": colorCode
}];