Merge pull request #189372 from laujan/1921051-update-managed-identities

update managed identities articles

Author: jborsecnik

articles/applied-ai-services/form-recognizer/managed-identities.md

@@ -7,27 +7,25 @@ manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: forms-recognizer
 ms.topic: how-to
-ms.date: 01/26/2022
+ms.date: 02/22/2022
 ms.author: lajanuar
 ms.custom: ignite-fall-2021
 ---
 
-# Create and use managed identities with Form Recognizer
+# Managed identities for Form Recognizer
 
-> [!IMPORTANT]
-> Azure RBAC (Azure role-based access control) assignment is currently in preview and not recommended for production workloads. Certain features may not be supported or have constrained capabilities. Azure RBAC assignments are used to grant permissions for managed identity.
+Managed identities for Azure resources are service principals that create an Azure Active Directory (Azure AD) identity and specific permissions for Azure managed resources:
 
-## What is managed identity?
+* You can use managed identities to grant access to any resource that supports Azure AD authentication, including your own applications. Unlike security keys and authentication tokens, managed identities eliminate the need for developers to manage credentials.
 
-Azure managed identity is a service principal. It creates an Azure Active Directory (Azure AD) identity and specific permissions for Azure managed resources. You can use a managed identity to grant access to any resource that supports Azure AD authentication. To grant access, assign a role to a managed identity using [Azure RBAC](../../role-based-access-control/overview.md) (Azure role-based access control).  There's no added cost to use managed identity in Azure.
+* To grant access to an Azure resource, assign an Azure role to a managed identity using [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md).
 
-Managed identity supports both privately and publicly accessible Azure blob storage accounts.  For storage accounts with public access, you can opt to use a shared access signature (SAS) to grant limited access.   In this article, you'll learn to enable a system-assigned managed identity for your Form Recognizer instance.
+* There's no added cost to use managed identities in Azure.
 
-## Private storage account access
-> [!NOTE]
->
-> Form Recognizer only supports system-assigned managed identities today. User-assigned managed identities is on the roadmap and will be enabled in the near future. 
+> [!TIP]
+> Managed identities eliminate the need for you to manage credentials, including Shared Access Signature (SAS) tokens. Managed identities are a safer way to grant access to data without having credentials in your code.
 
+## Private storage account access
 
  Private Azure storage account access and authentication are supported by [managed identities for Azure resources](../../active-directory/managed-identities-azure-resources/overview.md). If you have an Azure storage account, protected by a Virtual Network (VNet) or firewall, Form Recognizer can't directly access your storage account data. However, once a managed identity is enabled, Form Recognizer can access your storage account using an assigned managed identity credential.
 
