Jaa

Get User Delegation Key

  • Artikkeli

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.

POST method request URI HTTP version
https://myaccount.blob.core.windows.net/?restype=service&comp=userdelegationkey HTTP/1.1

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:

POST method request URI HTTP version
http://127.0.0.1:10000/devstoreaccount1/?restype=service&comp=userdelegationkey HTTP/1.1

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.

Parameter Description
timeout Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for Blob Storage operations.

Request headers

The following table describes required and optional request headers.

Request header Description
Authorization Required. Specifies the authorization scheme. Only authorization with Microsoft Entra ID is supported. For more information, see Authorize with Microsoft Entra ID.
x-ms-version Required for all authorized requests. For more information, see Versioning for the Azure Storage services.
x-ms-client-request-id Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Blob Storage.

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:

Element Description
Start Required. The start time for the user delegation SAS, in ISO date format. It must be a valid date and time within seven days of the current date.
Expiry Required. The expiration time of the user delegation SAS, in ISO date format. It must be a valid date and time within seven days of the current date.

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 header Description
x-ms-request-id Uniquely identifies the request that was made and can be used to troubleshoot the request. For more information, see Troubleshoot API operations.
x-ms-version The Blob Storage version that was used to execute the request.
Date A UTC date/time value that's generated by the service, which indicates the time when the response was initiated.
x-ms-client-request-id Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header if it's present in the request and the value contains no more than 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it won't be present in the response.

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:

Element Description
SignedOid The immutable identifier for an object in the Microsoft identity system.
SignedTid A GUID that represents the Microsoft Entra tenant that the user is from.
SignedStart The start time of the user delegation key, in ISO date format.
SignedExpiry The expiration time of the user delegation key, in ISO date format.
SignedService The service that the user delegation key can be used for, where b represents Blob Storage.
SignedVersion The REST API version that's used to get the user delegation key.
Value The user delegation key.

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:

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:

Operation Storage account type Billing category
Get User Delegation Key Premium block blob
Standard general-purpose v2		 Other operations
Get User Delegation Key Standard general-purpose v1 Read operations

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

See also