Files share level permissions integrity check

Author: khdownie

articles/storage/files/storage-files-identity-assign-share-level-permissions.md

@@ -1,14 +1,14 @@
 ---
 title: Assign Share-Level Permissions for Azure Files
-description: Learn how to control access to Azure Files by assigning share-level permissions to control user access to Azure file shares with identity-based authentication.
+description: Learn how to control access to Azure Files by assigning share-level permissions to control user access to SMB Azure file shares with identity-based authentication.
 author: khdownie
 ms.service: azure-file-storage
 ms.topic: how-to
-ms.date: 02/26/2026
+ms.date: 03/04/2026
 ms.author: kendownie 
 ms.custom: devx-track-azurepowershell, subject-rbac-steps, devx-track-azurecli
 ms.devlang: azurecli
-# Customer intent: As a cloud administrator, I want to assign share-level permissions for Azure File shares, so that I can control user access to shared files and ensure secure and effective file management within my organization.
+# Customer intent: As a cloud administrator, I want to assign share-level permissions for SMB Azure file shares, so that I can control user access to shared files and ensure secure and effective file management within my organization.
 ---
 
 # Assign share-level permissions for Azure file shares
@@ -23,13 +23,13 @@ You configure share-level permissions on Azure file shares for Microsoft Entra u
 
 Most users assign share-level permissions to specific Entra users or groups and use Windows ACLs for granular access control at the directory and file level. This configuration is the most secure.
 
