--- title: "Entitlement scripts" slug: "entitlement-scripts-v7-0" description: "Entitlement scripts define app shortcuts, hosts, and ports, enabling dynamic resource resolution for efficient Gateway connections and firewall rules." tags: ["Scripts", "Entitlement Scripts"] updated: 2026-10-13T17:45:23Z published: 2026-10-13T17:45:23Z canonical: "support.appgate.com/entitlement-scripts-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # Entitlement scripts 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.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/three_dots.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A39%3A38Z&se=2026-11-21T22%3A39%3A38Z&sr=b&sp=r&sig=V0K1PFQsHFsljsTNAMn0BBO1Hq9lc6GbcpSGRt90Y5Y%3D)) 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 ```javascript 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 ```javascript 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 }]; ```