Get User Delegation Key

The Get User Delegation Key operation gets a key that can be used to sign a user delegation SAS (shared access signature). A user delegation SAS grants access to Azure Blob Storage resources by using Microsoft Entra credentials. The Get User Delegation Key operation is available in version 2018-11-09 and later.

Request

Construct the Get User Delegation Key as follows. HTTPS is required. Replace myaccount with the name of your storage account.

Emulated storage service request

When you're making a request against the local storage service, specify the local hostname and Blob Storage port as 127.0.0.1:10000, followed by the local storage account name:

For more information, see Use the Azurite emulator for local Azure Storage development.

URI parameters

The following additional parameters may be specified on the request URI.

Request headers

The following table describes required and optional request headers.

Request body

The format of the request body is as follows:

<?xml version="1.0" encoding="utf-8"?>  
<KeyInfo>  
    <Start>String, formatted ISO Date</Start>
    <Expiry>String, formatted ISO Date </Expiry>
</KeyInfo>  

The elements of the request body are described in the following table:

Response

The response includes an HTTP status code and a set of response headers.

Status code

A successful operation returns status code 200 (OK).

For more information about status codes, see Status and error codes.

Response headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response body

The format of the response body is as follows:

<?xml version="1.0" encoding="utf-8"?>
<UserDelegationKey>
    <SignedOid>String containing a GUID value</SignedOid>
    <SignedTid>String containing a GUID value</SignedTid>
    <SignedStart>String formatted as ISO date</SignedStart>
    <SignedExpiry>String formatted as ISO date</SignedExpiry>
    <SignedService>b</SignedService>
    <SignedVersion>String specifying REST api version to use to create the user delegation key</SignedVersion>
    <Value>String containing the user delegation key</Value>
</UserDelegationKey>

The elements of the response body are described in the following table:

Authorization

Authorization is required when calling any data access operation in Azure Storage. You can only authorize the Get User Delegation Key operation using Microsoft Entra ID.

Permissions

The security principal that requests the user delegation key needs to have the appropriate permissions to do so. A Microsoft Entra security principal may be a user, a group, a service principal, or a managed identity.

Listed below are the RBAC action necessary for a Microsoft Entra security principal to call the Get User Delegation Key operation, and the least privileged built-in Azure RBAC role that includes this action:

• Azure RBAC action: Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action
• Least privileged built-in role: Storage Blob Delegator

Any built-in role that includes this Azure RBAC action, either explicitly or as part of a wildcard definition, is permitted to call the Get User Delegation Key operation.

To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.

Because the Get User Delegation Key operation acts at the level of the storage account, the Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey action must be scoped at the level of the storage account, the resource group, or the subscription. If the security principal is assigned any of the previously listed built-in roles, or a custom role that includes the Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey action, at the level of the storage account, the resource group, or the subscription, the security principal will be able to request the user delegation key.

If the security principal is assigned a role that permits data access but is scoped to the level of a container, you can additionally assign the Storage Blob Delegator role to that security principal at the level of the storage account, resource group, or subscription. The Storage Blob Delegator role grants the security principal permissions to request the user delegation key.

For more information about RBAC roles for Azure Storage, see Authorize with Azure Active Directory.

Remarks

Use the user delegation key to create a user delegation SAS. Include the fields that are returned on the response to the Get User Delegation Key in the user delegation SAS token. For more information, see Create a user delegation SAS.

The user delegation key can't be used to access Blob Storage resources directly.

Billing

Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API, or from an Azure Storage client library. These requests accrue charges per transaction. The type of transaction affects how the account is charged. For example, read transactions accrue to a different billing category than write transactions. The following table shows the billing category for Get User Delegation Key requests based on the storage account type:

To learn about pricing for the specified billing category, see Azure Blob Storage Pricing.

See also

• Authorize requests to Azure Storage
• Create a user delegation SAS