Learning Record learning from practice

· microsoft / azure

Choosing the Right ACL API in Azure

#azure #acl #microsoft-graph #data-lake-storage

Choosing the Right ACL API in Azure

“Azure file permissions” can refer to two different storage surfaces. OneDrive and SharePoint files use Microsoft Graph sharing permissions. Azure Data Lake Storage Gen2 uses POSIX-like ACLs on files and directories.

The distinction matters: the APIs, permission models, and inheritance rules are different.

OneDrive and SharePoint: Microsoft Graph

For a OneDrive or SharePoint file, use the permissions relationship on the driveItem resource. To list the effective sharing permissions, call:

GET /drives/{drive-id}/items/{item-id}/permissions
GET /me/drive/items/{item-id}/permissions
GET /sites/{site-id}/drive/items/{item-id}/permissions

The caller’s view is security-sensitive. An item’s owner receives all sharing permissions, while a non-owner may receive only the permissions that apply to that caller. The permissions relationship cannot be expanded as part of a normal driveItem request; request it directly.

Reading the response

A Graph permission object commonly contains:

  • roles: the access level, such as read or write.
  • grantedToV2: the user, group, or site user that received the permission.
  • link: details for a sharing link, including its type.
  • inheritedFrom: the ancestor from which the permission was inherited.

The response represents effective sharing permissions. A permission may be assigned directly to the item or inherited from a parent folder, so inheritedFrom is useful when explaining why access exists.

Choosing Graph permissions

Request the least-privileged permission that matches the application type and operation:

Application type Read Read and write
Delegated Files.Read Files.ReadWrite
Application Files.Read.All Files.ReadWrite.All

These scopes describe access to files; they do not replace the item’s own sharing rules. Use broader scopes only when the application genuinely needs them.

ADLS Gen2: POSIX-like ACLs

For files in Azure Data Lake Storage Gen2, use the Azure Storage APIs, Azure CLI, Azure PowerShell, or an Azure Storage SDK. ACL support requires a storage account with hierarchical namespace enabled. Microsoft Graph is not the API for these storage paths.

To display the ACL for a file or directory with Azure CLI:

az storage fs access show \
  --path <path> \
  --file-system <file-system> \
  --account-name <storage-account> \
  --auth-mode login

The ACL uses the familiar rwx notation:

user::rwx
user:<object-id>:r-x
group::r-x
mask::r-x
other::---

Here, r means read, w means write, and x means execute. Execute permission has a different practical meaning for files and directories. It is not meaningful for a file, but it is required to traverse a directory. Reading a directory also requires read and execute permissions on that directory.

Access ACLs and default ACLs

ADLS Gen2 has two related ACL types:

  • Access ACLs control access to an existing file or directory.
  • Default ACLs are templates on directories. They initialize the access ACL of child items created beneath that directory.

Default ACLs affect new children only. Changing a parent’s default ACL does not update items that already exist. Existing trees must be updated explicitly, often with a recursive operation.

When ACLs are the only authorization mechanism, a principal also needs execute permission on the root directory and every directory in the path to the target file. An ACL entry on the file alone is not enough.

Identity and object IDs

ACL entries can refer to Microsoft Entra users, groups, service principals, and managed identities. For a service principal, use the object ID of the service principal in the tenant, not the object ID of the application registration.

In practice, assigning permissions to Microsoft Entra security groups is easier to maintain than assigning them to individual users. Membership changes can then be handled in the identity system without rewriting a large directory tree.

A practical decision rule

Use this simple rule when designing an integration:

OneDrive or SharePoint file
  -> Microsoft Graph driveItem permissions

ADLS Gen2 file or directory
  -> Azure Storage ACL API, CLI, PowerShell, or SDK

Before troubleshooting a 403 response, identify the storage surface first. Then verify the account configuration, the caller’s identity, the required API scope or Azure role, and the permissions along the complete directory hierarchy.

References