Using a Shared Access Signature (REST API)

To construct the signature string of a Shared Access Signature, first construct the string-to-sign from the fields comprising the request, then encode the string as UTF-8 and compute the signature using the HMAC-SHA256 algorithm. Note that fields included in the string-to-sign must be URL-decoded.

To construct the string-to-sign, use the following format:

StringToSign = signedpermissions + "\n"
               signedstart + "\n"
               signedexpiry + "\n"
               canonicalizedresource + "\n"
               signedidentifier

When constructing the string to be signed, keep in mind the following:

• If a field is optional and not provided as part of the request, specify an empty string for that field. Be sure to include the newline character (\n) after the empty string.
  
  
• The signedpermission portion of the string must include the permission designations in the following order: rwdl. Any combination of these permissions is acceptable, so long as they are in the specified order. For example, valid permissions settings include rw, rd, rl, wd, wl, and rl. Invalid settings include wr, dr, lr, and dw. Specifying a permission designation more than once is not permitted.
  
  
• The canonicalizedresouce portion of the string is a canonical path to the signed resource. It must include the storage account name, the container name, and the blob name, and must be URL-decoded. The following examples show how to construct the canonicalizedresource portion of the string.
  
  If the signed resource is a container:
  
  
  Copy

  URL = http://myaccount.blob.core.windows.net/music
  canonicalizedresource = "/myaccount/music"
  

  If the signed resource is a blob:
  
  
  Copy

  URL = http://myaccount.blob.core.windows.net/music/intro.mp3
  canonicalizedresource = "/myaccount/music/intro.mp3"
  
  

• Provide a value for the signedidentifier portion of the string if you are associating the request with a container-level access policy.
  
  

To establish a container-level access policy, call the Set Container ACL (REST API) operation with a request body that specifies the terms of the access policy. The body of the request includes a unique signed identifier that may be up to 64 characters in length, and the optional parameters of the access policy, as follows:

<?xml version="1.0" encoding="utf-8"?>
<SignedIdentifiers>
  <SignedIdentifier> 
    <Id>unique-64-char-value</Id>
    <AccessPolicy>
      <Start>start-time</Start>
      <Expiry>expiry-time</Expiry>
      <Permission>abbreviated-permission-list</Permission>
    </AccessPolicy>
  </SignedIdentifier>
</SignedIdentifiers>

You can retrieve the container-level access policy by calling Get Container ACL (REST API).

A maximum of five access policies may be set on a container at any given time. Each SignedIdentifier field, with its unique Id field, corresponds to one access policy. Attempting to set more than five access policies at one time results in the service returning status code 400 (Bad Request).

To modify the parameters of the container-level access policy, you can call Set Container ACL (REST API) to replace the existing policy, specifying a new start time, expiry time, or set of permissions. For example, if your existing policy grants read and write permissions to a resource, you can modify it to grant only read permissions for all future requests. In this case, the signed identifier of the new policy, as specified by the ID field, would be identical to the signed identifier of the policy you are replacing.

To revoke a container-level access policy, you can replace the existing container-level access policy with a policy with a new signed identifier. Changing the signed identifier breaks the associations between any existing signatures and the container-level access policy.

To remove a single access policy, call Set Container ACL, passing in the set of signed identifiers that you wish to maintain on the container. To remove all access policies from the container, call Set Container ACL with an empty request body.

Following are some examples that demonstrate Shared Access Signatures for REST operations.

Example: GET Operation

---

The following example shows how to construct a Shared Access Signature for read access on a container.

The signed signature fields that will comprise the URL include:

Copy

signedstart=2009-02-09
signedexpiry=2009-02-10
signedresource=c
signedpermissions=r
signature=dD80ihBh5jfNpymO5Hg1IdiJIEvHcJpCMiCMnN/RnbI=
signedidentifier=YWJjZGVmZw==

The signature is constructed as follows:

Copy

StringToSign = r + \n 
               2009-02-09 + \n
               2009-02-10 + \n
               /myaccount/pictures + \n
               YWJjZGVmZw==

HMAC-SHA256(URL.Decode(UTF8.Encode(StringToSign))) = dD80ihBh5jfNpymO5Hg1IdiJIEvHcJpCMiCMnN/RnbI=

The request URL specifies read permissions on the pictures container for the designated interval. Note that the resource represented by the request URL is a blob, but the Shared Access Signature is specified on the container. It's also possible to specify it on the blob itself.

Copy

GET http://myaccount.blob.core.windows.net/pictures/profile.jpg? st=2009-02-09&se=2009-02-10 &sr=c&sp=r&si=YWJjZGVmZw%3d%3d&sig= dD80ihBh5jfNpymO5Hg1IdiJIEvHcJpCMiCMnN%2fRnbI%3d HTTP/1.1
Host: myaccount.blob.core.windows.net

