Assign Share-Level Permissions for Azure Files

Summary — Assign share-level permissions for Azure file shares

What this is about

• After enabling an identity source for a storage account, you must set share-level permissions to allow access to SMB Azure file shares.

• Two options:

  • Assign permissions to specific Microsoft Entra (Azure AD) users, groups, or service principals (recommended for most scenarios).

  • Assign a default share-level permission on the storage account that applies to all authenticated identities.

When to choose each option

• Assign to specific Entra identities (recommended)

  • More secure and granular when combined with Windows ACLs for directory/file-level control.

  • Requires the Entra identity to be a hybrid identity (exists in both on-prem AD DS and Microsoft Entra ID).

  • Use Azure Portal / PowerShell / CLI to assign one of the built-in Azure Files RBAC roles to the Entra identity.

  • Share-level permission changes may take up to ~30 minutes to propagate (note also a later statement that permissions can take up to three hours).

• Use a default share-level permission when:

  • You cannot sync on-prem AD DS to Microsoft Entra ID.

  • The on-prem AD DS is synced to a different Microsoft Entra ID than the one the file share uses (e.g., multitenant scenarios).

  • You prefer enforcing authentication only via Windows ACLs at directory/file level.

  • Default permissions apply to all authenticated identities for the storage account; default is None initially.

  • When default is set, you do not need to sync on-prem identities to Microsoft Entra ID.

Azure Files built-in RBAC roles (high level)

• Storage File Data SMB Share Reader: read access to files/directories.

• Storage File Data SMB Share Contributor: read, write, delete.

• Storage File Data SMB Share Elevated Contributor: read, write, delete, modify ACLs.

• Storage File Data Privileged Contributor: read/write/delete and override existing ACLs.

• Storage File Data Privileged Reader: read and override existing ACLs.

• Storage File Data SMB Admin: admin-equivalent SMB access.

Note: Computer accounts do not have Entra identities, so you cannot assign RBAC to them. They can rely on default share-level permission.

Important security guidance

• Avoid using wildcards (*) in custom role data actions. Wildcards grant all possible data actions (including future ones) to assigned identities and may produce unwanted permissions.

• For share-level permissions to work with specific Entra identities: sync both users and groups from on-prem AD to Microsoft Entra ID via Microsoft Entra Connect Sync, and add synced groups to RBAC roles.

• Share-level permission changes can take time to propagate — allow the stated propagation window before testing connections.

How to assign a role to a specific Entra identity (overview)

1

Use the Azure portal

• Go to the file share (or create an SMB file share).

• Select Access Control (IAM) → Add a role assignment.

• Choose the appropriate built-in role.

• Keep Assign access to = Microsoft Entra user, group, or service principal and select the hybrid Entra identity by name/email (must be hybrid, not cloud-only).

• Save.

2

Use PowerShell (example)

• Get the role definition and set scope to the target file share, then create the role assignment.

$FileShareContributorRole = Get-AzRoleDefinition "<role-name>"
$scope = "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/fileServices/default/fileshares/<share-name>"
New-AzRoleAssignment -SignInName <user-principal-name> -RoleDefinitionName $FileShareContributorRole.Name -Scope $scope

(Replace placeholder values.)

3

Use Azure CLI (example)

az role assignment create --role "<role-name>" --assignee <user-principal-name> --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/fileServices/default/fileshares/<share-name>"

(Replace placeholder values.)

How to configure a default share-level permission (overview)

1

Use the Azure portal

• Go to the storage account → Data storage > File shares.

• Ensure an AD source is enabled on the storage account (set up if not).

• Under Step 2: Set share-level permissions, enable permissions for all authenticated users and groups.

• Choose the default role from the dropdown and Save.

2

PowerShell example

• Ensure Az.Storage module ≥ 3.7.0.

$defaultPermission = "None|StorageFileDataSmbShareContributor|StorageFileDataSmbShareReader|StorageFileDataSmbShareElevatedContributor"
$account = Set-AzStorageAccount -ResourceGroupName "<resource-group-name-here>" -AccountName "<storage-account-name-here>" -DefaultSharePermission $defaultPermission
$account.AzureFilesIdentityBasedAuth

(Replace placeholder values.)

3

Azure CLI example

• Ensure Azure CLI ≥ 2.24.1.

storageAccountName="YourStorageAccountName"
resourceGroupName="YourResourceGroupName"
defaultPermission="None|StorageFileDataSmbShareContributor|StorageFileDataSmbShareReader|StorageFileDataSmbShareElevatedContributor"
az storage account update --name $storageAccountName --resource-group $resourceGroupName --default-share-permission $defaultPermission

(Replace placeholder values.)

Combining both configurations

• If both a default share-level permission and specific RBAC assignments exist, the user receives the higher-level of the two permissions. Higher permissions take precedence.

Group-based access for non-synced users (how it works)

• Only the group needs to be synced to Microsoft Entra ID, not individual users.

• On authentication, the on-prem AD DC issues a Kerberos ticket listing the user's group SIDs.

• Azure Files reads group SIDs from the ticket; if any group is synced and has an RBAC assignment, the user inherits that access.

• This enables non-synced users to access shares through their synced AD group memberships.

Tips and tools

• You can migrate on-prem SMB share-level permissions to Azure RBAC using the Move-OnPremSharePermissionsToAzureFileShare PowerShell cmdlet to help map groups/users and apply appropriate roles.

• Use Reader and Data Access role for tools like Azure Storage Explorer to read/access file shares.

Next steps and additional resources

• After assigning share-level permissions, configure directory and file-level permissions (Windows ACLs) for granular control: https://docs.azure.cn/en-us/storage/files/storage-files-identity-configure-file-level-permissions

• Be aware that share-level permissions can take time to take effect (documentation references up to 30 minutes and also up to three hours in other places — allow time for propagation).

(Last updated: 12/23/2025)