Set Access Control

The Set Access Control operation sets the Access Control List (ACL) for a file or directory. The ACL specifies the permissions that are granted to different identities for accessing a file or directory.

This operation can be used to:

  • Add or modify Access Control entries (ACEs) for users and groups.
  • Remove ACEs.
  • Grant or deny specific permissions (read, write, execute).

Request URI Syntax

The request URI for the Set Access Control operation is:


PUT /{filesystem}/{directory}/{file}?action=setAccessControl&directory={directory}&recursive={recursive}&force={force}&mode={mode}&acl={acl} HTTP/1.1
Host: {storageaccountname}.dfs.core.windows.net
x-ms-version: 2019-02-02
Authorization: SharedKey {storageaccountname}:{signature}
x-ms-date: {date}
Content-Length: {length}
Content-MD5: {md5}
If-Match: {ETag}

Or for a directory:


PUT /{filesystem}/{directory}?action=setAccessControl&directory={directory}&recursive={recursive}&force={force}&mode={mode}&acl={acl} HTTP/1.1
Host: {storageaccountname}.dfs.core.windows.net
x-ms-version: 2019-02-02
Authorization: SharedKey {storageaccountname}:{signature}
x-ms-date: {date}
Content-Length: {length}
Content-MD5: {md5}
If-Match: {ETag}

Path Parameters

Name Description Required
filesystem The name of the file system. Yes
directory The path of the directory. No (if operating on the root of the filesystem)
file The path of the file. No (if operating on a directory)

Query Parameters

Name Description Required
action Specifies the operation to perform. Must be setAccessControl. Yes
directory When setting ACLs recursively for a directory, this parameter specifies the path of the directory for which ACLs are being set. No
recursive Boolean value that specifies whether the ACL modification should be recursive. Set to true to apply to subdirectories and files. No
force Boolean value that specifies whether to overwrite existing ACLs when recursive is true. If false and an ACL exists, the operation fails. No
mode The POSIX mode of the file or directory. This parameter is only applicable when setting the ACL for a new file or directory. No
acl The Access Control List string. This is a comma-separated list of Access Control Entries (ACEs). Each ACE has the format [permissions][scope:][type:]identifier. Yes

Request Headers

This operation only supports the following headers:

Name Description Required
Host The storage account host name. Yes
x-ms-version Specifies the version of the Data Lake Storage Gen2 REST API. Yes
Authorization Specifies the authorization credentials for the request. Yes
x-ms-date Specifies the UTC date and time when the request was initiated. Yes
Content-Length The length of the request body in bytes. No (if no request body)
Content-MD5 The MD5 hash of the request body. No
If-Match Specifies an ETag value to return the resource only if its ETag matches the value specified in the If-Match header. No

Request Body

The request body is not used for this operation when setting the ACL via the acl query parameter.

Responses

This operation returns a 200 OK response if successful.

Success Response

A successful response returns an empty body.

Error Responses

The following error codes may be returned:

Code Description
400 Bad Request The request was malformed or invalid. This could be due to an invalid ACL string, incorrect query parameters, or missing required headers.
403 Forbidden The caller does not have the necessary permissions to perform this operation.
404 Not Found The specified file or directory does not exist.
409 Conflict The operation could not be completed due to a conflict. For example, attempting to set ACLs recursively on a file.
412 Precondition Failed A precondition specified in the request headers (e.g., If-Match) failed.

Example

The following example sets the ACL for a file named my-file.txt in the my-filesystem file system. It grants read and write permissions to the owner, read permissions to the owning group, and read permissions to a specific user.


PUT /my-filesystem/my-directory/my-file.txt?action=setAccessControl&acl=user::rw-,group::r--,other::---,user:alice:r-x HTTP/1.1
Host: mystorageaccount.dfs.core.windows.net
x-ms-version: 2019-02-02
Authorization: SharedKey mystorageaccount:your_signature_here
x-ms-date: Mon, 27 Jul 2023 22:08:01 GMT
Content-Length: 0

Explanation of the ACL string:

  • user::rw-: Grants read and write permissions to the owning user.
  • group::r--: Grants read permission to the owning group.
  • other::---: Denies all permissions to others.
  • user:alice:r-x: Grants read and execute permissions to the user 'alice'.

See Also

Get Access Control

Azure Data Lake Storage Gen2 REST API