Configure Entitlements

Entitlements define the network resources users and devices will be allowed to access. Review the Before you start section before configuring.

Actions

The Actions menu allows you to: clone the item for use within this system, export the item for use in another system (see import), or delete the item.

Add/Edit Entitlement

To create or edit an Entitlement, you will configure the access rights and any Client app shortcuts. Select +Add to create a new Entitlement or select an existing Entitlement to edit.

Access Rights

To configure access rights, enter values in the following fields of the Edit Entitlement page:

• Site. An Entitlement normally applies to one Site. Any hostnames, URLs, resource names or scripts used in Actions are resolved according to Site-specific configurations.

NOTE

Even if you plan to use an Exclude Action (below) then a Site is still needed to resolve the excluded IPs.

• Actions. Actions define the network access rights. Normally, the Rule will use ALLOW, however BLOCK, ALERT and EXCLUDE can also be specified.

• Action settings.All actions are given a reference number (#0, #1, etc.). These allow you to correlate the Action defined in the Entitlement with what later appears in session details and the audit logs. This is important as the Action might show a script and the session details an IP address - so it can be hard to understand where this rule came from! These numbers are just for reference and do not set any priorities or precedence. Rules relating to Action precedence are covered in Overlapping Entitlements. See Defining Hosts for more detailed information.

  • Hosts - Target or Source. Add one or more Host definitions. For UP protocols this will be the TARGET, for DOWN protocols this will be the SOURCE.

  • Target/Source. Enter one or more comma-separated host definitions. Only IP addresses are automatically split when entered as a comma-separated list. Non-IP entries will be treated as a single value.

You can test your name resolver syntax in Sites.

Multiple host definitions of the same type are allowed. However for each type used, the resolvers will be used in the order in which they appear and once a valid result is obtained then any remaining ones will be ignored.

• Create Name by Resolver. Select the type of resolver (defined for the Site) then pick the Resource Type, Name/Id and Value. If you have already defined one or more resolvers for the Site (selected in this Entitlement) then they should be listed. Clicking one will launch the JSON builder which will query the provider in real time to discover the allowed resource types, names/id and values related to that resource type. The builder is provided as a helper to automatically retrieve information from your environment and to avoid you making any typos. You may need to edit the JSON afterwards depending on the desired outcome.

  • Tags in Azure and AWS take the form of key:value pairs, so for tag related queries you need to set both the tag-key and the tag-value.

  • The builder supports regions and accounts in AWS but these are only qualifiers and not actual resources, so you still need to enter some actual resource by hand or copy it from another JSON resource name where an actual resource is specified.

  • Similarly, projects-ids are supported in GCP which is only a qualifier, so again actual resources must be specified.

For example if you select projects-ids you will get a name like gcp://{"projects-filter":"id:appgate"} and if you select instances network tags you will get a name like gcp://{"instances-network-tags":"prometheus"}. You can then combine them to create the final JSON syntax - gcp://{"projects-filter":"id:appgate","instances-network-tags":prometheus"}.

• Rule. ALLOW is the default for traffic. You can select BLOCK; ALERT (& BLOCK) to monitor for irregular network traffic; EXCLUDE to not route traffic.

Entitlements need to specifically define which rule should be applied for any defined hosts(s):

• No rule found: as with most firewalls, if nothing is defined, then the Gateway has a default deny access when the Client sends traffic to it.

  • This will report action:drop  in the audit logs.

  • With a web Client (Portal) this will send a RST to the Client and report action:reject.

• <ALLOW> will route Client traffic to/from the firewall where traffic will be allowed to pass.

  • This will normally  report action:allow in the audit logs.

  • When there is a condition linked to the Action that is about to expire (5 mins), then this will report action:allow_report in the audit logs.

  • When there is a condition linked to the Action that has not been met (or has expired), then this will report action:block_report in the audit logs.

• <BLOCK> can be useful to prevent access to specific hosts in the middle of an allowed range or to invoke route optimization within the AppGate ZTNA Clients.

  • This will  report action:block in the audit logs.

• <ALERT> will detect traffic matching the specified host(s). <ALERT> includes an implied <BLOCK>. It will also sets a local claim on the appliance (which therefore performs a re-evaluation). This claim can be used to trigger a response from an external SIEM system.

  • This will report action:block_report in the audit logs.

NOTE

This claim is not shared at the Collective level - so a Gateway in a Site might have this claim set for a given user, but after a roaming event the user might now end up on a different Gateway where that claim will not be set.  

• <EXCLUDE> will be applied to the local routes in the Client (and is controlled by the host OS in the normal way). This can be useful when using the Route all traffic through tunnel option (default gateway) and you want to exclude some specific applications - such as video meetings which can then be defined using the *.domain.com host syntax. It can also be useful for excluding a sub-domain from much larger sub-domain which may have been allowed.

  • This will not report in the audit logs as the traffic never hits the Gateway.

NOTE

<EXCLUDE> has no effect on any firewall rules on the Gateway, and any features that rely on traffic being sent to the Gateways (such as user interactions) will not work when this is used.

• Protocol. Select the protocol & direction. The default, TCP up, allows traffic from Client to Gateway. Depending on the Protocol choice you may need to enter additional parameters:

NOTE

Down rules don't always work i.e. if using source NAT on a Site or using the Express Connector.

• Ports. Enter one or more comma-separated (Host) Ports using: Port, Port range and/or Entitlement script.

• Types. Enter any combination of ICMP Types, Type ranges and/or Entitlement scripts (commas-separated). For information about ICMP type numbers refer to: https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol

NOTE

When using a Port or Type Entitlement script to populate the Port or Type (entered as: script://name), this must have already been uploaded. Refer to Entitlement Scripts.

• Methods. You can restrict the HTTP methods allowed - to match the web service being protected. For instance just GET, POST and HEAD.

• Specify. Select one or more HTTP methods that are to be allowed.

• Enable Monitoring.You can monitor TCP and HTTP return traffic and flag an Action as being unhealthy. This may invoke Client failover to an alternative Gateway.  This should be restricted to just a few critical applications which:

• will trigger a warning in the dashboard and will show the Gateway as being unhealthy when 25% or more of users on a Gateway are reporting the same Action as being unhealthy.

• may cause the Client to failover to a different Gateway (this will depend on the Client's knowledge of the state (unhealthy or not) of the other Gateways).

NOTE

There are some specific requirements when monitoring is in use. The related Action must have a singular Network Resource defined. Ranges count as a singular definition. So both 10.1.2.3 and 10.1.2.0/24 are allowed. Comma separated lists of IP addresses are NOT allowed. Hostnames and Resource Names must resolve to singular Network Resources.

• Response timeout. Set the monitoring sensitivity - short response timeouts will make unhealthy detection more sensitive.

• Access Control. Select how you would like the system to control access to this Entitlement.

• Always Allow Action(s). The Action will always be permitted. It is recommended that you consider using stricter access controls to protect resources. This option is the default.

• Risk Based Access (deprecated). Select the sensitivity of the Entitlement being configured. This will be combined with the user risk score (an externally derived claim) to DENY or ALLOW the Action (or trigger a USER ACTION such as MFA). Here you should select whether you consider this Entitlements to be of High, Medium or Low Sensitivity. This relates to the three horizontal rows in the Risk matrix and will affect the outcome based on the user risk column that applies.

• Condition Based Access. Combine one or more pre-defined Conditions to decide the outcome (or trigger user interactions). Conditions have two combining modes:

• <all below are true> - a logical AND of different Conditions that need to equate to true

• <any below are true> - a logical OR of different Conditions that need equate to true

Conditions need to be pre-configured before using them here.

NOTE

If Condition-based access is specified with None then the system will show Never Allow Actions(s) against this Entitlement.

Client App Shortcuts

To configure Client app shortcuts, enter values in the following fields:

• Static Shortcuts. Add clickable app shortcuts which will be presented in the Client. Shortcuts make life easy for the users who do not need to know (or have bookmarked) the URL/URI of a specific resource they might want to access. AppGate ZTNA Clients include multi-page views of app shortcuts which launch the appropriate app and load the specified URL/URI. Users can pin their favorite app shortcuts which will then appear on the first page. In addition to the usual http:// and https:// shortcuts, rdp:// and ssh:// are also supported.

App shortcuts are optional and if the intention is to just provide background connectivity to a /24 network then they may not be required. However it is possible to include multiple app shortcuts in one Entitlement - so even if you are providing access to a /24 network it would still be possible to cherry pick a few frequently used applications in that /24 network and publish them as shortcuts.

• Shortcut Name. This is the app shortcut name that is shown in the Client. Try to keep these names short - 12-16 characters, as more may get truncated due to the small form factor of the Client UI.

• Shortcut Group. Grouped shortcuts will be shown together in the Client.

Groups are shown before any un-grouped shortcuts and they will appear in alphabetical order with numbers taking precedence over letters.

• Shortcut Description. This text is shown in the Client when the user opens the shortcut details.

• Shortcut URL. This URL will be used to launch the app. The URL will be typically be in the form http:// or https:// so will launch the default browser and go to the defined URL.  Any URIs that follow the format <scheme>://<more> is supported by AppGate ZTNA as long as <more> meets the additional syntax requirements set out in https://docs.oracle.com/javase/7/docs/api/java/net/URI.html and passes syntax checking.

Other URIs need to be recognized by the operating system of the user's device. This is very dependent on the OS; some OSs natively register certain URIs - macOS for instance will open Terminal when it encounters ssh://host and Finder when it encounters smb://host/folder. Some applications register an appropriate URI when they are installed - Microsoft Remote Desktop desktop for instance registers rdp:// when it is installed. Perhaps the least well supported operating system in this regard is Windows. The AppGate ZTNA Client has built in support for Windows in order to support the use of ssh:// and rdp://. If neither of these URIs are registered already then the AppGate ZTNA Client will register mstsc.exe for rdp:// and either Putty or Windows own Command Prompt for ssh://.

A typical example might be ssh://my_linux_server.my_company

For rdp:// the AppGate ZTNA Client will honor a number of the parameters defined in https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-uri in order to try to make the behaviors the same across the different OSs.

Multiple RDP parameters are separated using the ampersand symbol (&). For example, when connecting to a PC, the string is:

rdp://full%20address=s:10.1.23.45:3389&screen%20mode%20id=i:2

• Icon Color. Pick one of the standard colors for the launch icon.

• Preview. This is the worst case app shortcut appearance. Larger screen devices will show more characters.

• Dynamic Client App Shortcuts from Entitlement Scripts. Select an app shortcut Entitlement script which defines what will be presented in the Client. When you use an Entitlement script to populate Client App Shortcuts, this can be done in conjunction with the static ones detailed above. The App Shortcut Entitlement Script should have already been uploaded.