Configuring custom Watch Folder permissions policies

By default, users are not allowed to perform any Watch Folders related actions, unless they are configured with admin ACLs. If you do not want every user to have admin permissions, configure users with customized permissions policies, including whether they are allowed or denied permission to create Watch Folders, create Watch and Watch Folder services, and edit policies. The policy is a JSON object that is assigned to specific users. Users can be assigned to multiple policies to incrementally allow or deny permissions.

Note: The access_control Node API parameter that was used to manage access to the watchfolders and async APIs was deprecated. This API will be removed in a future version.

Create a permission policy

Run the following command:

# curl -k --user node_api_user:node_api_password -X POST -d @path/to/json_file https://localhost:9092/access_control/policies

Where the JSON file contains the permissions policy, as described in the next section. The Node API user must have permission to create policies to run this command.

Policy syntax

A permissions policy is a JSON object with the following syntax:

{
   "id": "policy_name",
   "statements": [
      {
         "effect": "effect_value",
         "actions": [
            "permission_1",
            "permission_2",
            ...
            "permission_n"
         ],
         "resources": [
            "resource_id"
         ]
      }
   ]
}

The placeholders take the following values:

policy_name: A descriptive name for the policy, such as only-wfd-aspera. If no value is specified, a UUID is generated and returned in the output when the policy is created.
effect_value: Set to ALLOW or DENY.
permission: An action that the user is allowed or denied, depending on effect_value. Values can use * to match any sequence of characters. For example, to allow all Watch Folder related actions, enter WF_*. See the following section for a complete list of permissions.
resource_id: For Watch Folder-related permissions, specify the resources to which the actions apply by their Aspera® Resource Name (ARN), by using the following general syntax:
```
arn:service:resource_type:resource
```
Where service identifies the product (watchfolder or watch), resource_type is the type of resource (wfd for a Watch Folder daemon, wf for a Watch Folder), and resource is the resource ID, or a series of IDs to specify the daemon and Watch Folder ID of a specific Watch Folder. See the following section for examples.

Actions

The following actions are permissions to create, delete, and view policies, and assign users to policies. These actions do not require that you specify a value for resources. To allow all permissions, use PERM_*.

PERM_CREATE_POLICY
PERM_DELETE_POLICY
PERM_LIST_POLICIES
PERM_ATTACH_USER_POLICY
PERM_DETACH_USER_POLICY
PERM_LIST_USER_POLICIES

The following actions create, delete, and view Watch and Watch Folder services. These actions do not require that you specify a value for "resources". Users without these permissions must create Watch Folders that use existing Watch and Watch Folder services.

PERM_LIST_RESOURCES
PERM_CREATE_RESOURCE
PERM_DELETE_RESOURCE

The following actions create and delete Watch Folders. These actions require that you specify the wfd resource, as arn:watchfolder:wfd:daemon. To allow actions on Watch Folders as any daemon, use arn:watchfolder:wfd:*.

WF_CREATE_WATCHFOLDER
WF_DELETE_WATCHFOLDER

Note: Node API users must have PERM_LIST_RESOURCES allowed, so it can allow WF_CREATE_WATCHFOLDER or WF_DELETE_WATCHFOLDER.

The following actions retrieve Watch Folder configuration and state, update the Watch Folder, and retry a Watch Folder drop. These actions require that you specify the wf resource, as arn:watchfolder:wf:daemon:watchfolder_id. To allow actions on any Watch Folders run by any daemon, use arn:watchfolder:wf:*:*.

WF_GET_WATCHFOLDER
WF_GET_WATCHFOLDER_STATE
WF_UPDATE_WATCHFOLDER
WF_RETRY_DROP

To allow all Watch Folder actions on all Watch Folders, enter "WF_*" as the action and "arn:watchfolder:wfd:*" as the resource.

Sample policies

Allow the user to view policies and user permissions:

{
   "id": "read-permissions",
   "statements": [
      {
         "effect": "ALLOW",
         "actions": [
            "PERM_LIST_*"
         ],
         "resources": []
      }
   ]
}

Allow the user to do all Watch Folders actions:

{
  "id": "all-watch-folders",
  "statements": [
    {
      "effect": "ALLOW",
      "actions": [
        "WF_*",
        "PERM_LIST_RESOURCES"
      ],
      "resources": [
        "arn:watchfolder:wfd:*"
      ]
    }
  ]
}

Assigning Node API users to policies

Assign a user to one or more policies by running the following command:

# curl -k --user node_api_user:node_api_password -X PUT -d {"policies":["policy_id1", "policy_id2"]} https://localhost:9092/access_control/users/username/policies

You can also assign a policy to multiple users at once:

# curl -k --user node_api_user:node_api_password -X PUT" -d {"users":["user1", "user2"]} https://localhost:9092/access_control/policies/policy_id/users

To retrieve the IDs of available permissions policies, run the following command:

# curl -k --user node_api_user:node_api_password -X GET https://localhost:9092/access_control/policies

To view the permissions policies that are assigned to a user, run the following command:

# curl -k --user node_api_user:node_api_password -X GET https://localhost:9092/access_control/users/username/policies

To view the users that are assigned to a permissions policy, run the following command:

# curl -k --user node_api_user:node_api_password -X GET https://localhost:9092/access_control/policies/policy_id/users

Editing policies

To edit a policy, create a JSON configuration file as if you were creating a new policy, but do not include the "id". Run the following command to update the policy:

# curl -k --user node_api_user:node_api_password -X PUT -d @path/to/json_file https://localhost:9092/access_control/policies/policy_id

To retrieve the configuration of an existing policy, run the following command:

# curl -k --user node_api_user:node_api_password -X GET https://localhost:9092/access_control/policies/policy_id

Note: The policy name ("id") cannot be edited. To change the name, create a new policy.