Edit

Use Azure CLI to manage ACLs in Azure Data Lake Storage Gen2

  • Article

This article shows you how to use the Azure CLI to get, set, and update the access control lists of directories and files.

ACL inheritance is already available for new child items that are created under a parent directory. But you can also add, update, and remove ACLs recursively on the existing child items of a parent directory without having to make these changes individually for each child item.

Reference | Samples | Give feedback

Prerequisites

  • An Azure subscription. For more information, see Get Azure free trial.

  • A storage account that has hierarchical namespace enabled. Follow these instructions to create one.

  • Azure CLI version 2.14.0 or higher.

  • One of the following security permissions:

    • A provisioned Microsoft Entra ID security principal that has been assigned the Storage Blob Data Owner role, scoped to the target container, storage account, parent resource group, or subscription..

    • Owning user of the target container or directory to which you plan to apply ACL settings. To set ACLs recursively, this includes all child items in the target container or directory.

    • Storage account key.

Ensure that you have the correct version of Azure CLI installed

  1. Open the Azure Cloud Shell, or if you've installed the Azure CLI locally, open a command console application such as Windows PowerShell.

  2. Verify that the version of Azure CLI that have installed is 2.14.0 or higher by using the following command.

     az --version

    If your version of Azure CLI is lower than 2.14.0, then install a later version. For more information, see Install the Azure CLI.

Connect to the account

  1. If you're using Azure CLI locally, run the login command.

    az login

    If the CLI can open your default browser, it will do so and load an Azure sign-in page.

    Otherwise, open a browser page at https://aka.ms/devicelogin and enter the authorization code displayed in your terminal. Then, sign in with your account credentials in the browser.

    To learn more about different authentication methods, see Authorize access to blob or queue data with Azure CLI.

  2. If your identity is associated with more than one subscription, then set your active subscription to subscription of the storage account that will host your static website.

    az account set --subscription <subscription-id>

    Replace the <subscription-id> placeholder value with the ID of your subscription.

Note

The example presented in this article show Microsoft Entra authorization. To learn more about authorization methods, see Authorize access to blob or queue data with Azure CLI.

Get ACLs

Get the ACL of a directory by using the az storage fs access show command.

This example gets the ACL of a directory, and then prints the ACL to the console.

az storage fs access show -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login

Get the access permissions of a file by using the az storage fs access show command.

This example gets the ACL of a file and then prints the ACL to the console.

az storage fs access show -p my-directory/upload.txt -f my-file-system --account-name mystorageaccount --auth-mode login

The following image shows the output after getting the ACL of a directory.

Get ACL output

In this example, the owning user has read, write, and execute permissions. The owning group has only read and execute permissions. For more information about access control lists, see Access control in Azure Data Lake Storage Gen2.

Set ACLs

When you set an ACL, you replace the entire ACL including all of it's entries. If you want to change the permission level of a security principal or add a new security principal to the ACL without affecting other existing entries, you should update the ACL instead. To update an ACL instead of replace it, see the Update ACLs section of this article.

If you choose to set the ACL, you must add an entry for the owning user, an entry for the owning group, and an entry for all other users. To learn more about the owning user, the owning group, and all other users, see Users and identities.

This section shows you how to:

  • Set an ACL
  • Set ACLs recursively

Set an ACL

Use the az storage fs access set command to set the ACL of a directory.

This example sets the ACL on a directory for the owning user, owning group, or other users, and then prints the ACL to the console.

az storage fs access set --acl "user::rw-,group::rw-,other::-wx" -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login

This example sets the default ACL on a directory for the owning user, owning group, or other users, and then prints the ACL to the console.

az storage fs access set --acl "default:user::rw-,group::rw-,other::-wx" -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login

Use the az storage fs access set command to set the acl of a file.

This example sets the ACL on a file for the owning user, owning group, or other users, and then prints the ACL to the console.

az storage fs access set --acl "user::rw-,group::rw-,other::-wx" -p my-directory/upload.txt -f my-file-system --account-name mystorageaccount --auth-mode login

Note

To a set the ACL of a specific group or user, use their respective object IDs. For example, to set the ACL of a group, use group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. To set the ACL of a user, use user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

The following image shows the output after setting the ACL of a file.

Get ACL output 2

In this example, the owning user and owning group have only read and write permissions. All other users have write and execute permissions. For more information about access control lists, see Access control in Azure Data Lake Storage Gen2.

Set ACLs recursively

Set ACLs recursively by using the az storage fs access set-recursive command.