With this signature, Get Blob will be executed if the following criteria are met:

• The request against the storage account is properly authenticated using the Shared Access Signature.
  
  
• The request is made within the time frame specified by the Shared Access Signature.
  
  
• The request does not violate an associated container-level access policy.
  
  
• The blob specified by the request (/myaccount/pictures/profile.jpg) resides within the container specified as the signed resource (/myaccount/pictures).
  
  

Example: PUT Operation

---

The following example shows how to construct a Shared Access Signature for writing a blob.

The signed signature fields that will comprise the URL include:

Copy

signedstart=2009-02-09T08:49Z
signedexpiry=2009-02-10T08:49Z
signedresource=c
signedpermissions=w
signature= Rcp6gQRfV7WDlURdVTqCa+qEArnfJxDgE+KH3TCChIs=
signedidentifier=YWJjZGVmZw==

The signature is constructed as follows:

Copy

StringToSign = w + \n 
               2009-02-09T08:49Z + \n
               2009-02-10T08:49Z + \n
               /myaccount/pictures + \n
               YWJjZGVmZw==

HMAC-SHA256(URL.Decode(UTF8.Encode(StringToSign))) = Rcp6gQRfV7WDlURdVTqCa+qEArnfJxDgE+KH3TCChIs=

The request URL specifies write permissions on the pictures container for the designated interval. Note that the resource represented by the request URL is a blob, but the Shared Access Signature is specified on the container. It's also possible to specify it on the blob itself.

Copy

PUT http://myaccount.blob.core.windows.net/pictures/photo.jpg?st=2009-02-09T08%3a49Z&se=2009-02-10T08%3a49Z&
sr=c&sp=w&si=YWJjZGVmZw%3d%3d&sig= Rcp6gQRfV7WDlURdVTqCa%2bqEArnfJxDgE%2bKH3TCChIs%3d HTTP/1.1
Host: myaccount.blob.core.windows.net
Content-Length: 12

Hello World.

With this signature, Put Blob will be called if the following criteria are met:

• The request against the storage account is properly authenticated.
  
  
• The request is made within the time frame specified by the Shared Access Signature.
  
  
• The request does not violate an associated container-level access policy.
  
  
• The blob specified by the request (/myaccount/pictures/photo.jpg) can be created or updated within the container specified as the signed resource (/myaccount/pictures).
  
  

Example: DELETE operation

---

The following example shows how to construct a Shared Access Signature for deleting a blob.

Note that a Shared Access Signature for a DELETE operation should be distributed judiciously, as permitting a client to delete data may have unintended consequences.

The signed signature fields that will comprise the URL include:

Copy

signedstart=2009-02-09T08:49:37.0000000Z
signedexpiry=2009-02-10T08:49:37.0000000Z
signedresource=c
signedpermissions=d
signature= +SzBm0wi8xECuGkKw97wnkSZ/62sxU+6Hq6a7qojIVE=
signedidentifier=YWJjZGVmZw==

The signature is constructed as follows:

Copy

StringToSign = d + \n 
               2009-02-09T08:49:37.0000000Z + \n
               2009-02-10T08:49:37.0000000Z + \n
               /myaccount/pictures + \n
               YWJjZGVmZw==

HMAC-SHA256(URL.Decode(UTF8.Encode(StringToSign))) = +SzBm0wi8xECuGkKw97wnkSZ/62sxU+6Hq6a7qojIVE=

The request URL specifies delete permissions on the pictures container for the designated interval. Note that the resource represented by the request URL is a blob, but the Shared Access Signature is specified on the container. It's also possible to specify it on the blob itself.

Copy

DELETE http://myaccount.blob.core.windows.net/pictures/profile.jpg?st=2009-02-09T08%3a49%3a37.0000000Z&se=2009-02-10T08%3a49%3a37.0000000Z&sr=c&sp=d&si=YWJjZGVmZw%3d%3d&sig= %2bSzBm0wi8xECuGkKw97wnkSZ%2f62sxU%2b6Hq6a7qojIVE%3d HTTP/1.1
Host: myaccount.blob.core.windows.net
Content-Length: 0

With this signature, Delete Blob will be called if the following criteria are met:

• The request against the storage account is properly authenticated.
  
  
• The request is made within the time frame specified by the Shared Access Signature.
  
  
• The request does not violate an associated container-level access policy.
  
  
• The blob specified by the request (/myaccount/pictures/profile.jpg) resides within the container specified as the signed resource (/myaccount/pictures).