Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Applies to: ✔️ SMB file shares
After you enable an identity source for your storage account, you must configure share-level permissions to access your file share. You can assign share-level permissions in two ways: to specific Microsoft Entra users or groups, or to all authenticated identities as a default share-level permission.
Choose how to assign share-level permissions
You configure share-level permissions on Azure file shares for Microsoft Entra users, groups, or service principals. Directory-level and file-level permissions are enforced through Windows access control lists (ACLs). Assign share-level permissions to the Microsoft Entra identity that represents the user, group, or service principal needing access.
Most users assign share-level permissions to specific Microsoft Entra users or groups and use Windows ACLs for granular access control at the directory and file levels. This configuration is the most secure.
Use a default share-level permission to grant role-based access to all authenticated identities in these scenarios:
You're using Microsoft Entra Kerberos to authenticate cloud-only identities (preview).
You can't sync your on-premises Active Directory Domain Services (AD DS) deployment to Microsoft Entra ID. Assigning a default share-level permission works around the sync requirement because you don't need to specify the permission to identities in Microsoft Entra ID. Then you can use Windows ACLs for granular permission enforcement on your files and directories.
Identities that are tied to an Active Directory but aren't syncing to Microsoft Entra ID can also use the default share-level permission. This condition can include standalone Managed Service Accounts (sMSAs), group Managed Service Accounts (gMSAs), and computer accounts.
The on-premises AD DS deployment that you're using is synced to a Microsoft Entra ID deployment that's different from the one where the file share is deployed.
This condition is typical when you're managing multitenant environments. By using a default share-level permission, you bypass the requirement for a Microsoft Entra ID hybrid identity. You can still use Windows ACLs on your files and directories for granular permission enforcement.
You prefer to enforce authentication only by using Windows ACLs at the file and directory levels.
Azure RBAC roles for Azure Files
Several built-in Azure role-based access control (RBAC) roles are intended for use with Azure Files. Some of these roles grant share-level permissions to users and groups. If you're using Azure Storage Explorer, you also need the Reader and Data Access role to read and access the Azure file share.
Note
Because computer accounts don't have an identity in Microsoft Entra ID, you can't configure Azure RBAC for them. However, computer accounts can access a file share by using a default share-level permission.
| Built-in Azure RBAC role | Description |
|---|---|
| Storage File Data SMB Share Reader | Grants read access to files and directories in Azure Files. This role is similar to a file share ACL of read on Windows file servers. |
| Storage File Data SMB Share Contributor | Grants read, write, and delete access on files and directories in Azure Files. |
| Storage File Data SMB Share Elevated Contributor | Grants read, write, delete, and modify-ACLs access on files and directories in Azure Files. This role is similar to a file share ACL of change on Windows file servers. |
| Storage File Data Privileged Contributor | Grants read, write, delete, and modify-ACLs access in Azure Files by overriding existing ACLs. |
| Storage File Data Privileged Reader | Grants read access in Azure Files by overriding existing ACLs. |
| Storage File Data SMB Admin | Grants admin access equivalent to a storage account key for users over SMB. |
| Storage File Data SMB Take Ownership | Allows users to assume ownership of a file/directory. |
Share-level permissions for specific Microsoft Entra users or groups
If you intend to use a specific Microsoft Entra user or group to access Azure file share resources, that identity must be a hybrid identity that exists in both on-premises AD DS and Microsoft Entra ID. Cloud-only identities must use a default share-level permission.
For example, if you have a user in Active Directory named user1@onprem.contoso.com and you sync to Microsoft Entra ID as user1@contoso.com by using Microsoft Entra Connect Sync or Microsoft Entra Connect Cloud Sync, the user must have the share-level permissions assigned to user1@contoso.com to access the file share. The same concept applies to groups and service principals.
Important
Assign permissions by explicitly declaring actions and data actions instead of using a wildcard (*) character.
If a custom role definition for a data action contains a wildcard character, all identities assigned to that role are granted access for all possible data actions. This access includes any new data action added to the platform. The additional access and permissions granted through new actions or data actions might be unwanted behavior for customers who use wildcards.
For share-level permissions to work, you must take the following actions:
- If your identity source is AD DS or Microsoft Entra Kerberos, sync the users and the groups from your local Active Directory deployment to Microsoft Entra ID by using either Microsoft Entra Connect Sync or Microsoft Entra Cloud Sync. Microsoft Entra Cloud Sync is a lightweight agent that you can install from the Microsoft Entra admin center.
- Add Active Directory-synced groups to the RBAC role so they can access your storage account.
Tip
Optional: To migrate SMB server root folder permissions to RBAC permissions, use the Move-OnPremSharePermissionsToAzureFileShare PowerShell cmdlet from the AzFilesHybrid module. This cmdlet gets the directory permissions of the root directory of an on-premises file share and updates the RBAC definition on the Azure file share to grant access to users/groups listed in the root directory ACL.
The cmdlet only converts the root directory into RBAC assignments. Users who have access to sub-files and directories without access to the root aren't added to RBAC. Also, the cmdlet grants the RBAC role that's equivalent to what's on the root. Users who have read-only access to the root but write access to some sub-files or directories will only get read access in RBAC. You need to manually adjust RBAC in those cases.
To grant share-level permissions, use the Azure portal, Azure PowerShell, or the Azure CLI to assign one of the built-in roles to the Microsoft Entra ID identity of a user.
Share-level permission changes usually take effect within 30 minutes, but in some cases they can take longer. Wait for permissions to propagate before you connect to the file share by using your credentials.
To assign an Azure role to a Microsoft Entra identity by using the Azure portal, follow these steps:
In the Azure portal, go to your file share, or create an SMB file share.
Select Access Control (IAM).
Select Add a role assignment.
In the Add role assignment pane, select the appropriate built-in role from the Role list.
Keep Assign access to at the default setting: Microsoft Entra user, group, or service principal. Select the target Microsoft Entra identity by name or email address.
The selected Microsoft Entra identity must be a hybrid identity and can't be a cloud-only identity. This requirement means that the same identity is also represented in AD DS.
Select Save to complete the role assignment operation.
Share-level permissions for all authenticated identities
You can add a default share-level permission on your storage account, instead of configuring share-level permissions for Microsoft Entra users or groups. A default share-level permission assigned to your storage account applies to all file shares contained in the storage account.
Important
If you set a default share-level permission on the storage account, you don't need to sync your on-premises identities to Microsoft Entra ID.
When you set a default share-level permission, all authenticated users and groups have the same permission. Authenticated users or groups are identified as the identity that can be authenticated against the AD DS deployment that the storage account is associated with.
The default share-level permission is set to None at initialization. This setting means no access is allowed to files or directories in the Azure file share.
To configure default share-level permissions on your storage account by using the Azure portal, follow these steps:
In the Azure portal, go to the storage account that contains your file shares and select Data storage > File shares.
You must enable an identity source on your storage account before assigning default share-level permissions. If you already enabled an identity source, select Configured next to Identity-based access, and proceed to the next step. Otherwise, select Not configured, select Set up under the desired identity source, and enable the identity source.
After you enable an identity source, Step 2: Set share-level permissions is available for configuration. Select Enable permissions for all authenticated users and groups.
In the dropdown list, select the appropriate role to enable as the default share permission.
Select Save.
What happens if you use both configurations
You can assign permissions to all authenticated Microsoft Entra users and to specific Microsoft Entra users or groups. When you use this configuration, a specific user or group gets the higher-level permission between the default share-level permission and the RBAC assignment.
For example, suppose you grant a user the Storage File Data SMB Reader role on the target file share. You also grant the default share-level permission Storage File Data SMB Share Elevated Contributor to all authenticated users. With this configuration, that particular user has Storage File Data SMB Share Elevated Contributor access to the file share. Higher-level permissions always take precedence.
Understanding group-based access for non-synced users
This section applies only to storage accounts that use AD DS authentication.
Users who aren't synced to Microsoft Entra ID can still access Azure file shares through group membership. If a user belongs to an on-premises AD DS group that's synced to Microsoft Entra ID and has an Azure RBAC role assignment, the user gets the group's permissions, even though they don't appear as a group member in the Microsoft Entra admin center.
Here's how it works:
- Only the group needs to be synced to Microsoft Entra ID, not individual users.
- When a user authenticates, the on-premises domain controller sends a Kerberos ticket that includes all the user's group memberships.
- Azure Files reads the group security identifiers (SIDs) from the Kerberos ticket.
- If any of those groups are synced to Microsoft Entra ID, Azure Files applies the matching RBAC role assignments.
Because of this process, authorization is based on the groups listed in the Kerberos ticket, not on what appears in the Microsoft Entra admin center. Non-synced users can access file shares through their synced AD DS group memberships without needing individual syncing to Microsoft Entra ID.
Next step
After you assign share-level permissions, you can take ownership of the file share and configure directory-level and file-level permissions. Wait for share-level permissions to propagate first.