Merge pull request #211792 from khdownie/kendownie091922-2

Documenting migrate share level perms

Author: prmerger-automator[bot]

articles/storage/files/storage-files-identity-ad-ds-assign-permissions.md

@@ -1,11 +1,11 @@
 ---
 title: Control access to Azure file shares - on-premises AD DS authentication
-description: Learn how to assign permissions to an Active Directory Domain Services identity that represents your storage account. This allows you control access with identity-based authentication.
+description: Learn how to assign permissions to an Active Directory Domain Services identity that represents your Azure storage account. This allows you to control access with identity-based authentication.
 author: khdownie
 ms.service: storage
 ms.subservice: files
 ms.topic: how-to
-ms.date: 05/04/2022
+ms.date: 09/19/2022
 ms.author: kendownie 
 ms.custom: devx-track-azurepowershell, subject-rbac-steps, devx-track-azurecli 
 ms.devlang: azurecli
@@ -41,7 +41,7 @@ There are three scenarios where we instead recommend using default share-level p
 
 ## Share-level permissions
 
-The following table lists the share-level permissions and how they align with the built-in RBAC roles:
+The following table lists the share-level permissions and how they align with the built-in Azure role-based access control (RBAC) roles:
 
 |Supported built-in roles  |Description  |
 |---------|---------|
@@ -51,7 +51,7 @@ The following table lists the share-level permissions and how they align with th
 
 ## Share-level permissions for specific Azure AD users or groups
 
-If you intend to use a specific Azure AD 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 Azure AD**. For example, say you have a user in your AD that is [email protected] and you have synced to Azure AD as [email protected] using Azure AD Connect sync. For this user to access Azure Files, you must assign the share-level permissions to [email protected]. The same concept applies to groups or service principals.
+If you intend to use a specific Azure AD user or group to access Azure file share resources, that identity must be a [hybrid identity](/azure/active-directory/hybrid/whatis-hybrid-identity) that exists in both on-premises AD DS and Azure AD. For example, say you have a user in your AD that is [email protected] and you have synced to Azure AD as [email protected] using Azure AD Connect sync. For this user to access Azure Files, you must assign the share-level permissions to [email protected]. The same concept applies to groups or service principals.
 
 > [!IMPORTANT]
 > **Assign permissions by explicitly declaring actions and data actions as opposed to 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 means that all such identities will also be granted any new data action added to the platform. The additional access and permissions granted through new actions or data actions may be unwanted behavior for customers using wildcard. To mitigate any unintended future impact, we highly recommend declaring actions and data actions explicitly as opposed to using the wildcard.
@@ -63,6 +63,9 @@ In order for share-level permissions to work, you must:
 
 Share-level permissions must be assigned to the Azure AD identity representing the same user or group in your AD DS to support AD DS authentication to your Azure file share. Authentication and authorization against identities that only exist in Azure AD, such as Azure Managed Identities (MSIs), are not supported with AD DS authentication.
 
+> [!TIP]
+> Customers who want to migrate SMB server share-level permissions to RBAC permissions can 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 share on premises, then writes the appropriate users and groups to the Azure file share using the three RBAC roles. You provide the information for the on-premises share and the Azure file share when invoking the cmdlet.
+
 You can use the Azure portal, Azure PowerShell module, or Azure CLI to assign the built-in roles to the Azure AD identity of a user for granting share-level permissions.
 
 > [!IMPORTANT]