Authorize access to blobs using Azure Active Directory
Azure Storage supports using Azure Active Directory (Azure AD) to authorize requests to blob data. With Azure AD, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal, which may be a user, group, or application service principal. The security principal is authenticated by Azure AD to return an OAuth 2.0 token. The token can then be used to authorize a request against the Blob service.
Authorization with Azure AD provides superior security and ease of use over Shared Key authorization. Microsoft recommends using Azure AD authorization with your blob applications when possible to assure access with minimum required privileges.
Authorization with Azure AD is available for all general-purpose and Blob storage accounts in all public regions and national clouds. Only storage accounts created with the Azure Resource Manager deployment model support Azure AD authorization.
Blob storage additionally supports creating shared access signatures (SAS) that are signed with Azure AD credentials. For more information, see Grant limited access to data with shared access signatures.
Overview of Azure AD for blobs
When a security principal (a user, group, or application) attempts to access a blob resource, the request must be authorized, unless it's a blob available for anonymous access. With Azure AD, access to a resource is a two-step process:
First, the security principal's identity is authenticated and an OAuth 2.0 token is returned.
The authentication step requires that an application request an OAuth 2.0 access token at runtime. If an application is running from within an Azure entity such as an Azure VM, a virtual machine scale set, or an Azure Functions app, it can use a managed identity to access blob data.
Next, the token is passed as part of a request to the Blob service and used by the service to authorize access to the specified resource.
The authorization step requires that one or more Azure RBAC roles be assigned to the security principal making the request. For more information, see Assign Azure roles for access rights.
Use an Azure AD account with portal, PowerShell, or Azure CLI
To learn about how to access data in the Azure portal with an Azure AD account, see Data access from the Azure portal. To learn how to call Azure PowerShell or Azure CLI commands with an Azure AD account, see Data access from PowerShell or Azure CLI.
Use Azure AD to authorize access in application code
To authorize access to Azure Storage with Azure AD, you can use one of the following client libraries to acquire an OAuth 2.0 token:
- The Azure Identity client library is recommended for most development scenarios.
- The Microsoft Authentication Library (MSAL) may be suitable for certain advanced scenarios.
Azure Identity client library
An advantage of the Azure Identity client library is that it enables you to use the same code to acquire the access token whether your application is running in the development environment or in Azure. The Azure Identity client library returns an access token for a security principal. When your code is running in Azure, the security principal may be a managed identity for Azure resources, a service principal, or a user or group. In the development environment, the client library provides an access token for either a user or a service principal for testing purposes.
The access token returned by the Azure Identity client library is encapsulated in a token credential. You can then use the token credential to get a service client object to use in performing authorized operations against Azure Storage. A simple way to get the access token and token credential is to use the DefaultAzureCredential class that is provided by the Azure Identity client library. DefaultAzureCredential attempts to get the token credential by sequentially trying several different credential types. DefaultAzureCredential works in both the development environment and in Azure.
The following table points to additional information for authorizing access to data in various scenarios:
Microsoft Authentication Library (MSAL)
While Microsoft recommends using the Azure Identity client library when possible, the MSAL library may be appropriate to use in certain advanced scenarios. For more information, see Learn about MSAL.
When you use MSAL to acquire an OAuth token for access to Azure Storage, you need to provide an Azure AD resource ID. The Azure AD resource ID indicates the audience for which a token that is issued can be used to provide access to an Azure resource. In the case of Azure Storage, the resource ID may be specific to a single storage account, or it may apply to any storage account.
The following table describes the values that you can provide for the resource ID. The resource ID for Azure Storage is the same for all public and sovereign clouds:
||The service endpoint for a given storage account. Use this value to acquire a token for authorizing requests to that specific Azure Storage account and service only. Replace the value in brackets with the name of your storage account.|
||Use to acquire a token for authorizing requests to any Azure Storage account.|
Assign Azure roles for access rights
Azure Active Directory (Azure AD) authorizes access rights to secured resources through Azure RBAC. Azure Storage defines a set of built-in RBAC roles that encompass common sets of permissions used to access blob data. You can also define custom roles for access to blob data. To learn more about assigning Azure roles for blob access, see Assign an Azure role for access to blob data.
An Azure AD security principal may be a user, a group, an application service principal, or a managed identity for Azure resources. The RBAC roles that are assigned to a security principal determine the permissions that the principal has for the specified resource. To learn more about assigning Azure roles for blob access, see Assign an Azure role for access to blob data
In some cases you may need to enable fine-grained access to blob resources or to simplify permissions when you have a large number of role assignments for a storage resource. You can use Azure attribute-based access control (Azure ABAC) to configure conditions on role assignments. You can use conditions with a custom role or select built-in roles. For more information about configuring conditions for Azure storage resources with ABAC, see Authorize access to blobs using Azure role assignment conditions (preview). For details about supported conditions for blob data operations, see Actions and attributes for Azure role assignment conditions in Azure Storage (preview).
When you create an Azure Storage account, you are not automatically assigned permissions to access data via Azure AD. You must explicitly assign yourself an Azure role for access to Blob Storage. You can assign it at the level of your subscription, resource group, storage account, or container.
Before you assign an Azure RBAC role to a security principal, determine the scope of access that the security principal should have. Best practices dictate that it's always best to grant only the narrowest possible scope. Azure RBAC roles defined at a broader scope are inherited by the resources beneath them.
You can scope access to Azure blob resources at the following levels, beginning with the narrowest scope:
- An individual container. At this scope, a role assignment applies to all of the blobs in the container, and to the container properties and metadata.
- The storage account. At this scope, a role assignment applies to all containers and their blobs.
- The resource group. At this scope, a role assignment applies to all of the containers in all of the storage accounts in the resource group.
- The subscription. At this scope, a role assignment applies to all of the containers in all of the storage accounts in all of the resource groups in the subscription.
- A management group. At this scope, a role assignment applies to all of the containers in all of the storage accounts in all of the resource groups in all of the subscriptions in the management group.
For more information about scope for Azure RBAC role assignments, see Understand scope for Azure RBAC.
Azure built-in roles for blobs
Azure RBAC provides several built-in roles for authorizing access to blob data using Azure AD and OAuth. Some examples of roles that provide permissions to data resources in Azure Storage include:
- Storage Blob Data Owner: Use to set ownership and manage POSIX access control for Azure Data Lake Storage Gen2. For more information, see Access control in Azure Data Lake Storage Gen2.
- Storage Blob Data Contributor: Use to grant read/write/delete permissions to Blob storage resources.
- Storage Blob Data Reader: Use to grant read-only permissions to Blob storage resources.
- Storage Blob Delegator: Get a user delegation key to use to create a shared access signature that is signed with Azure AD credentials for a container or blob.
To learn how to assign an Azure built-in role to a security principal, see Assign an Azure role for access to blob data. To learn how to list Azure RBAC roles and their permissions, see List Azure role definitions.
For more information about how built-in roles are defined for Azure Storage, see Understand role definitions. For information about creating Azure custom roles, see Azure custom roles.
Only roles explicitly defined for data access permit a security principal to access blob data. Built-in roles such as Owner, Contributor, and Storage Account Contributor permit a security principal to manage a storage account, but don't provide access to the blob data within that account via Azure AD. However, if a role includes Microsoft.Storage/storageAccounts/listKeys/action, then a user to whom that role is assigned can access data in the storage account via Shared Key authorization with the account access keys. For more information, see Choose how to authorize access to blob data in the Azure portal.
For detailed information about Azure built-in roles for Azure Storage for both the data services and the management service, see the Storage section in Azure built-in roles for Azure RBAC. Additionally, for information about the different types of roles that provide permissions in Azure, see Azure roles, Azure AD roles, and classic subscription administrator roles.
Azure role assignments may take up to 30 minutes to propagate.
Access permissions for data operations
For details on the permissions required to call specific Blob service operations, see Permissions for calling data operations.
Access data with an Azure AD account
Access to blob data via the Azure portal, PowerShell, or Azure CLI can be authorized either by using the user's Azure AD account or by using the account access keys (Shared Key authorization).
Authorization with Shared Key is not recommended as it may be less secure. For optimal security, disable authorization via Shared Key for your storage account, as described in Prevent Shared Key authorization for an Azure Storage account.
Use of access keys and connection strings should be limited to initial proof of concept apps or development prototypes that don't access production or sensitive data. Otherwise, the token-based authentication classes available in the Azure SDK should always be preferred when authenticating to Azure resources.
Microsoft recommends that clients use either Azure AD or a shared access signature (SAS) to authorize access to data in Azure Storage. For more information, see Authorize operations for data access.
Data access from the Azure portal
The Azure portal can use either your Azure AD account or the account access keys to access blob data in an Azure storage account. Which authorization scheme the Azure portal uses depends on the Azure roles that are assigned to you.
When you attempt to access blob data, the Azure portal first checks whether you've been assigned an Azure role with Microsoft.Storage/storageAccounts/listkeys/action. If you've been assigned a role with this action, then the Azure portal uses the account key for accessing blob data via Shared Key authorization. If you haven't been assigned a role with this action, then the Azure portal attempts to access data using your Azure AD account.
To access blob data from the Azure portal using your Azure AD account, you need permissions to access blob data, and you also need permissions to navigate through the storage account resources in the Azure portal. The built-in roles provided by Azure Storage grant access to blob resources, but they don't grant permissions to storage account resources. For this reason, access to the portal also requires the assignment of an Azure Resource Manager role such as the Reader role, scoped to the level of the storage account or higher. The Reader role grants the most restricted permissions, but another Azure Resource Manager role that grants access to storage account management resources is also acceptable. To learn more about how to assign permissions to users for data access in the Azure portal with an Azure AD account, see Assign an Azure role for access to blob data.
The Azure portal indicates which authorization scheme is in use when you navigate to a container. For more information about data access in the portal, see Choose how to authorize access to blob data in the Azure portal.
Data access from PowerShell or Azure CLI
Azure CLI and PowerShell support signing in with Azure AD credentials. After you sign in, your session runs under those credentials. To learn more, see one of the following articles:
- Choose how to authorize access to blob data with Azure CLI
- Run PowerShell commands with Azure AD credentials to access blob data
Support for this feature might be impacted by enabling Data Lake Storage Gen2, Network File System (NFS) 3.0 protocol, or the SSH File Transfer Protocol (SFTP).
If you've enabled any of these capabilities, see Blob Storage feature support in Azure Storage accounts to assess support for this feature.
Authorizing blob data operations with Azure AD is supported only for REST API versions 2017-11-09 and later. For more information, see Versioning for the Azure Storage services.
Submit and view feedback for