-Use a [default share-level permission](#share-level-permissions-for-all-authenticated-identities) to grant reader, contributor, elevated contributor, privileged contributor, or privileged reader access to all authenticated identities in these scenarios:
+Use a [default share-level permission](#share-level-permissions-for-all-authenticated-identities) 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're unable to sync your on-premises Active Directory Domain Services (AD DS) 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 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 leverage the default share-level permission. This condition can include standalone Managed Service Accounts (sMSA), group Managed Service Accounts (gMSA), and computer accounts.
-- The on-premises AD DS you're using is synched to a different Entra ID than the Entra ID the file share is deployed in.
-    - This condition is typical when you're managing multitenant environments. By using a default share-level permission, you bypass the requirement for an Entra ID [hybrid identity](../../active-directory/hybrid/whatis-hybrid-identity.md). You can still use Windows ACLs on your files and directories for granular permission enforcement.
+    - Identities that are tied to an Active Directory but aren't syncing to Microsoft Entra ID can also leverage the default share-level permission. This condition can include standalone Managed Service Accounts (sMSA), group Managed Service Accounts (gMSA), and computer accounts.
+- The on-premises AD DS you're using is synced to a different Entra ID than the Entra ID the file share is deployed in.
+    - This condition is typical when you're managing multitenant environments. By using a default share-level permission, you bypass the requirement for an Entra ID [hybrid identity](/entra/identity/hybrid/whatis-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 level.
 
 ## Azure RBAC roles for Azure Files
@@ -41,36 +41,36 @@ There are several built-in Azure role-based access control (RBAC) roles intended
 
 |**Built-in Azure RBAC role**  |**Description**  |
 |---------|---------|
-|[Storage File Data SMB Share Reader](../../role-based-access-control/built-in-roles.md#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](../../role-based-access-control/built-in-roles.md#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](../../role-based-access-control/built-in-roles.md#storage-file-data-smb-share-elevated-contributor)     |Grants read, write, delete, and modify ACLs 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](../../role-based-access-control/built-in-roles/storage.md#storage-file-data-privileged-contributor) |Grants read, write, delete, and modify ACLs in Azure Files by overriding existing ACLs. |
-|[Storage File Data Privileged Reader](../../role-based-access-control/built-in-roles/storage.md#storage-file-data-privileged-reader) |Grants read access in Azure Files by overriding existing ACLs. |
-|[Storage File Data SMB Admin](../../role-based-access-control/built-in-roles/storage.md#storage-file-data-smb-admin) |Grants admin access equivalent to storage account key for end users over SMB. |
+|[Storage File Data SMB Share Reader](../../role-based-access-control/built-in-roles.md#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](../../role-based-access-control/built-in-roles.md#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](../../role-based-access-control/built-in-roles.md#storage-file-data-smb-share-elevated-contributor) | Grants read, write, delete, and modify ACLs 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](../../role-based-access-control/built-in-roles/storage.md#storage-file-data-privileged-contributor) | Grants read, write, delete, and modify ACLs in Azure Files by overriding existing ACLs. |
+|[Storage File Data Privileged Reader](../../role-based-access-control/built-in-roles/storage.md#storage-file-data-privileged-reader) | Grants read access in Azure Files by overriding existing ACLs. |
+|[Storage File Data SMB Admin](../../role-based-access-control/built-in-roles/storage.md#storage-file-data-smb-admin) | Grants admin access equivalent to storage account key for end users over SMB. |
 
 <a name='share-level-permissions-for-specific-azure-ad-users-or-groups'></a>
 
 ## Share-level permissions for specific 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](../../active-directory/hybrid/whatis-hybrid-identity.md) that exists in both on-premises AD DS and Microsoft Entra ID. Cloud-only identities must use a default share-level permission.
+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](/entra/identity/hybrid/whatis-hybrid-identity) that exists in both on-premises AD DS and Microsoft Entra ID. Cloud-only identities must use a [default share-level permission](#share-level-permissions-for-all-authenticated-identities).
 
-For example, say you have a user in your AD that's [email protected] and you sync to Entra ID as [email protected] by using Microsoft Entra Connect Sync or Microsoft Entra Connect cloud sync. To access Azure Files, this user must have the share-level permissions assigned to [email protected]. The same concept applies to groups and service principals.
+For example, say you have a user in your AD that's [email protected] and you sync to Entra ID as [email protected] by using Microsoft Entra Connect Sync or Microsoft Entra Connect Cloud Sync. To access Azure Files, this user must have the share-level permissions assigned to [email protected]. 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 using wildcard.
 
 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 to Entra ID by using either the on-premises [Microsoft Entra Connect Sync](../../active-directory/hybrid/whatis-azure-ad-connect.md) application or [Microsoft Entra Connect cloud sync](../../active-directory/cloud-sync/what-is-cloud-sync.md), a lightweight agent that you can install from the Entra Admin Center.
+- If your identity source is AD DS or Microsoft Entra Kerberos, sync the users **and** the groups from your local Active Directory to Entra ID by using either [Microsoft Entra Connect Sync](/entra/identity/hybrid/connect/how-to-connect-sync-whatis) or [Microsoft Entra Cloud Sync](/entra/identity/hybrid/cloud-sync/what-is-cloud-sync), a lightweight agent that you can install from the Entra Admin Center.
 - Add AD synced groups to RBAC role so they can access your storage account.
 
 > [!TIP]
-> Optional: To migrate SMB server share-level permissions to RBAC permissions, use the `Move-OnPremSharePermissionsToAzureFileShare` PowerShell cmdlet to migrate directory and file-level permissions from on-premises to Azure. This cmdlet evaluates the groups of a particular on-premises file share, then writes the appropriate users and groups to the Azure file share by using the three RBAC roles. You provide the information for the on-premises share and the Azure file share when invoking the cmdlet.
+> Optional: To migrate SMB server share-level permissions to RBAC permissions, use the `Move-OnPremSharePermissionsToAzureFileShare` PowerShell cmdlet to migrate directory and file-level permissions from on-premises to Azure. This cmdlet evaluates the groups of a particular on-premises file share, then writes the appropriate users and groups to the Azure file share by using the built-in RBAC roles. You provide the information for the on-premises share and the Azure file share when invoking the cmdlet.
 
-To grant share-level permissions, use the Azure portal, Azure PowerShell, or Azure CLI to assign the built-in roles to the Entra ID identity of a user.
+To grant share-level permissions, use the Azure portal, Azure PowerShell, or Azure CLI to assign one of the built-in roles to the Entra ID identity of a user.
 
 > [!IMPORTANT]
-> Share-level permission changes usually take effect within 30 minutes. Wait for permissions to propagate before connecting to the file share by using your credentials.
+> Share-level permission changes usually take effect within 30 minutes, but in some cases they can take longer. Wait for permissions to propagate before connecting to the file share by using your credentials.
 
 # [Portal](#tab/azure-portal)
 
@@ -80,7 +80,7 @@ To assign an Azure role to an Entra identity by using the [Azure portal](https:/
 1. Select **Access Control (IAM)**.
 1. Select **Add a role assignment**.
 1. In the **Add role assignment** pane, select the [appropriate built-in role](#azure-rbac-roles-for-azure-files) from the **Role** list.
-1.  Keep **Assign access to** at the default setting: **Microsoft Entra user, group, or service principal**. Select the target Entra identity by name or email address. **The selected 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.
+1. Keep **Assign access to** at the default setting: **Microsoft Entra user, group, or service principal**. Select the target Entra identity by name or email address. **The selected 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.
 1. Select **Save** to complete the role assignment operation.
 
 # [Azure PowerShell](#tab/azure-powershell)
@@ -91,7 +91,7 @@ Before you run the following sample script, replace placeholder values, includin
 
 ```powershell
 #Get the name of the custom role
-$FileShareContributorRole = Get-AzRoleDefinition "<role-name>" #Use one of the built-in roles: Storage File Data SMB Share Reader, Storage File Data SMB Share Contributor, Storage File Data SMB Share Elevated Contributor
+$FileShareContributorRole = Get-AzRoleDefinition "<role-name>" #Use one of the built-in roles: Storage File Data SMB Share Reader, Storage File Data SMB Share Contributor, Storage File Data SMB Share Elevated Contributor, Storage File Data Privileged Contributor, Storage File Data Privileged Reader, Storage File Data SMB Admin
 #Constrain the scope to the target file share
 $scope = "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/fileServices/default/fileshares/<share-name>"
 #Assign the custom role to the target identity with the specified scope.
@@ -102,10 +102,11 @@ New-AzRoleAssignment -SignInName <user-principal-name> -RoleDefinitionName $File
 
 The following CLI command assigns an Azure role to an Entra identity based on sign-in name. For more information about assigning Azure roles by using Azure CLI, see [Add or remove Azure role assignments using the Azure CLI](../../role-based-access-control/role-assignments-cli.md).  
 
-Before you run the following sample script, replace placeholder values, including brackets, with your own values.
+Before you run the following command, replace placeholder values, including brackets, with your own values.
 
 ```azurecli-interactive
-#Assign the built-in role to the target identity: Storage File Data SMB Share Reader, Storage File Data SMB Share Contributor, Storage File Data SMB Share Elevated Contributor, Storage File Data Privileged Contributor, Storage File Data Privileged Reader
+#Assign one of the built-in roles to the target identity: Storage File Data SMB Share Reader, Storage File Data SMB Share Contributor, Storage File Data SMB Share Elevated Contributor, Storage File Data Privileged Contributor, Storage File Data Privileged Reader, Storage File Data SMB Admin
+
 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>"
 ```
 ---
@@ -134,29 +135,29 @@ To configure default share-level permissions on your storage account by using th
 
 # [Azure PowerShell](#tab/azure-powershell)
 
-Use the following script to configure default share-level permissions on your storage account. You can enable default share-level permission only on storage accounts associated with a directory service for Azure Files authentication. 
+Use the following script to configure default share-level permissions on your storage account. You can only enable default share-level permission on storage accounts that have an identity source enabled for Azure Files authentication.
 
-Before running the following script, make sure your Az.Storage module is version 3.7.0 or newer. Update to the latest version if needed.
+Before running the following script, make sure your Az.Storage module is version 3.7.0 or newer. Update to the [latest version](https://www.powershellgallery.com/packages/Az.Storage/) if needed. Replace `<resource-group-name>` and `<storage-account-name>` with your own values.
 
 ```azurepowershell
-$defaultPermission = "None|StorageFileDataSmbShareContributor|StorageFileDataSmbShareReader|StorageFileDataSmbShareElevatedContributor" # Set the default permission of your choice
+$defaultPermission = "None|StorageFileDataSmbShareContributor|StorageFileDataSmbShareReader|StorageFileDataSmbShareElevatedContributor|StorageFileDataPrivilegedContributor|StorageFileDataPrivilegedReader|StorageFileDataSmbAdmin" # Set the default permission of your choice. Specify only one of the built-in roles.
 
-$account = Set-AzStorageAccount -ResourceGroupName "<resource-group-name-here>" -AccountName "<storage-account-name-here>" -DefaultSharePermission $defaultPermission
+$account = Set-AzStorageAccount -ResourceGroupName "<resource-group-name>" -AccountName "<storage-account-name>" -DefaultSharePermission $defaultPermission
 
 $account.AzureFilesIdentityBasedAuth
 ```
 
 # [Azure CLI](#tab/azure-cli)
 
-Use the following script to configure default share-level permissions on your storage account. You can enable default share-level permission only on storage accounts associated with a directory service for Azure Files authentication. 
+Use the following script to configure default share-level permissions on your storage account. You can only enable default share-level permission on storage accounts that have an identity source enabled for Azure Files authentication.
 
 Before running the following script, make sure your Azure CLI is version 2.24.1 or later.
 
 ```azurecli
 # Declare variables
 storageAccountName="YourStorageAccountName"
 resourceGroupName="YourResourceGroupName"
-defaultPermission="None|StorageFileDataSmbShareContributor|StorageFileDataSmbShareReader|StorageFileDataSmbShareElevatedContributor" # Set the default permission of your choice
+defaultPermission="None|StorageFileDataSmbShareContributor|StorageFileDataSmbShareReader|StorageFileDataSmbShareElevatedContributor|StorageFileDataPrivilegedContributor|StorageFileDataPrivilegedReader|StorageFileDataSmbAdmin" # Set the default permission of your choice. Specify only one of the built-in roles.
 
 az storage account update --name $storageAccountName --resource-group $resourceGroupName --default-share-permission $defaultPermission
 ```
@@ -181,4 +182,4 @@ Because of this process, authorization is based on the groups listed in the Kerb
 
 ## Next step
 
-After you assign share-level permissions, you can [configure directory and file-level permissions](storage-files-identity-configure-file-level-permissions.md). Share-level permissions can take up to three hours to take effect.
+After you assign share-level permissions, you can [configure directory and file-level permissions](storage-files-identity-configure-file-level-permissions.md). Wait for share-level permissions to propagate first.