Configuring device claim scripts

Prev Next

Device claim scripts create scripted (formerly on-demand) device claims. You select them in identity providers (IdPs). Device claim scripts are stored in the AppGate ZTNA system, pushed to the client, and executed on the user's device every five minutes. Any claim changes are then reported. If the scripts are not already present, the client downloads them at authentication.

In AppGate ZTNA version 6.6 and later, device claim scripts are disabled by default. The client executes scripts only from profiles with verified DNS names.

WARNING

If you have not yet updated to version 6.6 and you plan to continue using device claim scripts after you upgrade, you must obtain an updated license file before upgrading your Collective to 6.6.


Before configuring device claim scripts

Before configuring device claim scripts, consider the following:

  • Device claim scripts are not executed until AppGate Support verifies profile DNS names.

  • Device claim scripts are not executed if the client is running in elevated/administrator mode.

  • Device claim scripts must be able to execute on the target platform and run without requiring admin rights.

  • Device claim scripts should return values through stdout which are then evaluated for true/false.

  • Supported, platform-dependent script formats are: .exe, .sh, .bat, .vbs, and .ps1. Others formats might run but are unsupported.


Adding a device claim script

To create a device claim script:

  1. Go to the Device Claim Scripts page (Identity > Device Claim Scripts).

  2. Select +Add, and complete the following fields:

    • Name. Enter the name used when mapping scripted (formerly on-demand) device claims for an IdP. If you edit an existing script, changing the name might break existing policies.

    • Notes. Optional. Enter notes for the script.

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

    • Filename. Auto-populates with the original filename of the uploaded script, but it can be edited. The client device uses this filename when executing scripts.

    • File. Select Choose a file… to upload the script. Supported formats are .exe, .sh, .bat, .vbs, and .ps1. If you edited an existing script, upload the revised file to overwrite the file currently stored in the client.

  3. Save the scripts.

During authentication, the client downloads device claims scripts and stores them on the device. Before running a script, the client verifies its checksum with the Controller to confirm it was not corrupted. If the checksums do not match, the client downloads the script again. This ensures the client downloads and runs the latest version.

Verifying the profile DNS name

You must verify the profile DNS name before you can execute device claim scripts.

To do this:

  1. Send a request to AppGate Support for an updated license file, which enables device claim scripts for your Collective.

  2. AppGate Support verifies your identity and confirms that your team owns the provided list of profile DNS names. AppGate Support then exports a license from your customer account in the SDP License Server.

  3. After you receive the license, upload it to your Controller (Settings > Licenses > Upload License button).

  4. After you upload the license, sign out and sign back in to the AppGate client. When the client connects to your Controller, it sends the relevant section of the license file, along with the device claim script, to the client.

  5. The AppGate client verifies the license signature and confirms that the profile DNS name is on the list. If validation succeeds, the device claim scripts are executed.


Enabling device claim scripts

Enable device claim scripts by IdP:

  1. Go to the Identity Providers page and select an IdP type.

  2. Under Scripts Mapped to Device Claims, select +Add to add a new claim.

List of scripts mapped to device claims for Windows and macOS devices.

  1. In the Script Mapped to Device Claim window, select the required script from the drop-down list and configure the required fields.

    Configuration settings for a script mapped to a device claim on macOS.

  2. You can now select the new claim Device Claims in assignment criteria drop-downs in Policies and Criteria Scripts, and from the access criteria drop-down in Conditions.  

Running a device claim script

To run a device claim script:

  1. Go to the Identity Providers page (Identity > Identity Providers).

  2. Select the IdP, and then go to Scripts Mapped to Device Claims.

  3. Select +Add and in the Script field select Run Device Claim Script.

  4. Complete the remaining required fields, and then select Save.

The script output is mapped to the specified device claim.

NOTE

Device claims that return yes/no or true/false are evaluated as strings. Values that should not be treated as strings must be handled using <script returns true> mode.

NOTE

Custom scripted device claims are not supported on headless clients.


Managing device claim scripts

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:

  • Download Script. Downloads the script to your machine.