Azure Data Lake Storage Gen2 REST API

Access Control

This section details the REST API operations for managing access control lists (ACLs) for files and directories in Azure Data Lake Storage Gen2.

Understanding ACLs

ACLs define permissions for specific users and groups on files and directories. They are hierarchical, meaning permissions set on a directory are inherited by its contents, subject to the ACLs defined on those contents.

Key Concepts

Read (r): Allows viewing file/directory contents or listing directory contents.
Write (w): Allows modifying file content or creating/deleting files/subdirectories.
Execute (x): Allows entering a directory or executing a file.
Owner: The user who owns the file or directory.
Owning Group: The group associated with the file or directory.
Other: Permissions for users not explicitly listed in the ACL.
Default ACLs: Applied to newly created entities within a directory.

REST API Operations

Get Access Control List (ACL)

Retrieves the ACL for a specific file or directory.

GET /{{filesystem_name}}/{{path}}?action=getAccessControl

Query Parameters:

Name	Type	Description
`action`	String	Must be set to `getAccessControl`.
`directoryQueryParams`	String	Optional. Valid values include `recursive` for recursive retrieval.

Successful Response (200 OK):

Returns an AccessControlList object containing the ACL entries.


{
  "entries": [
    {
      "type": "user",
      "id": "owner-sid",
      "permissions": "rwx"
    },
    {
      "type": "group",
      "id": "owning-group-sid",
      "permissions": "rwx"
    },
    {
      "type": "other",
      "permissions": "r--"
    },
    {
      "type": "user",
      "id": "specific-user-sid",
      "permissions": "rw-"
    }
  ],
  "defaultEntries": [
    {
      "type": "user",
      "id": "owner-sid",
      "permissions": "rwx"
    }
  ]
}

Set Access Control List (ACL)

Sets the ACL for a specific file or directory. This operation replaces the existing ACL.

PATCH /{{filesystem_name}}/{{path}}?action=setAccessControl

Query Parameters:

Name	Type	Description
`action`	String	Must be set to `setAccessControl`.
`directoryQueryParams`	String	Optional. Valid values include `recursive` for recursive application.

Request Body:

A JSON object representing the new ACL:


{
  "entries": [
    {
      "type": "user",
      "id": "owner-sid",
      "permissions": "rwx"
    },
    {
      "type": "group",
      "id": "owning-group-sid",
      "permissions": "r--"
    },
    {
      "type": "other",
      "permissions": "---"
    }
  ],
  "defaultEntries": [
    {
      "type": "user",
      "id": "owner-sid",
      "permissions": "rwx"
    }
  ]
}

Successful Response (200 OK):

Indicates the ACL was successfully updated. No response body is returned.

Error Response:

Returns an error code and message for failures.

Set Access Control Entry (ACE)

Adds, modifies, or removes a single Access Control Entry (ACE) from the ACL of a file or directory. This is an efficient way to make granular changes.

PATCH /{{filesystem_name}}/{{path}}?action=updateAccessControl&acl=[base64_encoded_acl_entry]

Query Parameters:

Name	Type	Description
`action`	String	Must be set to `updateAccessControl`.
`acl`	String	A base64 encoded string representing the ACE to add, modify, or remove. Example ACE encoding: `user:specific-user-sid:rw-` (for adding/modifying) To remove an ACE, you can often set its permissions to empty or use a specific "remove" action if supported by the SDK. For direct REST, the exact behavior might depend on the presence and format of the entry.
`directoryQueryParams`	String	Optional. Valid values include `recursive` for recursive application.

Successful Response (200 OK):

Indicates the ACE was successfully updated. No response body is returned.