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 resources in the Blob service using Azure Active Directory (Azure AD) 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 URI

When making a request against the local storage service, specify the local hostname and Blob service 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 Using the Azure Storage Emulator for Development and Testing.

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 Setting Timeouts for Blob Service Operations.

Request Headers

The following table describes required and optional request headers.

Request Header Description
Authorization Required. Specifies the authorization scheme. Only authorization with Azure AD is supported. For more information, see Authorize with Azure Active Directory.
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 KB character limit that is recorded in the analytics logs when storage analytics logging is enabled. Using this header is highly recommended for correlating client-side activities with requests received by the server. For more information, see About Storage Analytics Logging and Azure Logging: Using Logs to Track Storage Requests.

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 following table describes the elements of the request body:

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

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 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 This header uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API Operations.
x-ms-version Indicates the version of the Blob service used to execute the request.
Date A UTC date/time value generated by the service that indicates the time at which the response was initiated.
x-ms-client-request-id This header 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 is present in the request and the value is at most 1024 visible ASCII characters. If the x-ms-client-request-id header is not present in the request, this header will not 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 key signature</Value>
</UserDelegationKey>

The following table describes the elements of the response body:

Element Name Description
SignedOid The immutable identifier for an object in the Microsoft identity system.
SignedTid A GUID that represents the Azure AD tenant that the user is from.
SignedStart The start time of the user delegation key, in ISO date format.
SignedExpiry The expiry time of the user delegation key, in ISO date format.
SignedService The service of the user delegation key can be used for, b represents Blob service.
SignedVersion The rest api version used to get user delegation key.
Value The signature of the user delegation key.

Authorization

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

To request the user delegation key, a security principal must be assigned the Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey action. The following built-in RBAC roles include the Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey action, either explicitly or as part of a wildcard definition:

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 built-in roles listed above, 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.

In the case where 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 returned on the response to the Get User Delegation Key in the user delegation SAS token. For more information about creating a user delegation SAS, see Create a user delegation SAS (preview).

The user delegation key cannot be used to access resources in the Blob service directly.

See also