This example sets the ACL of a directory named my-parent-directory. These entries give the owning user read, write, and execute permissions, gives the owning group only read and execute permissions, and gives all others no access. The last ACL entry in this example gives a specific user with the object ID "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" read and execute permissions.

az storage fs access set-recursive --acl "user::rwx,group::r-x,other::---,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

Note

If you want to set a default ACL entry, add the prefix default: to each entry. For example, default:user::rwx or default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x.

Update ACLs

When you update an ACL, you modify the ACL instead of replacing the ACL. For example, you can add a new security principal to the ACL without affecting other security principals listed in the ACL. To replace the ACL instead of update it, see the Set ACLs section of this article.

To update an ACL, create a new ACL object with the ACL entry that you want to update, and then use that object in update ACL operation. Do not get the existing ACL, just provide ACL entries to be updated.

This section shows you how to:

  • Update an ACL
  • Update ACLs recursively

Update an ACL

Update the ACL of a file by using the az storage fs access update-recursive command.

This example updates an ACL entry with write permission.

az storage fs access update-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx" -p my-parent-directory/myfile.txt -f my-container --account-name mystorageaccount --auth-mode login

To a update the ACL of a specific group or user, use their respective object IDs. For example, group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx or user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Note

Updating the ACL of a single directory without updating the ACL of child items is not supported by the Azure CLI. To update the ACL of a directory without modifying the ACLs of all child items in that directory, use any of the other supported tools and SDKs. See How to set ACLs.

Update ACLs recursively

Update ACLs recursively by using the az storage fs access update-recursive command.

This example updates an ACL entry with write permission.

az storage fs access update-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

Note

If you want to update a default ACL entry, add the prefix default: to each entry. For example, default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x.

Remove ACL entries recursively

You can remove one or more ACL entries recursively. To remove an ACL entry, create a new ACL object for ACL entry to be removed, and then use that object in remove ACL operation. Do not get the existing ACL, just provide the ACL entries to be removed.

Remove ACL entries by using the az storage fs access remove-recursive command.

This example removes an ACL entry from the root directory of the container.

az storage fs access remove-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

Note

If you want to remove a default ACL entry, add the prefix default: to each entry. For example, default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Recover from failures

You might encounter runtime or permission errors when modifying ACLs recursively. For runtime errors, restart the process from the beginning. Permission errors can occur if the security principal doesn't have sufficient permission to modify the ACL of a directory or file that is in the directory hierarchy being modified. Address the permission issue, and then choose to either resume the process from the point of failure by using a continuation token, or restart the process from beginning. You don't have to use the continuation token if you prefer to restart from the beginning. You can reapply ACL entries without any negative impact.

In the event of a failure, you can return a continuation token by setting the --continue-on-failure parameter to false. After you address the errors, you can resume the process from the point of failure by running the command again, and then setting the --continuation parameter to the continuation token.

az storage fs access set-recursive --acl "user::rw-,group::r-x,other::---" --continue-on-failure false --continuation xxxxxxx -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

If you want the process to complete uninterrupted by permission errors, you can specify that.

To ensure that the process completes uninterrupted, set the --continue-on-failure parameter to true.

az storage fs access set-recursive --acl "user::rw-,group::r-x,other::---" --continue-on-failure true --continuation xxxxxxx -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

Best practices

This section provides you some best practice guidelines for setting ACLs recursively.

Handling runtime errors

A runtime error can occur for many reasons (For example: an outage or a client connectivity issue). If you encounter a runtime error, restart the recursive ACL process. ACLs can be reapplied to items without causing a negative impact.

Handling permission errors (403)

If you encounter an access control exception while running a recursive ACL process, your AD security principal might not have sufficient permission to apply an ACL to one or more of the child items in the directory hierarchy. When a permission error occurs, the process stops and a continuation token is provided. Fix the permission issue, and then use the continuation token to process the remaining dataset. The directories and files that have already been successfully processed won't have to be processed again. You can also choose to restart the recursive ACL process. ACLs can be reapplied to items without causing a negative impact.

Credentials

We recommend that you provision a Microsoft Entra security principal that has been assigned the Storage Blob Data Owner role in the scope of the target storage account or container.

Performance

To reduce latency, we recommend that you run the recursive ACL process in an Azure Virtual Machine (VM) that is located in the same region as your storage account.

ACL limits

The maximum number of ACLs that you can apply to a directory or file is 32 access ACLs and 32 default ACLs. For more information, see Access control in Azure Data Lake Storage Gen2.

See also