Get User Delegation Key
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.
Get User Delegation Key as follows. HTTPS is required. Replace
myaccount with the name of your storage account.
|POST Method Request URI||HTTP Version|
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|
For more information, see Using the Azure Storage Emulator for Development and Testing.
The following additional parameters may be specified on the request URI.
The following table describes required and optional request headers.
||Required. Specifies the authorization scheme. Only authorization with Azure AD is supported. For more information, see Authorize with Azure Active Directory.|
||Required for all authorized requests. For more information, see Versioning for the Azure Storage Services.|
||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.|
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:
|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.|
The response includes an HTTP status code and a set of response headers.
A successful operation returns status code 200 (OK).
For information about status codes, see Status and Error Codes.
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.
||This header uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API Operations.|
||Indicates the version of the Blob service used to execute the request.|
||A UTC date/time value generated by the service that indicates the time at which the response was initiated.|
||This header can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the
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:
|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.|
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:
- Storage Account Contributor
- Storage Blob Data Contributor
- Storage Blob Data Owner
- Storage Blob Data Reader
- Storage Blob Delegator
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.
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.