Handling access policies with Secure Private Access on-premises API

This topic provides instructions on how to create, list, update, and delete policies using the Secure Private Access API. Before starting with this API, understand the mandatory headers for all requests listed in Getting Started.

For more details about access policies, see the following topics.

• PoC Guide - Adaptive Access to SaaS and Private Web Apps.

1. Get a list of access policies

The following is an example of a GET request and response for getting a list of access policies:

GET https://{ hostUrl }:{ port }/accessSecurity/accessPolicy

Request header sample

...
Accept: application/json
Authorization: bearer { bearerToken }
...
<!--NeedCopy-->

Request parameters

A set of optional parameters can be used in the GET request:

A sample URL:

GET https://{ hostUrl }:{ port }/accessSecurity/accessPolicy?offset=0&limit=3&orderby=modified&name=TestPolicy

This API invocation requests the first three items from the collection of access policies which include TestPolicy in their name and are ordered by modified field.

Successful response sample

A 200 OK response with a JSON body:

{
    "items": [
        {
            ...Policy #1...
        },
        {
            ...Policy #2...
        },
        {
            ...Policy #3...
        }
    ],
    "totalNum": 10
}
<!--NeedCopy-->

The JSON object has an items array that contains the list of policy objects. The list can be whole or partial depending on the pagination parameters (offset, limit) used. The JSON object also has a totalNum property that contains the total number of policy objects that would be returned regardless of the pagination parameters.

Access policies object schema in the response body

Each policy object in the items array follows the schema below. Each property value is given as a string unless differently specified.

• id (read only). The universal unique identifier of the current policy.
• modified. The timestamp of when this policy was modified as a string following the ISO 8601 format, for example “2022-11-28T08:51:28Z”.
• apps. An array of app universal unique identifiers that this policy applies to.
• name. Indicates the name of this policy.
• description (optional). This field contains a short description of the policy.
• priority. An integer indicating the policy’s priority. For more details, see Create Policy - Priority Number in Policies.
• active. A boolean true or false indicating whether this policy is active or not.
• accessRules. This field represents an array of access rules comprising this policy. Each access rule object contains:
  • name (optional). Indicates the name of the access rule.
  • id (read only, not required). The universal unique identifier of the access rule.
  • description (optional). This field contains a short description of the access rule.
  • priority. An integer indicating the access rule’s priority.
  • active. A boolean true or false indicating whether this rule is active or not.
  • access. In multi-rule policies, this field can be set to capture the action for the HTTP apps. The value can be ACCESS_ALLOW or ACCESS_DENY indicating the type of the access rule.
  • accessNative (optional). In multi-rule policies, this field can be set to capture the action for the TCP apps. The value can be ACCESS_ALLOW or ACCESS_DENY indicating the type of the access rule.
  • restrictions. Additional restrictions given as an object containing:
    • redirectSBS (optional). A boolean true or false indicating whether Secure Browser Service must be redirected or not.
    • enhancedSecuritySettings. Additional enhanced security settings given as an object:
      • browserV1 (optional). Takes embeddedBrowser as the only value.
      • clipboardV1 (optional). This element restricts clipboard access, disables cut/copy/paste operations between the app and the system clipboard. The value can be disabled or enabled.
      • downloadV1 (optional). This element disables the user’s ability to download from within the app. The value can be disabled or enabled.
      • printingV1 (optional). This element disables the ability to print from within the Citrix Enterprise Browser. The value can be disabled or enabled.
      • toolbarV1 (optional). This element disables the toolbar in the Citrix Enterprise Browser. The value can be disabled or enabled.
      • watermarkV1 (optional). This element displays a watermark on the user’s screen displaying the user name and IP address of the user’s machine. The value can be disabled or enabled.
      • keyLoggingV1 (optional). This element enables protection against key loggers. All the keys are encrypted on the key loggers. The value can be disabled or enabled.
      • screenCaptureV1 (optional). This element disables the ability to capture the screens using any of the screen capture programs or apps. If a user tries to capture the screen, a blank screen is captured. The value can be disabled or enabled.
      • proxyTrafficV1 (optional). The value can be direct or secureBrowse.
      • uploadV1 (optional). This element disables the user’s ability to upload within the app. The value can be disabled or enabled.
  • rules. An array of rules that comprise this access rule. Each rule object contains:
    • type. This field indicates the rule type and takes one of TYPE_TAG, TYPE_USERGROUP, TYPE_PLATFORM, TYPE_MULTIURLDOMAIN or TYPE_MACHINEGROUP values.
    • operator. The operator field helps to represent the relation between values. Takes one of OPERATOR_EQ, OPERATOR_IN, OPERATOR_CONTAINS, OPERATOR_LTE, OPERATOR_GTE, OPERATOR_NOT, or OPERATOR_RANGE values. If the type of the rule is TYPE_MULTIURLDOMAIN, the operator should take the values OPERATOR_IN and OPERATOR_NOT.
    • tagSource (optional). Indicates the source of data retrieval. Takes one of CAS, EPA, NLS or ITM values. This field can’t be used if the type of the rule is TYPE_MULTIURLDOMAIN.
    • tagKey (optional). States the key of the tag, as the tags are key-value pairs. This field can’t be used if the type of the rule is TYPE_MULTIURLDOMAIN.
    • values. This field contains the values used in this rule.
    • metadata (reserved). States a JSON object that contains the metadata of the rule (can be empty/null).
  • conditions (optional). An array of conditions under which this access rule applies to. Each condition object contains:
    • userAndGroups. The user or groups where this access policy applies to. This is a JSON object that contains conditions (can be empty/null).
    • platformFilter (optional). This field indicates the platform. Takes one of PLATFORM_FILTER_MOBILE, PLATFORM_FILTER_PC, or PLATFORM_FILTER_ANY.

