Access Security

Modifying existing policies with Secure Private Access API

December 21, 2023

Contributed by:

This page showcases a use case where the user needs to modify all existing access policies to add another rule where the geolocation of the user is matching any country from a list of countries. This is done first by getting the list of all policies and then by updating each of them with a different request adding the new policy rule.

Prerequisites

{{Citrix-CustomerId}} for the specific Citrix Cloud Customer that owns the applications/access policies that must be extracted.
Bearer token. For details, see Getting started with Secure Private Access API.

1. Get all policies

The entire list of policies can be extracted by a GET request to the following endpoint, with the headers as described and without any other query parameters.

GET https://api.cloud.com/accesssecurity/accessPolicy

Request headers

Accept: application/json
Citrix-CustomerId: \{\{customerId\}\}
Authorization: CWSAuth Bearer=\{\{bearerToken\}\}
Citrix-TransactionId: \{\{Citrix-TransactionId\}\}
<!--NeedCopy-->

The Citrix-TransactionId header can be omitted.

Response example

A 200 OK response contains a JSON body like the following:

{
    "items": [
        {
            "id": "1f738e0a-7342-4f65-aa6c-af50c56dbfc7",
            "modified": "2022-10-27T09:05:58Z",
            "apps": [
                "1a1d2dce-f567-4369-8997-d4834fc64464"
            ],
            "name": "TestPolicy 1",
            "description": "TestPolicy Description",
            "priority": 73945,
            "active": false,
            "accessRules": [
                {
                    "name": "ACS-2634 Policy | no toolbar_v1 ",
                    "id": "1c052a01-dafa-45ff-8c8e-340975e1b1c4",
                    "description": "",
                    "priority": 1,
                    "active": true,
                    "access": "ACCESS_ALLOW",
                    "accessNative": "ACCESS_DENY",
                    "restrictions": {
                        "enhancedSecuritySettings": {
                            "browserV1": "embeddedBrowser",
                            "watermarkV1": "enabled"
                        }
                    },
                    "rules": [
                        {
                            "type": "TYPE_USERGROUP",
                            "operator": "OPERATOR_IN",
                            "tagSource": "ITM",
                            "tagKey": "",
                            "values": [
                                "SID:/03fc0b3d-7641-4236-8e39-a4d5da073edb/S-1-5-21-3251101242-2954149830-320600214-16714",
                                "OID:/ad/None:9df11d6a-8588-42ca-a3ed-6c4b3d1a5f43",
                                "SID:/03fc0b3d-7641-4236-8e39-a4d5da073edb/S-1-5-21-3251101242-2954149830-320600214-16427",
                                "OID:/ad/None:959bbf6a-61bf-440a-b8be-a4a8f26ef3e5"
                            ],
                            "metadata": {
                                "ak2": "SID:/03fc0b3d-7641-4236-8e39-a4d5da073edb/S-1-5-21-3251101242-2954149830-320600214-16714,OID:/ad/None:9df11d6a-8588-42ca-a3ed-6c4b3d1a5f43",
                                "ak3": "SID:/03fc0b3d-7641-4236-8e39-a4d5da073edb/S-1-5-21-3251101242-2954149830-320600214-16427,OID:/ad/None:959bbf6a-61bf-440a-b8be-a4a8f26ef3e5"
                            }
                        }
                    ]
                }
            ]
        },
        {
            "id": "7a738d4d-c6fb-46bf-8cdd-ba19097d25e6",
            "modified": "2022-12-06T12:41:55Z",
            "apps": [
                "b1030399-2312-4374-85a4-da6910da253e"
            ],
            "name": "TestPolicy 2",
            "description": "TestPolicy Description",
            "priority": 22920,
            "active": true,
            "accessRules": [...]
        },
        {
            "id": "e04f4bcb-807e-4743-8d4d-6a19e805f0c5",
            "modified": "2023-01-31T08:37:31Z",
            "apps": [
                "b1030399-2312-4374-85a4-da6910da253e"
            ],
            "name": "TestPolicy 3",
            "description": "TestPolicy Description",
            "priority": 12604,
            "active": false,
            "accessRules": [...]
        },
        {
            "id": "f75a4eab-5c5c-46cf-9155-42ee0e067902",
            "modified": "2023-02-03T13:13:23Z",
            "apps": [
                "b1030399-2312-4374-85a4-da6910da253e"
            ],
            "name": "TestPolicy 4",
            "description": "TestPolicy Description",
            "priority": 12202,
            "active": true,
            "accessRules": [...]
        }
    ],
    "totalNum": 4
}
<!--NeedCopy-->

The JSON object can be parsed and the policies retrieved from the items array. The preceding example shows the rule for the first policy, the rules for the rest are similar.

