Authorize with Azure Active Directory

Azure Storage provides integration with Azure Active Directory (Azure AD) for identity-based authorization of requests to the Blob and Queue services. With Azure AD, you can use role-based access control (RBAC) to grant access to blob and queue resources to users, groups, or applications. You can grant permissions that are scoped to the level of an individual container or queue.

To learn more about Azure AD integration in Azure Storage, see Authorize access to Azure blobs and queues using Azure Active Directory.

For more information on the advantages of using Azure AD in your application, see Integrating with Azure Active Directory.

Tip

Authorizing access to blob and queue data with Azure AD provides superior security and ease of use over other authorization options. When you use Azure AD to authorize requests make from your applications, you avoid having to store your account access key with your code, as you do with Shared Key authorization. While you can continue to use Shared Key authorization with your blob and queue applications, Microsoft recommends moving to Azure AD where possible. For more information about Azure AD integration in Azure Storage, see Authorize access to Azure blobs and queues using Azure Active Directory.

Use OAuth access tokens for authentication

Azure Storage accepts OAuth 2.0 access tokens from the Azure AD tenant associated with the subscription that contains the storage account. Azure Storage accepts access tokens for:

  • Users
  • Service principals
  • Managed service identities for Azure resources
  • Applications using permissions delegated by users

Azure Storage exposes a single delegation scope named user_impersonation that permits applications to take any action allowed by the user.

To request tokens for Azure Storage, specify the value https://storage.azure.com/ for the Resource ID.

For more information on requesting access tokens from Azure AD for users and service principals, see Authentication scenarios for Azure AD.

For more information about requesting access tokens for resources configured with managed identities, see How to use managed identities for Azure resources on an Azure VM to acquire an access token.

Call storage operations with OAuth tokens

To call Blob and Queue service operations using OAuth access tokens, pass the access token in the Authorization header using the Bearer scheme, and specify a service version of 2017-11-09 or higher, as shown in the following example:

Request:
GET /container/file.txt
x-ms-version: 2017-11-09
Authorization: Bearer eyJ0eXAiO...V09ccgQ
User-Agent: PostmanRuntime/7.6.0
Accept: */*
Host: sampleoautheast2.blob.core.windows.net
accept-encoding: gzip, deflate

Response:
HTTP/1.1 200
status: 200
Content-Length: 28
Content-Type: text/plain
Content-MD5: dxG7IgOBzApXPcGHxGg5SA==
Last-Modified: Wed, 30 Jan 2019 07:21:32 GMT
Accept-Ranges: bytes
ETag: "0x8D686838F9E8BA7"
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 09f31964-e01e-00a3-8066-d4e6c2000000
x-ms-version: 2017-11-09
x-ms-creation-time: Wed, 29 Aug 2018 04:22:47 GMT
x-ms-lease-status: unlocked
x-ms-lease-state: available
x-ms-blob-type: BlockBlob
x-ms-server-encrypted: true
Date: Wed, 06 Mar 2019 21:50:50 GMT
Welcome to Azure Storage!!

Bearer Challenge

Bearer challenge is part of the OAuth protocol RFC 6750 and is used for authority discovery. For anonymous requests, or requests with an invalid OAuth bearer token, the server will return status code 401 (Unauthorized) with identity provider and resource information. Refer to link for how to use these values during authentication with Azure AD.

Azure Storage Blob and Queue services return a bearer challenge for version 2019-12-12 and newer. Azure Data Lake Storage Gen2 returns a bearer challenge for version 2017-11-09 and newer.

The following is an example of a bearer challenge response when the client request does not include the bearer token in the anonymous download blob request:

Request:
GET /container/file.txt
x-ms-version: 2019-12-12
Host: sampleoautheast2.blob.core.windows.net

Response:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri=https://login.microsoftonline.com/<tenant_id>/oauth2/authorize resource_uri=https://storage.azure.com

<?xml version="1.0" encoding="utf-8"?>
<Error>
    <Code>NoAuthenticationInformation</Code>
    <Message>Server failed to authenticate the request. Please refer to the information in the www-authenticate header.
RequestId:ec4f02d7-1003-0006-21f9-c55bc8000000
Time:2020-01-08T08:01:46.2063459Z</Message>
</Error>
Parameter Description
authorization_uri The URI (physical endpoint) of the authorization server. This value is also used as a lookup key to get more information about the server from a discovery endpoint. The client must validate that the authorization server is trusted. When the resource is protected by Azure AD, it is sufficient to verify that the URL begins with https://login.microsoftonline.com or other hostname that Azure AD supports. A tenant-specific resource should always return a tenant-specific authorization URI.
resource_id Returns the unique identifier of the resource. The client application can use this identifier as the value of the resource parameter when it requests an access token for the resource. It is important for the client application to verify this value, otherwise a malicious service might be able to induce an elevation-of-privileges attack. The recommended strategy for preventing an attack is to verify that the resource_id matches the base of the web API URL that being accessed. https://storage.azure.com is the generally used Azure Storage resource ID.

Manage access rights with RBAC

Azure AD handles the authorization of access to secured resources through RBAC. Using RBAC, you can assign roles to users, groups, or service principals. Each role encompasses a set of permissions for a resource. Once the role is assigned to the user, group, or service principal, they have access to that resource. You can assign access rights using the Azure portal, Azure command-line tools, and Azure Management APIs. For more information on RBAC, see Get started with Role-Based Access Control.

For Azure Storage, you can grant access to data in a container or queue in the storage account. Azure Storage offers these built-in RBAC roles for use with Azure AD:

For more information about how built-in roles are defined for Azure Storage, see Understand role definitions for Azure resources.

You can also define custom roles for use with Blob storage and Azure Queues. For more information, see Create custom roles for Azure Role-Based Access Control.

Permissions for calling blob and queue data operations

The following tables describe the permissions necessary for an Azure AD user, group, or service principal to call specific Azure Storage operations. To enable a client to call a particular operation, ensure that the client's assigned RBAC role offers sufficient permissions for that operation.

Permissions for Blob service operations

Blob service operation RBAC action
List Containers Microsoft.Storage/storageAccounts/blobServices/containers/read (scoped to the storage account)
Set Blob Service Properties Microsoft.Storage/storageAccounts/blobServices/write
Get Blob Service Properties Microsoft.Storage/storageAccounts/blobServices/read
Preflight Blob Request Anonymous
Get Blob Service Stats Microsoft.Storage/storageAccounts/blobServices/read
Get User Delegation Key Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey
Create Container Microsoft.Storage/storageAccounts/blobServices/containers/write
Get Container Properties Microsoft.Storage/storageAccounts/blobServices/containers/read
Get Container Metadata Microsoft.Storage/storageAccounts/blobServices/containers/read
Set Container Metadata Microsoft.Storage/storageAccounts/blobServices/containers/write
Get Container ACL Not available via OAuth
Set Container ACL Not available via OAuth
Delete Container Microsoft.Storage/storageAccounts/blobServices/containers/delete
Lease Container Microsoft.Storage/storageAccounts/blobServices/containers/write
List Blobs Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read (scoped to container)
Put Blob For create or replace: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
To create new blob: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action
Get Blob Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Get Blob Properties Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Set Blob Properties Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Get Blob Metadata Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Set Blob Metadata Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Lease Blob Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Snapshot Blob Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write or
Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action
Copy Blob For destination blob: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write or Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action (when writing a new blob to the destination)
For source blob in the same storage account: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
For source blob in a different storage account: Available as anonymous, or include valid SAS token
Abort Copy Blob Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Delete Blob Microsoft.Storage/storageAccounts/blobServices/containers/blobs/delete
Put Block Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Put Block List Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Get Block List Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Put Page Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Get Page Ranges Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Incremental Copy Blob For destination blob: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
For source blob: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
For new blob: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action
Append Block Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write or Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action

Permissions for Queue service operations

Queue service operation RBAC action
List Queues Microsoft.Storage/storageAccounts/queueServices/queues/read (scoped storage account)
Set Queue Service Properties Microsoft.Storage/storageAccounts/queueServices/read
Get Queue Service Properties Microsoft.Storage/storageAccounts/queueServices/read
Preflight Queue Request Anonymous
Get Queue Service Stats Microsoft.Storage/storageAccounts/queueServices/read
Create Queue Microsoft.Storage/storageAccounts/queueServices/queues/write
Delete Queue Microsoft.Storage/storageAccounts/queueServices/queues/delete
Get Queue Metadata Microsoft.Storage/storageAccounts/queueServices/queues/read
Set Queue Metadata Microsoft.Storage/storageAccounts/queueServices/queues/write
Get Queue ACL Not available via OAuth
Set Queue ACL Not available via OAuth
Put Message Microsoft.Storage/storageAccounts/queueServices/queues/messages/add/action or Microsoft.Storage/storageAccounts/queueServices/queues/messages/write
Get Messages Microsoft.Storage/storageAccounts/queueServices/queues/messages/process/action or (Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete and Microsoft.Storage/storageAccounts/queueServices/queues/messages/read)
Peek Messages Microsoft.Storage/storageAccounts/queueServices/queues/messages/read
Delete Message Microsoft.Storage/storageAccounts/queueServices/queues/messages/process/action or Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete
Clear Messages Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete
Update Message Microsoft.Storage/storageAccounts/queueServices/queues/messages/write

See also