Successful response headers sample

Among other headers, a transaction ID can be used in the requests to follow.

...
Citrix-TransactionId: 2098daee-aea0-444c-9bae-f8b4fdb5d0b7
...
<!--NeedCopy-->

Potential unsuccessful responses

2. Get a specific policy

The following is an example of a GET request and response for getting a specific policy. The policy’s UUID is appended to the request URL:

GET https://{ hostUrl }:{ port }/accessSecurity/accessPolicy/{ policyUUID }

Request header sample

...
Accept: application/json
Authorization: bearer { bearerToken }
...
<!--NeedCopy-->

Successful response sample

A 200 OK response with a JSON body that contains a policy object:

{
    "id": "xH2DAi",
    "apps": [
        "nysCLV"
    ],
    "name": "TestPolicy",
    "description": "",
    "priority": 0,
    "active": false,
    "accessRules": [
        {
            "name": "Default Access Rule",
            "id": "qxpct8",
            "priority": 0,
            "active": true,
            "access": "ACCESS_DENY",
            "accessNative": "ACCESS_DENY",
            "rules": [
                {
                    "type": "TYPE_USERGROUP",
                    "operator": "OPERATOR_IN",
                    "tagSource": "",
                    "tagKey": "",
                    "values": [
                        "SID:/XX-XXXXXX-XXXXXXX-XXXX-XXXXXXXXX-XXX"
                    ],
                    "metadata": {
                        "adomain\\auser": "SID:/XX-XXXXXX-XXXXXXX-XXXX-XXXXXXXXX-XXX"
                    }
                }
            ],
            "conditions": []
        }
    ],
    "modified": "2024-12-16T15:50:49Z"
}
<!--NeedCopy-->

Successful response headers sample

Among other headers, a transaction ID that can be used in the requests to follow.

...
Citrix-TransactionId: 2098daee-aea0-444c-9bae-f8b4fdb5d0b7
...
<!--NeedCopy-->

Potential unsuccessful responses

3. Create a policy

The following is an example of a POST request and response for creating a new policy:

POST https://{ hostUrl }:{ port }/accessSecurity/accessPolicy

Request header sample

...
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: bearer { bearerToken }
...
<!--NeedCopy-->

Request body sample

{
    "apps":["nysCLV"],
    "active":false,
    "name":"newTestPolicy",
    "description":"",
    "accessRules":[
        {
            "active":true,
            "conditions":[],
            "rules": [
                {"metadata":{
                    "ak2": "SID:/XXXXXXXX-XXXX-XXXXX-XX-XXXXXX/"
                    },
                    "operator":"OPERATOR_IN",
                    "tagKey":"",
                    "tagSource":"",
                    "type":"TYPE_USERGROUP",
                    "values":["SID:/XXXXXXXX-XXXX-XXXXX-XX-XXXXXX/"]
                    }
             ],
             "name":"Default Access Rule",
             "access":"ACCESS_DENY",
             "priority":1
        }
    ]
}
<!--NeedCopy-->

