Create and use managed identity for your Form Recognizer resource
Azure role-based access control (Azure RBAC) 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.
What is managed identity?
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 (Azure RBAC). There is no added cost to use managed identity in Azure.
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.
Private storage account access
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.
Private Azure storage account access and authentication is supported by managed identities for Azure resources. If you have an Azure storage account protected by a Virtual Network (VNet) or firewall or have enabled bring-your-own-storage (BYOS), Form Recognizer cannot directly access your storage account data; however, once a managed identity is enabled, the Form Recognizer service can access your storage account using an assigned managed identity credential.
If you intend to analyze your storage data with the Form Recognizer Sample Labeling tool (FOTT), you must deploy the tool behind your VNet or firewall.
The Analyze Receipt, Business Card, Invoice, ID document, and Custom Form APIs can extract data from a single document by posting requests as raw binary content. In these scenarios, there is no requirement for a managed identity credential.
To get started, you'll need:
A Form Recognizer or Cognitive Services resource in the Azure portal. For detailed steps, see Create a Cognitive Services resource using the Azure portal.
An Azure blob storage account 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:
On your storage account page, select Security + networking → Networking from the left menu.
In the main window, select Allow access from selected networks.
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 checkbox is enabled.
A brief understanding of Azure role-based access control (Azure RBAC) using the Azure portal.
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 is not 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.
In the following steps, we will enable a system-assigned managed identity and grant Form Recognizer limited access to your Azure blob storage account.
Enable a system-assigned managed identity
To enable a system-assigned managed identity, you need Microsoft.Authorization/roleAssignments/write permissions, such as Owner or User Access Administrator. You can specify a scope at four levels: management group, subscription, resource group, or resource.
Sign in to the Azure portal using an account associated with your Azure subscription.
Navigate to your Form Recognizer resource page in the Azure portal.
In the left rail, Select Identity from the Resource Management list:
In the main window, toggle the System assigned Status tab to On.
Under Permissions select Azure role assignments:
An Azure role assignments page will open. Choose your subscription from the drop-down menu then select + Add role assignment.
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.
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.
After you've received the Added Role assignment confirmation message, refresh the page to see the added role assignment.
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.
That's it! You have 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.