Reorganize ACLing docs for Portal and PowerShell

MaximeKjaer · web-flow · commit 7e3d81b8ed1d · 2026-04-16T11:59:48.000-07:00
diff --git a/articles/storage/files/storage-files-identity-auth-hybrid-identities-enable.md b/articles/storage/files/storage-files-identity-auth-hybrid-identities-enable.md
@@ -207,7 +207,7 @@ To set share-level permissions, follow the instructions in [Assign share-level p
 
 ## Configure directory and file-level permissions
 
-Once share-level permissions are in place, you can assign Windows ACLs (directory and file-level permissions) to the user or group. **For hybrid identities, this assignment requires using a device with unimpeded network connectivity to an Active Directory**.
+Once share-level permissions are in place, you can assign Windows ACLs (directory and file-level permissions) to the user or group. **For hybrid identities, if using icacls or File Explorer, this assignment requires using a device with unimpeded network connectivity to an Active Directory**.
 
 To configure directory and file-level permissions, follow the instructions in [Configure directory and file-level permissions over SMB](storage-files-identity-configure-file-level-permissions.md).
 
diff --git a/articles/storage/files/storage-files-identity-configure-file-level-permissions.md b/articles/storage/files/storage-files-identity-configure-file-level-permissions.md
@@ -17,13 +17,19 @@ Before you can configure directory-level and file-level permissions, you must [a
 
 ## Prerequisites
 
-If you want to configure Windows ACLs for [hybrid identities](/entra/identity/hybrid/whatis-hybrid-identity) and the identity source for your storage account is Active Directory Domain Services (AD DS) or Microsoft Entra Kerberos, you need a client machine running Windows that has unimpeded network connectivity to on-premises Active Directory.
+Consult the following table to determine which tool can be used for which authentication type.
 
-If the identity source for your storage account is Microsoft Entra Domain Services, you need a client machine running Windows that has unimpeded network connectivity to the domain controllers for the domain that Microsoft Entra Domain Services manages. These domain controllers are located in Azure.
+| Tool                            | AD DS (Hybrid)           | Entra Domain Services (Hybrid) | Entra Kerberos (Hybrid)  | Entra Kerberos (Cloud-only, preview) |
+|---------------------------------|:------------------------:|:------------------------------:|:------------------------:|:------------------------------------:|
+| Windows File Explorer           | :heavy_check_mark:       | :heavy_check_mark:             | :heavy_check_mark:       | :heavy_multiplication_x:             |
+| icacls                          | :heavy_check_mark:       | :heavy_check_mark:             | :heavy_check_mark:       | :heavy_multiplication_x:             |
+| PowerShell (Set-ACL)            | :heavy_check_mark:       | :heavy_check_mark:             | :heavy_check_mark:       | :heavy_multiplication_x:             |
+| Azure portal                    | :heavy_multiplication_x: | :heavy_multiplication_x:       | :heavy_check_mark:       | :heavy_check_mark:                   |
+| PowerShell (RestSetAcls module) | :heavy_multiplication_x: | :heavy_multiplication_x:       | :heavy_check_mark:       | :heavy_check_mark:                   |
 
-If your identity source is Microsoft Entra Kerberos and you want to configure Windows ACLs for cloud-only identities (preview), there's no dependency on domain controllers, but the client device must be joined to Microsoft Entra ID.
+To use Windows File Explorer, icacls or PowerShell (Set-Acl), you need a client machine running Windows. You will also need to mount the file share with admin-level access. If the identity source for your storage account is Active Directory Domain Services (AD DS) or Microsoft Entra Kerberos, this machine must have unimpeded network connectivity to an on-premises Active Directory. If the identity source is Microsoft Entra Domain Services, the machine must have unimpeded network connectivity to the domain controllers for the domain that Microsoft Entra Domain Services manages; these domain controllers are located in Azure.
 
-Before you can configure Windows ACLs, you need to mount the file share with admin-level access.
+To use the Azure portal or the PowerShell RestSetAcls module, there's no dependency on domain controllers. However, the identities must be hybrid or cloud-native (preview). For RestSetAcls, you need a client machine running Windows.
 
 ## How Azure RBAC and Windows ACLs work together
 
@@ -72,17 +78,34 @@ The root directory of a file share includes the following permissions:
 
 For more information on these permissions, see the [command-line reference for icacls](/windows-server/administration/windows-commands/icacls).
 
-## Mount the file share with admin-level access
+## Configure Windows ACLs
+
+The process for configuring Windows ACLs varies depending on whether you're authenticating hybrid or cloud-only identities:
+
+- For cloud-only identities (preview), you must use the Azure portal or PowerShell. Windows File Explorer and icacls aren't currently supported for cloud-only identities.
+
+- For hybrid identities, you can configure Windows ACLs by using icacls, or you can use Windows File Explorer. You can also use the [Set-ACL](/powershell/module/microsoft.powershell.security/set-acl) PowerShell command.
 
-Before you configure Windows ACLs, mount the file share with admin-level access. You can take two approaches:
+  If you have directories or files in on-premises file servers with Windows ACLs configured against the AD DS identities, you can copy them over to Azure Files while preserving the ACLs by using traditional file copy tools like Robocopy or the latest version of [Azure AzCopy](https://github.com/Azure/azure-storage-azcopy/releases). If you tier directories and files to Azure Files through Azure File Sync, your ACLs are carried over and persisted in their native format.
+
+> [!IMPORTANT]
+> If you're using Microsoft Entra Kerberos to authenticate hybrid identities, the hybrid identities must be synced to Microsoft Entra ID for ACLs to be enforced.
+>
+> You can set file-level and directory-level ACLs for identities that aren't synced to Microsoft Entra ID. However, these ACLs aren't enforced because the Kerberos ticket used for authentication and authorization doesn't contain the not-synced identities. If you're using on-premises AD DS as your identity source, you can include not-synced identities in the ACLs. AD DS puts those security identifiers (SIDs) in the Kerberos ticket, and ACLs are enforced.
+
+## Configure Windows ACLs with Windows File Explorer or icacls
+
+### Mount the file share with admin-level access
+
+Before you configure Windows ACLs with File Explorer or icacls, mount the file share with admin-level access. You can take two approaches:
 
 - **Use the Windows permission model for SMB admin (recommended)**: Assign the built-in RBAC role [Storage File Data SMB Admin](/azure/role-based-access-control/built-in-roles/storage#storage-file-data-smb-admin) to admin users who will configure ACLs. Then mount the file share by using [identity-based authentication](storage-files-active-directory-overview.md) and configure ACLs. If an existing ACL on a file or directory denies the admin access, the admin can use the Windows `takeown` command to take ownership of the file or directory and then modify the ACL. This approach is more secure because it doesn't require your storage account key to mount the file share.
 
 - **Use the storage account key (less secure)**: Use your storage account key to mount the file share and then configure ACLs. Mounting with a storage account key gives you immediate full access without needing to take ownership of files or directories. The storage account key is a sensitive credential. For security reasons, use this option only if you can't use identity-based authentication.
 
 If a user has the Full Control ACL and the [Storage File Data SMB Share Elevated Contributor](/azure/role-based-access-control/built-in-roles/storage#storage-file-data-smb-share-elevated-contributor) role (or a custom role with the required permissions), they can configure ACLs without using the Windows permission model for SMB admin or the storage account key.
 
-### Use the Windows permission model for SMB admin
+#### Use the Windows permission model for SMB admin
 
 Use the Windows permission model for SMB admin instead of the storage account key. This feature enables you to assign the built-in RBAC role [Storage File Data SMB Admin](/azure/role-based-access-control/built-in-roles/storage#storage-file-data-smb-admin) to admin users, so they can mount the share using identity-based authentication and configure ACLs.
 
@@ -113,7 +136,7 @@ To use the Windows permission model for SMB admin, follow these steps:
       net use Z: \\<YourStorageAccountName>.file.core.windows.net\<FileShareName>
       ```
 
-### Mount the file share by using your storage account key (not recommended)
+#### Mount the file share by using your storage account key (not recommended)
 
 > [!WARNING]
 > If possible, use the [Windows permission model for SMB admin](#use-the-windows-permission-model-for-smb-admin) to mount the share instead of using the storage account key.
@@ -128,26 +151,51 @@ Use the `net use` command to mount the share at this stage and not PowerShell. I
 net use Z: \\<YourStorageAccountName>.file.core.windows.net\<FileShareName> /user:localhost\<YourStorageAccountName> <YourStorageAccountKey>
 ```
 
-## Configure Windows ACLs
+### Configure Windows ACLs by using icacls
 
-The process for configuring Windows ACLs varies depending on whether you're authenticating hybrid or cloud-only identities:
+> [!IMPORTANT]
+> Using icacls doesn't work for cloud-only identities.
 
-- For cloud-only identities (preview), you must use the Azure portal or PowerShell. Windows File Explorer and icacls aren't currently supported for cloud-only identities.
+To grant full permissions to all directories and files under the file share, including the root directory, run the following Windows command from a machine that has unimpeded network connectivity to the Active Directory domain controller. Remember to replace the placeholder values in the example with your own values. If your identity source is Microsoft Entra Domain Services, then `<user-upn>` is `<user-email>`.
 
-- For hybrid identities, you can configure Windows ACLs by using icacls, or you can use Windows File Explorer. You can also use the [Set-ACL](/powershell/module/microsoft.powershell.security/set-acl) PowerShell command.
+```
+icacls <mapped-drive-letter>: /grant <user-upn>:(f)
+```
 
-  If you have directories or files in on-premises file servers with Windows ACLs configured against the AD DS identities, you can copy them over to Azure Files while preserving the ACLs by using traditional file copy tools like Robocopy or the latest version of [Azure AzCopy](https://github.com/Azure/azure-storage-azcopy/releases). If you tier directories and files to Azure Files through Azure File Sync, your ACLs are carried over and persisted in their native format.
+For more information on how to use icacls to set Windows ACLs and on the types of supported permissions, see [the command-line reference for icacls](/windows-server/administration/windows-commands/icacls).
+
+### Configure Windows ACLs by using Windows File Explorer
+
+If you sign in to a domain-joined Windows client, you can use Windows File Explorer to grant full permission to all directories and files under the file share, including the root directory. Using File Explorer works only for hybrid identities.
 
 > [!IMPORTANT]
-> If you're using Microsoft Entra Kerberos to authenticate hybrid identities, the hybrid identities must be synced to Microsoft Entra ID for ACLs to be enforced.
->
-> You can set file-level and directory-level ACLs for identities that aren't synced to Microsoft Entra ID. However, these ACLs aren't enforced because the Kerberos ticket used for authentication and authorization doesn't contain the not-synced identities. If you're using on-premises AD DS as your identity source, you can include not-synced identities in the ACLs. AD DS puts those security identifiers (SIDs) in the Kerberos ticket, and ACLs are enforced.
+> Using Windows File Explorer doesn't work for cloud-only identities. If your client isn't domain joined, or if your environment has multiple Active Directory forests, don't use File Explorer to configure ACLs. [Use icacls](#configure-windows-acls-by-using-icacls) instead. This restriction exists because Windows File Explorer ACL configuration requires the client to be domain joined to the Active Directory domain that the storage account is joined to.
 
-### Configure Windows ACLs by using the Azure portal
+To configure ACLs by using Windows File Explorer, follow these steps:
+
+1. Open Windows File Explorer, right-click the file or directory, and then select **Properties**.
+
+1. Select the **Security** tab.
+
+1. Select **Edit** to change permissions.
+
+1. Change the permissions of existing users, or select **Add** to grant permissions to new users.
+
+1. In the prompt window for adding new users, enter the target username that you want to grant permissions to in the **Enter the object names to select** box. To find the full user principal name (UPN) of the target user, select **Check Names**.
+
+   You might need to specify domain name and domain GUID for your on-premises Active Directory deployment. You can get this information from your domain admin or from an on-premises Active Directory-joined client.
+
+1. Select **OK**.
+
+1. On the **Security** tab, select all permissions you want to grant your new user.
+
+1. Select **Apply**.
+
+## Configure Windows ACLs by using the Azure portal
 
 If you configure Entra Kerberos as your identity source, you can configure Windows ACLs for each Entra user or group by using the Azure portal. This method works for both hybrid and cloud-only identities only when Entra Kerberos is used as the identity source.
 
-1. Sign in to the Azure portal by using this specific URL: [https://aka.ms/portal/fileperms](https://aka.ms/portal/fileperms).
+1. Sign in to the [Azure portal](https://portal.azure.com/).
 
 1. Go to the file share where you want to configure Windows ACLs.
 
@@ -169,9 +217,9 @@ If you configure Entra Kerberos as your identity source, you can configure Windo
 
 1. Select **Save** to set the ACL.
 
-### Configure Windows ACLs for cloud-only identities by using PowerShell
+## Configure Windows ACLs for cloud-only identities by using PowerShell
 
-If you need to assign ACLs in bulk to cloud-only users, use the [RestSetAcls PowerShell module](https://www.powershellgallery.com/packages/RestSetAcls/) to automate the process by using the Azure Files REST API.
+If you need to assign ACLs in bulk to cloud-only users, use the [RestSetAcls PowerShell module](https://www.powershellgallery.com/packages/RestSetAcls/) to automate the process by using the Azure Files REST API. This module does not require network connectivity to Active Directory.
 
 For example, if you want to set a root ACL that gives the cloud-only user `testUser@contoso.com` read access:
 
@@ -182,46 +230,6 @@ $context = New-AzStorageContext -StorageAccountName $AccountName -StorageAccount
 Add-AzFileAce -Context $context -FileShareName test -FilePath "/" -Type Allow -Principal "testUser@contoso.com" -AccessRights Read,Synchronize -InheritanceFlags ObjectInherit,ContainerInherit 
 ```
 
-### Configure Windows ACLs by using icacls
-
-> [!IMPORTANT]
-> Using icacls doesn't work for cloud-only identities.
-
-To grant full permissions to all directories and files under the file share, including the root directory, run the following Windows command from a machine that has unimpeded network connectivity to the Active Directory domain controller. Remember to replace the placeholder values in the example with your own values. If your identity source is Microsoft Entra Domain Services, then `<user-upn>` is `<user-email>`.
-
-```
-icacls <mapped-drive-letter>: /grant <user-upn>:(f)
-```
-
-For more information on how to use icacls to set Windows ACLs and on the types of supported permissions, see [the command-line reference for icacls](/windows-server/administration/windows-commands/icacls).
-
-### Configure Windows ACLs by using Windows File Explorer
-
-If you sign in to a domain-joined Windows client, you can use Windows File Explorer to grant full permission to all directories and files under the file share, including the root directory. Using File Explorer works only for hybrid identities.
-
-> [!IMPORTANT]
-> Using Windows File Explorer doesn't work for cloud-only identities. If your client isn't domain joined, or if your environment has multiple Active Directory forests, don't use File Explorer to configure ACLs. [Use icacls](#configure-windows-acls-by-using-icacls) instead. This restriction exists because Windows File Explorer ACL configuration requires the client to be domain joined to the Active Directory domain that the storage account is joined to.
-
-To configure ACLs by using Windows File Explorer, follow these steps:
-
-1. Open Windows File Explorer, right-click the file or directory, and then select **Properties**.
-
-1. Select the **Security** tab.
-
-1. Select **Edit** to change permissions.
-
-1. Change the permissions of existing users, or select **Add** to grant permissions to new users.
-
-1. In the prompt window for adding new users, enter the target username that you want to grant permissions to in the **Enter the object names to select** box. To find the full user principal name (UPN) of the target user, select **Check Names**.
-
-   You might need to specify domain name and domain GUID for your on-premises Active Directory deployment. You can get this information from your domain admin or from an on-premises Active Directory-joined client.
-
-1. Select **OK**.
-
-1. On the **Security** tab, select all permissions you want to grant your new user.
-
-1. Select **Apply**.
-
 ## Next step
 
 After you configure directory-level and file-level permissions, you can mount the SMB file share on [Windows](storage-how-to-use-files-windows.md) or [Linux](storage-how-to-use-files-linux.md).