Priority number in access policies

The priority property allows setting the priority of an access policy using a positive integer. Using spaced-out values for the priorities of different access policies allows for easier manipulation of policies’ order. When creating a new policy that needs to have the highest priority, check for the current highest priority by using a GET request. Then add a selected number to the current priority to set the new highest priority for the policy. For example, if the current priority is 12500, then set 20000 as the priority for the new policy. Priorities can change with PUT requests that update existing access policies. Users MUST take into account the priorities of the adjacent access policies (by getting them first) and calculating the new priority accordingly (for example with a value between them, in the middle).

Successful response sample

A 200 Created response with body:

{
    "id": "xH2DAi",
    "apps": [
        "nysCLV"
    ],
    "name": "newTestPolicy",
    "description": "",
    "priority": 0,
    "active": false,
    "accessRules": [
        {
            "name": "Default Access Rule",
            "id": "qxpct8",
            "priority": 1,
            "active": true,
            "access": "ACCESS_DENY",
            "accessNative": "ACCESS_DENY",
            "rules": [
                {
                    "type": "TYPE_USERGROUP",
                    "operator": "OPERATOR_IN",
                    "tagSource": "",
                    "tagKey": "",
                    "values": [
                        "SID:/XXXXXXX-XXXXXX-XXXXXXX-XXXX-XXXXXXXXX/"
                    ],
                    "metadata": {
                        "ak2": "SID:/XXXXXXX-XXXXXX-XXXXXXX-XXXX-XXXXXXXXX/"
                    }
                }
            ],
            "conditions": []
        }
    ],
    "modified": "2024-12-16T15:37:30Z"
}
<!--NeedCopy-->

Successful response headers sample

Among other headers, the location of the policy that was created containing its UUID and a transaction ID that can be used in the requests to follow.

...
Location:/accessSecurity/accessPolicy/xH2DAi
Citrix-TransactionId: 2098daee-aea0-444c-9bae-f8b4fdb5d0b7
...
<!--NeedCopy-->

Potential unsuccessful responses

4. Update a policy

The following is an example of a PUT request and response for Updating a specific policy. The policy’s UUID is appended to the request URL:

PUT https://{ hostUrl }:{ port }/accessSecurity/accessPolicy/{ policyUUID }

Request header sample

...
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: bearer { bearerToken }
...
<!--NeedCopy-->

Request body sample

{
    "apps":["nysCLV"],
    "active":false,
    "name":"UpdatedTestPolicy",
    "description":"",
    "accessRules":[
        {
            "active":true,
            "conditions":[],
            "rules":[
                {
                    "metadata":{"ak2": "SID:/XXXXXXX-XXXXX-XXXX-XXXXX-XXXXXXXXXX/,OID:/XXXXXXXXX-XXXXX-XXXX-XXX-XXXXXXXX"},
                    "operator":"OPERATOR_IN",
                    "tagKey":"",
                    "tagSource":"",
                    "type":"TYPE_USERGROUP",
                    "values":["SID:/XXXXXXX-XXXXX-XXXX-XXXXX-XXXXXXXXXX/]
                 }
               ],
            "name":"Default Access Rule",
            "access":"ACCESS_DENY",
            "priority":0
        }
     ],
    "priority":0,
    "id":"xH2DAi"
}
<!--NeedCopy-->

Successful response sample

A 204 NO CONTENT response with an empty body.

Successful response headers sample

Among other headers, a transaction ID that can be used in requests to follow.

...
Citrix-TransactionId: 2098daee-aea0-444c-9bae-f8b4fdb5d0b7
...
<!--NeedCopy-->

Potential unsuccessful responses

5. Delete a policy

The following is an example of a DELETE request and response for deleting a specific policy. The policy’s UUID is appended to the request URL:

DELETE https://{ hostUrl }:{ port }/accesssecurity/accessPolicy/{ policyUUID }

Request header sample

...
Accept: application/json
Authorization: bearer { bearerToken }
...
<!--NeedCopy-->

Successful response sample

A 204 NO CONTENT response with an empty body.

Successful response headers sample

Among other headers, a transaction ID that can be used in the requests to follow.

...
Citrix-TransactionId: 2098daee-aea0-444c-9bae-f8b4fdb5d0b7
...
<!--NeedCopy-->

Potential unsuccessful responses