Use JavaScript SDK in Node.js to manage ACLs in Azure Data Lake Storage Gen2
This article shows you how to use Node.js to get, set, and update the access control lists of directories and files.
Package (Node Package Manager) | Samples | Give Feedback
Prerequisites
An Azure subscription. For more information, see Get Azure free trial.
A storage account that has hierarchical namespace (HNS) enabled. Follow these instructions to create one.
Azure CLI version
2.6.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..
Set up your project
Install Data Lake client library for JavaScript by opening a terminal window, and then typing the following command.
npm install @azure/storage-file-datalake
Import the storage-file-datalake
package by placing this statement at the top of your code file.
const {
AzureStorageDataLake,
DataLakeServiceClient,
StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");
Connect to the account
To use the snippets in this article, you'll need to create a DataLakeServiceClient instance that represents the storage account.
Connect by using Microsoft Entra ID
Note
If you're using Microsoft Entra ID to authorize access, then make sure that your security principal has been assigned the Storage Blob Data Owner role. To learn more about how ACL permissions are applied and the effects of changing them, see Access control model in Azure Data Lake Storage Gen2.
You can use the Azure identity client library for JS to authenticate your application with Microsoft Entra ID.
First, you'll have to assign one of the following Azure role-based access control (Azure RBAC) roles to your security principal:
Role | ACL setting capability |
---|---|
Storage Blob Data Owner | All directories and files in the account. |
Storage Blob Data Contributor | Only directories and files owned by the security principal. |
Next, create a DataLakeServiceClient instance and pass in a new instance of the DefaultAzureCredential class.
function GetDataLakeServiceClientAD(accountName) {
const dataLakeServiceClient = new DataLakeServiceClient(
`https://${accountName}.dfs.core.windows.net`,
new DefaultAzureCredential()
);
return dataLakeServiceClient;
}
To learn more about using DefaultAzureCredential to authorize access to data, see Overview: Authenticate JavaScript apps to Azure using the Azure SDK.
Connect by using an account key
You can authorize access to data using your account access keys (Shared Key). This example creates a DataLakeServiceClient instance that is authorized with the account key.
function GetDataLakeServiceClient(accountName, accountKey) {
const sharedKeyCredential =
new StorageSharedKeyCredential(accountName, accountKey);
const dataLakeServiceClient = new DataLakeServiceClient(
`https://${accountName}.dfs.core.windows.net`, sharedKeyCredential);
return dataLakeServiceClient;
}
Caution
Authorization with Shared Key is not recommended as it may be less secure. For optimal security, disable authorization via Shared Key for your storage account, as described in Prevent Shared Key authorization for an Azure Storage account.
Use of access keys and connection strings should be limited to initial proof of concept apps or development prototypes that don't access production or sensitive data. Otherwise, the token-based authentication classes available in the Azure SDK should always be preferred when authenticating to Azure resources.
Microsoft recommends that clients use either Microsoft Entra ID or a shared access signature (SAS) to authorize access to data in Azure Storage. For more information, see Authorize operations for data access.
Get and set a directory ACL
This example gets and then sets the ACL of a directory named my-directory
. This example gives the owning user read, write, and execute permissions, gives the owning group only read and execute permissions, and gives all others read access.
Note
If your application authorizes access by using Microsoft Entra ID, then make sure that the security principal that your application uses to authorize access has been assigned the Storage Blob Data Owner role. To learn more about how ACL permissions are applied and the effects of changing them, see Access control in Azure Data Lake Storage Gen2.
async function ManageDirectoryACLs(fileSystemClient) {
const directoryClient = fileSystemClient.getDirectoryClient("my-directory");
const permissions = await directoryClient.getAccessControl();
console.log(permissions.acl);
const acl = [
{
accessControlType: "user",
entityId: "",
defaultScope: false,
permissions: {
read: true,
write: true,
execute: true
}
},
{
accessControlType: "group",
entityId: "",
defaultScope: false,
permissions: {
read: true,
write: false,
execute: true
}
},
{
accessControlType: "other",
entityId: "",
defaultScope: false,
permissions: {
read: true,
write: true,
execute: false
}
}
];
await directoryClient.setAccessControl(acl);
}
You can also get and set the ACL of the root directory of a container. To get the root directory, pass an empty string (/
) into the DataLakeFileSystemClient.getDirectoryClient method.
Get and set a file ACL
This example gets and then sets the ACL of a file named upload-file.txt
. This example gives the owning user read, write, and execute permissions, gives the owning group only read and execute permissions, and gives all others read access.
Note
If your application authorizes access by using Microsoft Entra ID, then make sure that the security principal that your application uses to authorize access has been assigned the Storage Blob Data Owner role. To learn more about how ACL permissions are applied and the effects of changing them, see Access control in Azure Data Lake Storage Gen2.
async function ManageFileACLs(fileSystemClient) {
const fileClient = fileSystemClient.getFileClient("my-directory/uploaded-file.txt");
const permissions = await fileClient.getAccessControl();
console.log(permissions.acl);
const acl = [
{
accessControlType: "user",
entityId: "",
defaultScope: false,
permissions: {
read: true,
write: true,
execute: true
}
},
{
accessControlType: "group",
entityId: "",
defaultScope: false,
permissions: {
read: true,
write: false,
execute: true
}
},
{
accessControlType: "other",
entityId: "",
defaultScope: false,
permissions: {
read: true,
write: true,
execute: false
}
}
];
await fileClient.setAccessControl(acl);
}
See also
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for