Use PowerShell to assign an Azure role for access to blob and queue data

Azure Active Directory (Azure AD) authorizes access rights to secured resources through Azure role-based access control (Azure RBAC). Azure Storage defines a set of Azure built-in roles that encompass common sets of permissions used to access containers or queues.

When an Azure role is assigned to an Azure AD security principal, Azure grants access to those resources for that security principal. Access can be scoped to the level of the subscription, the resource group, the storage account, or an individual container or queue. An Azure AD security principal may be a user, a group, an application service principal, or a managed identity for Azure resources.

This article describes how to use Azure PowerShell to list Azure built-in roles and assign them to users. For more information about using Azure PowerShell, see Overview of Azure PowerShell.

Note

This article has been updated to use the Azure Az PowerShell module. The Az PowerShell module is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Azure roles for blobs and queues

Azure provides the following Azure built-in roles for authorizing access to blob and queue data using Azure AD and OAuth:

Only roles explicitly defined for data access permit a security principal to access blob or queue data. Built-in roles such as Owner, Contributor, and Storage Account Contributor permit a security principal to manage a storage account, but do not provide access to the blob or queue 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 Use the Azure portal to access blob or queue data.

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 Classic subscription administrator roles, Azure roles, and Azure AD roles.

Important

Azure role assignments may take up to 30 minutes to propagate.

Determine resource scope

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.

The following list describes the levels at which you can scope access to Azure blob and queue resources, starting with the narrowest scope:

  • An individual container. At this scope, a role assignment applies to all of the blobs in the container, as well as container properties and metadata.
  • An individual queue. At this scope, a role assignment applies to messages in the queue, as well as queue properties and metadata.
  • The storage account. At this scope, a role assignment applies to all containers and their blobs, or to all queues and their messages.
  • The resource group. At this scope, a role assignment applies to all of the containers or queues in all of the storage accounts in the resource group.
  • The subscription. At this scope, a role assignment applies to all of the containers or queues 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 or queues 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 Azure role assignments and scope, see What is Azure role-based access control (Azure RBAC)?.

List available Azure roles

To list available Azure built-in roles with Azure PowerShell, use the Get-AzRoleDefinition command:

Get-AzRoleDefinition | FT Name, Description

You'll see the built-in Azure Storage data roles listed, together with other built-in roles for Azure:

Storage Blob Data Contributor             Allows for read, write and delete access to Azure Storage blob containers and data
Storage Blob Data Owner                   Allows for full access to Azure Storage blob containers and data, including assigning POSIX access control.
Storage Blob Data Reader                  Allows for read access to Azure Storage blob containers and data
Storage Queue Data Contributor            Allows for read, write, and delete access to Azure Storage queues and queue messages
Storage Queue Data Message Processor      Allows for peek, receive, and delete access to Azure Storage queue messages
Storage Queue Data Message Sender         Allows for sending of Azure Storage queue messages
Storage Queue Data Reader                 Allows for read access to Azure Storage queues and queue messages

Assign an Azure role to a security principal

To assign an Azure role to a security principal, use the New-AzRoleAssignment command. The format of the command can differ based on the scope of the assignment. In order to run the command, you need to have Owner or Contributor role assigned at the corresponding scope. The following examples show how to assign a role to a user at various scopes, but you can use the same command to assign a role to any security principal.

Important

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 RBAC role for data access. You can assign it at the level of your subscription, resource group, storage account, or container or queue.

If the storage account is locked with an Azure Resource Manager read-only lock, then the lock prevents the assignment of Azure RBAC roles that are scoped to the storage account or to a data container (blob container or queue).

Container scope

To assign a role scoped to a container, specify a string containing the scope of the container for the --scope parameter. The scope for a container is in the form:

/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/blobServices/default/containers/<container-name>

The following example assigns the Storage Blob Data Contributor role to a user, scoped to a container named sample-container. Make sure to replace the sample values and the placeholder values in brackets with your own values:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/sample-resource-group/providers/Microsoft.Storage/storageAccounts/<storage-account>/blobServices/default/containers/sample-container"

Queue scope

To assign a role scoped to a queue, specify a string containing the scope of the queue for the --scope parameter. The scope for a queue is in the form:

/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/queueServices/default/queues/<queue-name>

The following example assigns the Storage Queue Data Contributor role to a user, scoped to a queue named sample-queue. Make sure to replace the sample values and the placeholder values in brackets with your own values:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/sample-resource-group/providers/Microsoft.Storage/storageAccounts/<storage-account>/queueServices/default/queues/sample-queue"

Storage account scope

To assign a role scoped to the storage account, specify the scope of the storage account resource for the --scope parameter. The scope for a storage account is in the form:

/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>

The following example shows how to scope the Storage Blob Data Reader role to a user at the level of the storage account. Make sure to replace the sample values with your own values:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Storage Blob Data Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/sample-resource-group/providers/Microsoft.Storage/storageAccounts/<storage-account>"

Resource group scope

To assign a role scoped to the resource group, specify the resource group name or ID for the --resource-group parameter. The following example assigns the Storage Queue Data Reader role to a user at the level of the resource group. Make sure to replace the sample values and placeholder values in brackets with your own values:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Storage Queue Data Reader" `
    -ResourceGroupName "sample-resource-group"

Subscription scope

To assign a role scoped to the subscription, specify the scope for the subscription for the --scope parameter. The scope for a subscription is in the form:

/subscriptions/<subscription>

The following example shows how to assign the Storage Blob Data Reader role to a user at the level of the storage account. Make sure to replace the sample values with your own values:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Storage Blob Data Reader" `
    -Scope  "/subscriptions/<subscription>"

Next steps