Criteria scripts

Prev Next

The AppGate ZTNA system evaluates claims through assignment criteria expressions to make policy assignment decisions. In most cases, you can configure criteria in the policy by using the assignment options and the claims drop-down list; the UI generates the underlying JavaScript expression. In those cases, you do not need to write a separate script.

NOTE

Criteria scripts cannot be used in conditions.


Purpose of criteria scripts

You might want to use a criteria script instead of a Boolean expression for several reasons:

  • The Boolean expression you need is more complex than the builder supports.

  • You switched from custom logic is met to script returns true and then made an edit.

  • You need an external call to harvest claims from a third party system.

  • You want to use the same criteria expression across multiple policies.


Functionality of criteria scripts

When you use a custom script, it can reference existing user, device, and system claims. The script runs in the native, sandboxed JavaScript engine, which supports external httpGet/httpPost/httpPut/httpDelete calls. Use scripts sparingly and keep them efficient. After sign-in, the authorization process checks every policy (and runs any script present) to determine which rights apply. For example, if one script takes two seconds to run and the system must check 50 policies, evaluation can take 100 seconds. As an alternative, consider using a user claim script, which runs only once per sign-in.

  • After 3 seconds, the dashboard posts a warning message that names the offending policy.

  • After 15 seconds, the script times out.

  • After 15 seconds, the client also fails over to the next Controller, where this process might be repeated.


Before you create criteria scripts

Before you configure criteria scripts, consider the following:

  • The script runs on the Controller once per authenticated user, per policy. For example, 1,000 users authenticating with 100 policies configured results in 100,000 script runs.

  • The script runs in a sandboxed JavaScript engine that supports external httpGet/httpPost/httpPut/httpDelete calls.

  • To learn how assignment decisions are made, see Policy assignment.


Configuring criteria scripts

You can configure criteria scripts in the Criteria Scripts page, within a policy, or within a condition.

To configure a criteria script:

  1. Do to the Criteria Scripts page (Access > Criteria Scripts).

  2. Select +Add and complete the following fields:

    • Name. Enter a valid JavaScript name with no whitespace, dashes, or special characters. If you edit an existing script, changing the name might break existing configurations.

    • Notes. Optional. Add notes for the script.

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

    • Criteria Combining Mode. Select an option from the drop-down list:

      • All Criteria below must be true

      • At least one of the Criteria below must be true

      • Criteria are met according to Custom Logic

    • Criteria. Select +Add to open the Type drop-down list, and then select assignment criteria. Alternatively, select Switch to Script Mode to enter a script directly. For more information, see Configuring conditions. Criteria scripts use the same script view and JavaScript editor tools that are available when you configure policies directly. Create a criteria script if you plan to reuse it more than once.

  3. Save the script.

Policy assignment criteria scripts

To configure an assignment criteria script in a policy:

  1. Go to Policies (Access > Policies) and select the policy.

  2. In Edit Policy, go to Assignment Criteria and either:

    • Select Switch to script mode and enter the script directly.

    • Select +Add next to Criteria and select the criteria script from the drop-down list.

  3. Select Save.

If a user signs in and no policy is assigned, the system sends an admin message to the dashboard.


Managing criteria scripts

On the Criteria 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 Policies. Displays the policies linked to that criteria script.

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

  • Clone. Creates a copy of the criteria script.

  • Test. Tests the script and opens the Test Expression window. You can enter values to simulate claims, or switch to active session mode to test against an active session.