@@ -45,7 +43,7 @@ To get started, you'll need:
 
 * A [**Form Recognizer**](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) or [**Cognitive Services**](https://portal.azure.com/#create/Microsoft.CognitiveServicesAllInOne) resource in the Azure portal. For detailed steps, _see_ [Create a Cognitive Services resource using the Azure portal](../../cognitive-services/cognitive-services-apis-create-account.md?tabs=multiservice%2cwindows).
 
-* An [**Azure blob storage account**](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM) in the same region as your Form Recognizer resource. You'll create containers to store and organize your blob data within your storage account. 
+* An [**Azure blob storage account**](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM) in the same region as your Form Recognizer resource. You'll create containers to store and organize your blob data within your storage account.
 
   * If your storage account is behind a firewall, **you must enable the following configuration**: </br></br>
 
@@ -62,7 +60,11 @@ To get started, you'll need:
 
 ## Managed identity assignments
 
-There are two types of managed identity: **system-assigned** and **user-assigned**. Currently, Form Recognizer is supported by system-assigned managed identity. A system-assigned managed identity is **enabled** directly on a service instance. It isn't enabled by default; you have to go to your resource and update the identity setting. The system-assigned managed identity is tied to your resource throughout its lifecycle. If you delete your resource, the managed identity will be deleted as well.
+There are two types of managed identity: **system-assigned** and **user-assigned**. Currently, Form Recognizer supports system-assigned managed identity:
+
+* A system-assigned managed identity is **enabled** directly on a service instance. It isn't enabled by default; you must go to your resource and update the identity setting.
+
+* The system-assigned managed identity is tied to your resource throughout its lifecycle. If you delete your resource, the managed identity will be deleted as well.
 
 In the following steps, we'll enable a system-assigned managed identity and grant Form Recognizer limited access to your Azure blob storage account.
 
@@ -82,6 +84,10 @@ In the following steps, we'll enable a system-assigned managed identity and gran
 
 1. In the main window, toggle the **System assigned Status** tab to **On**.
 
+## Grant access to your storage account
+
+You need to grant Form Recognizer access to your storage account before it can create, read, or delete blobs. Now that you've enabled Form Recognizer with a system-assigned managed identity, you can use Azure role-based access control (Azure RBAC), to give Form Recognizer access to Azure storage. The **Storage Blob Data Reader** role gives Form Recognizer (represented by the system-assigned managed identity) read and list access to the blob container and data.
+
 1. Under **Permissions** select **Azure role assignments**:
 
     :::image type="content" source="media/managed-identities/enable-system-assigned-managed-identity-portal.png" alt-text="Screenshot: enable system-assigned managed identity in Azure portal.":::
@@ -94,14 +100,14 @@ In the following steps, we'll enable a system-assigned managed identity and gran
     >
     > If you're unable to assign a role in the Azure portal because the Add > Add role assignment option is disabled or you get the permissions error, "you do not have permissions to add role assignment at this scope", check that you're currently signed in as a user with an assigned a role that has Microsoft.Authorization/roleAssignments/write permissions such as Owner or User Access Administrator at the Storage scope for the storage resource.
 
- 7. Next, you're going to assign a **Storage Blob Data Reader** role to your Form Recognizer service resource. In the **Add role assignment** pop-up window complete the fields as follows and select **Save**:
+1. Next, you're going to assign a **Storage Blob Data Reader** role to your Form Recognizer service resource. In the **Add role assignment** pop-up window complete the fields as follows and select **Save**:
 
     | Field | Value|
     |------|--------|
-    |**Scope**| ***Storage***|
-    |**Subscription**| ***The subscription associated with your storage resource***.|
-    |**Resource**| ***The name of your storage resource***|
-    |**Role** | ***Storage Blob Data Reader***—allows for read access to Azure Storage blob containers and data.|
+    |**Scope**| **_Storage_**|
+    |**Subscription**| **_The subscription associated with your storage resource_**.|
+    |**Resource**| **_The name of your storage resource_**|
+    |**Role** | **_Storage Blob Data Reader_**—allows for read access to Azure Storage blob containers and data.|
 
      :::image type="content" source="media/managed-identities/add-role-assignment-window.png" alt-text="Screenshot: add role assignments page in the Azure portal.":::
 
@@ -113,9 +119,9 @@ In the following steps, we'll enable a system-assigned managed identity and gran
 
     :::image type="content" source="media/managed-identities/assigned-roles-window.png" alt-text="Screenshot: Azure role assignments window.":::
 
- That's it! You've completed the steps to enable a system-assigned managed identity. With this identity credential, you can grant Form Recognizer-specific access rights to documents and files stored in your BYOS account.
+ That's it! You've completed the steps to enable a system-assigned managed identity. With managed identity and Azure RBAC, you granted Form Recognizer specific access rights to your storage resource without having to manage credentials such as SAS tokens.
 
 ## Learn more about  managed identity
 
 > [!div class="nextstepaction"]
-> [Managed identities for Azure resources: frequently asked questions - Azure AD](../../active-directory/managed-identities-azure-resources/managed-identities-faq.md)
+> [Access Azure Storage form a web app using managed identities](/azure/app-service/scenario-secure-app-access-storage?toc=/azure/applied-ai-services/form-recognizer/toc.json&bc=/azure/applied-ai-services/form-recognizer/breadcrumb/toc.json )

articles/applied-ai-services/form-recognizer/toc.yml

@@ -152,6 +152,8 @@ items:
   items:
   - name: Use Form Recognizer with Azure Logic Apps
     href: tutorial-logic-apps.md
+  - name: Use managed identities to access Azure storage
+    href: /azure/app-service/scenario-secure-app-access-storage?toc=/azure/applied-ai-services/form-recognizer/toc.json&bc=/azure/applied-ai-services/form-recognizer/breadcrumb/toc.json  
   - name: "Create Form Recognizer workflows with AI Builder"
     expanded: true
     items:

articles/cognitive-services/Translator/document-translation/managed-identity.md

@@ -1,27 +1,32 @@
 ---
-title: Create and use managed identity
+title: Create and use managed identities for Document Translation
 titleSuffix: Azure Cognitive Services
-description: Understand how to create and use managed identity in the Azure portal
+description: Understand how to create and use managed identities in the Azure portal
 author: laujan
 manager: nitinme
 ms.service: cognitive-services
 ms.subservice: translator-text
 ms.topic: how-to
-ms.date: 09/09/2021
+ms.date: 02/22/2022
 ms.author: lajanuar
 ---
 
-# Create and use managed identity
+# Managed identities for Document Translation
 
 > [!IMPORTANT]
 >
-> Managed identity for Document Translation is currently unavailable in the global region. If you intend to use managed identity for Document Translation operations, [create your Translator resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) in a non-global Azure region.
+> Managed identities for Azure resources are currently unavailable for Document Translation service in the global region. If you intend to use managed identities for Document Translation operations, [create your Translator resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) in a non-global Azure region.
 
-## What is managed identity?
+Managed identities for Azure resources are service principals that create an Azure Active Directory (Azure AD) identity and specific permissions for Azure managed resources:
 
- Azure managed identity is a service principal that creates an Azure Active Directory (Azure AD) identity and specific permissions for Azure managed resources. You can use a managed identity to grant access to any resource that supports Azure AD authentication. To grant access, assign a role to a managed identity using [Azure role-based access control](../../../role-based-access-control/overview.md) (Azure RBAC).  There is no added cost to use managed identity in Azure.
+* You can use managed identities to grant access to any resource that supports Azure AD authentication, including your own applications. Unlike security keys and authentication tokens, managed identities eliminate the need for developers to manage credentials. 
 
-Managed identity supports both privately and publicly accessible Azure blob storage accounts.  For storage accounts **with public access**, you can opt to use a shared access signature (SAS) to grant limited access.  In this article, we will examine how to manage access to translation documents in your Azure blob storage account using system-assigned managed identity.
+* To grant access to an Azure resource, assign an Azure role to a managed identity using [Azure role-based access control (Azure RBAC)](../../../role-based-access-control/overview.md).
+
+* There's no added cost to use managed identities in Azure.
+
+> [!TIP]
+> Managed identities eliminate the need for you to manage credentials, including Shared Access Signature (SAS) tokens. Managed identities are a safer way to grant access to data without having credentials in your code.
 
 ## Prerequisites
 
@@ -43,17 +48,21 @@ To get started, you'll need:
   * In the main window, select **Allow access from Selected networks**.
   :::image type="content" source="../media/managed-identities/firewalls-and-virtual-networks.png" alt-text="Screenshot: Selected networks radio button selected.":::
 
-  * On the selected networks page navigate to the **Exceptions** category and make certain that the  [**Allow Azure services on the trusted services list to access this storage account**](../../../storage/common/storage-network-security.md?tabs=azure-portal#manage-exceptions) checkbox is enabled.
+  * On the selected networks page, navigate to the **Exceptions** category and make certain that the  [**Allow Azure services on the trusted services list to access this storage account**](../../../storage/common/storage-network-security.md?tabs=azure-portal#manage-exceptions) checkbox is enabled.
 
     :::image type="content" source="../media/managed-identities/allow-trusted-services-checkbox-portal-view.png" alt-text="Screenshot: allow trusted services checkbox, portal view":::
 
-## Managed Identity assignments
+## Managed identity assignments
+
+There are two types of managed identities: **system-assigned** and **user-assigned**.  Currently, Document Translation supports system-assigned managed identities:
 
-There are two types of managed identity: **system-assigned** and **user-assigned**.  Currently, Document Translation is supported by system-assigned managed identity. A system-assigned managed identity is **enabled** directly on a service instance. It is not enabled by default; you must go to your resource and update the identity setting. The system-assigned managed identity is tied to your resource throughout its lifecycle. If you delete your resource, the managed identity will be deleted as well.
+* A system-assigned managed identity is **enabled** directly on a service instance. It isn't enabled by default; you must go to your resource and update the identity setting. 
+
+* The system-assigned managed identity is tied to your resource throughout its lifecycle. If you delete your resource, the managed identity will be deleted as well.
 
 In the following steps, we'll enable a system-assigned managed identity and grant your Translator resource limited access to your Azure blob storage account.
 
-## Enable a system-assigned managed identity using the Azure portal
+## Enable a system-assigned managed identity
 
 >[!IMPORTANT]
 >
@@ -69,6 +78,12 @@ In the following steps, we'll enable a system-assigned managed identity and gran
 
 1. In the main window, toggle the **System assigned Status** tab to **On**.
 
+## Grant access to your storage account
+
+You need to grant Translator access to your storage account before it can create, read, or delete blobs. Now that you enabled Translator with a system-assigned managed identity, you can use Azure role-based access control (Azure RBAC), to give Translator access to Azure storage. 
+
+The **Storage Blob Data Contributor** role gives Translator (represented by the system-assigned managed identity) read, write, and delete access to the blob container and data.
+
 1. Under **Permissions** select **Azure role assignments**:
 
     :::image type="content" source="../media/managed-identities/enable-system-assigned-managed-identity-portal.png" alt-text="Screenshot: enable system-assigned managed identity in Azure portal.":::
@@ -85,27 +100,24 @@ In the following steps, we'll enable a system-assigned managed identity and gran
 
     | Field | Value|
     |------|--------|
-    |**Scope**| ***Storage***.|
-    |**Subscription**| ***The subscription associated with your storage resource***.|
-    |**Resource**| ***The name of your storage resource***.|
-    |**Role** | ***Storage Blob Data Contributor***.|
+    |**Scope**| **_Storage_**.|
+    |**Subscription**| **_The subscription associated with your storage resource_**.|
+    |**Resource**| **_The name of your storage resource_**.|
+    |**Role** | **_Storage Blob Data Contributor_**.|
 
      :::image type="content" source="../media/managed-identities/add-role-assignment-window.png" alt-text="Screenshot: add role assignments page in the Azure portal.":::
 
-1. After you've received the _Added Role assignment_ confirmation message, refresh the page to see the added role assignment. 
+1. After you've received the _Added Role assignment_ confirmation message, refresh the page to see the added role assignment.
 
     :::image type="content" source="../media/managed-identities/add-role-assignment-confirmation.png" alt-text="Screenshot: Added role assignment confirmation pop-up message.":::
 
 1. If you don't see the change right away, wait and try refreshing the page once more. When you assign or remove role assignments, it can take up to 30 minutes for changes to take effect.
 
     :::image type="content" source="../media/managed-identities/assigned-roles-window.png" alt-text="Screenshot: Azure role assignments window.":::
 
- Great! You have completed the steps to enable a system-assigned managed identity. With this identity credential, you can grant Translator specific access rights to your storage resource.
+ Great! You've completed the steps to enable a system-assigned managed identity. With managed identity and Azure RBAC, you granted Translator specific access rights to your storage resource without having to manage credentials such as SAS tokens.
 
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Managed identities for Azure resources: frequently asked questions](../../../active-directory/managed-identities-azure-resources/managed-identities-faq.md)
-
-> [!div class="nextstepaction"]
->[Use managed identities to acquire an access token](../../../app-service/overview-managed-identity.md?tabs=dotnet#configure-target-resource)
+> [Access Azure Storage from a web app using managed identities](/azure/app-service/scenario-secure-app-access-storage?toc=/azure/cognitive-services/translator/toc.json&bc=/azure/cognitive-services/translator/breadcrumb/toc.json)

articles/cognitive-services/Translator/toc.yml

@@ -67,6 +67,8 @@ items:
         href: containers/translator-container-supported-parameters.md
   - name: Tutorials
     items:
+    - name: Use managed identities to access Azure storage
+      href: /azure/app-service/scenario-secure-app-access-storage?toc=/azure/cognitive-services/translator/toc.json&bc=/azure/cognitive-services/translator/breadcrumb/toc.json
     - name: Create a Translator workflow
       href: /ai-builder/flow-text-translation?toc=/azure/cognitive-services/translator/toc.json&bc=/azure/cognitive-services/translator/breadcrumb/toc.json
     - name: Translate text with Translator