2. Update policies

For each of the policies retrieved from the GET request, the user must do a PUT request to update it, and add the new policy rule. The policy’s UUID is appended to the request URL for each request:

PUT https://api.cloud.com/accesssecurity/accessPolicy/{{policyUUID}}`

Request headers

Accept: application/json
Content-Type: application/json; charset=utf-8
Citrix-CustomerId: \{\{customerId\}\}
Authorization: CWSAuth Bearer=\{\{bearerToken\}\}
Citrix-TransactionId: \{\{Citrix-TransactionId\}\}
<!--NeedCopy-->

The Citrix-TransactionId header can be omitted but it is encouraged to use the Citrix-TransactionId returned by the previous GET request so that this particular stream of requests can be traced, in case support is needed.

Request body example

{
    "modified": "2022-10-27T09:05:58Z",
    "apps": [
        "1a1d2dce-f567-4369-8997-d4834fc64464"
    ],
    "name": "TestPolicy 1",
    "description": "TestPolicy Description",
    "priority": 73945,
    "active": false,
    "accessRules": [
        {
            "name": "ACS-2634 Policy | no toolbar_v1 ",
            "id": "1c052a01-dafa-45ff-8c8e-340975e1b1c4",
            "description": "",
            "priority": 1,
            "active": true,
            "access": "ACCESS_ALLOW",
            "accessNative": "ACCESS_DENY",
            "restrictions": {
                "enhancedSecuritySettings": {
                    "browserV1": "embeddedBrowser",
                    "watermarkV1": "enabled"
                }
            },
            "rules": [
                {
                    "type": "TYPE_USERGROUP",
                    "operator": "OPERATOR_IN",
                    "tagSource": "ITM",
                    "tagKey": "",
                    "values": [
                        "SID:/03fc0b3d-7641-4236-8e39-a4d5da073edb/S-1-5-21-3251101242-2954149830-320600214-16714",
                        "OID:/ad/None:9df11d6a-8588-42ca-a3ed-6c4b3d1a5f43",
                        "SID:/03fc0b3d-7641-4236-8e39-a4d5da073edb/S-1-5-21-3251101242-2954149830-320600214-16427",
                        "OID:/ad/None:959bbf6a-61bf-440a-b8be-a4a8f26ef3e5"
                    ],
                    "metadata": {
                        "ak2": "SID:/03fc0b3d-7641-4236-8e39-a4d5da073edb/S-1-5-21-3251101242-2954149830-320600214-16714,OID:/ad/None:9df11d6a-8588-42ca-a3ed-6c4b3d1a5f43",
                        "ak3": "SID:/03fc0b3d-7641-4236-8e39-a4d5da073edb/S-1-5-21-3251101242-2954149830-320600214-16427,OID:/ad/None:959bbf6a-61bf-440a-b8be-a4a8f26ef3e5"
                    }
                },
                {
                    "type": "TYPE_TAG",
                    "operator": "OPERATOR_IN",
                    "tagSource": "ITM",
                    "tagKey": "location-geo-country-isocode",
                    "values": [
                        "US",
                        "IN",
                        "GR"
                    ],
                    "metadata": {
                        "US": "United States",
                        "IN": "India",
                        "GR": "Greece"
                    }
                }
            ]
        }
    ]
}
<!--NeedCopy-->

The JSON in the payload for each policy must be the same as it was given from the previous GET request, apart from the id field that is given in the URL path and the new rule object appended to the rules array. If the update was successful, a 204 NO CONTENT response is returned.

For more details regarding the GET requests to get the policies list and the schema of the response, see Handling Policies with Secure Private Access API - Get List of Policies.
For more details regarding the PUT requests to update a specific policy and the schema of the JSON payload, see Handling Policies with Secure Private Access API - Update Policy.

3. Modifying a policy from the Secure Private Access service user interface

Log in to Citrix Cloud.
Click the Manage tab in the Secure Private Access tile.
In the navigation pane, click Access Policies and you can see the list of the policies.
To edit a specific access policy, click the ellipsis button, and then click Edit.
In the Policy rules section, select the policy and click Edit.

For more information about handling access policies from the Secure Private Access service UI, see Create access policies.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

Access Security OpenAPI Specification

Copy Download

Modifying existing policies with Secure Private Access API

December 21, 2023

Contributed by:

December 21, 2023

Contributed by:

Modifying existing policies with Secure Private Access API

Prerequisites

1. Get all policies

Request headers

Response example

2. Update policies

Request headers

Request body example

3. Modifying a policy from the Secure Private Access service user interface

Resources

Access Security OpenAPI Specification

In this article

Resources

Access Security OpenAPI Specification