Export (0) Print
Expand All
0 out of 7 rated this helpful - Rate this topic

Constructing the Shared Access Signature URI (REST API)

Updated: April 3, 2014

The URI for a shared access signature includes components that specify the resource to make accessible, the interval over which the shared access signature is valid, the permissions associated with the signature, an optional access policy identifier associated with the request, and the signature itself. The following figure represents the parts of the shared access signature URI. Required parts appear in orange. The parts of the URI are described in the subsequent sections.

Parameter elements of a SAS URL

The signedversion field contains the service version of the shared access signature. This value specifies the version of shared access authentication used by this shared access signature (in the signature field), and also specifies the service version of requests made with this shared access signature. See Delegating Access with a Shared Access Signature (REST API) to learn how this parameter affects authentication of requests made with a shared access signature.

 

Field name Query parameter Description

signedversion

sv

Required and only allowed in versions 2012-02-12 and newer. The storage service version of shared access signature authentication to use, and the service version to use when handling requests made with this shared access signature.

In legacy scenarios where signedversion is not used, the Blob service applies rules to determine the version. See Versioning for the Blob, Queue, and Table Services in Azure for more information about these rules.

ImportantImportant
Client software might experience unexpected protocol behavior when using a shared access signature URI that uses a storage service version that is newer than the client software. Code that constructs shared access signature URIs should rely on versions that are understood by client software that makes storage service requests.

The signedresource field specifies which resources are accessible via the shared access signature. The following table describes how to refer to a blob or container resource on the URI.

 

Field name Query parameter Description

signedresource

sr

Required.

Specify b if the shared resource is a blob. This grants access to the content and metadata of the blob.

Specify c if the shared resource is a container. This grants access to the content and metadata of any blob in the container, and to the list of blobs in the container.

To define values for certain response headers to be returned when the shared access signature is used in a request, you can specify response headers in query parameters. This feature is supported beginning with version 2013-08-15; shared access signatures using this feature must include the sv parameter set to 2013-08-15.

The response headers and corresponding query parameters are as follows:

 

Response header name Corresponding SAS query parameter

Cache-Control

rscc

Content-Disposition

rscd

Content-Encoding

rsce

Content-Language

rscl

Content-Type

rsct

For example, if you specify the rsct=binary query parameter on a shared access signature created with version 2013-08-15, the Content-Type response header is set to binary. This value overrides the Content-Type header value stored for the blob for a request using this shared access signature only.

Note that if you create a shared access signature that specifies response headers as query parameters, you must include those in the string-to-sign that is used to construct the signature string. See the Constructing the Signature String section below for details, and Examples of Shared Access Signatures (REST API) for additional examples.

The tablename field specifies the name of the table to share.

 

Field name Query parameter Description

tablename

tn

Required. The name of the table to share.

The access policy portion of the URI indicates the period of time over which the shared access signature is valid and the permissions to be granted to the user. The parts of the URI described in the following table comprise the access policy.

 

Field name Query parameter Description

signedstart

st

Optional. The time at which the shared access signature becomes valid, in an ISO 8061 format. If omitted, start time for this call is assumed to be the time when the storage service receives the request.

In versions before 2012-02-12, the duration between signedstart and signedexpiry cannot exceed one hour unless a container policy is used.

signedexpiry

se

Required. The time at which the shared access signature becomes invalid, in an ISO 8061 format. This field must be omitted if it has been specified in an associated stored access policy. For details, see Lifetime and Revocation of a shared access signature.

signedpermissions

sp

Required. The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. This field must be omitted if it has been specified in an associated stored access policy.

startpk

startrk

spk

srk

Table service only.

Optional, but startpk must accompany startrk. The minimum partition and row keys accessible with this shared access signature. Key values are inclusive. If omitted, there is no lower bound on the table entities that can be accessed.

endpk

endrk

epk

erk

Table service only.

Optional, but endpk must accompany endrk. The maximum partition and row keys accessible with this shared access signature. Key values are inclusive. If omitted, there is no upper bound on the table entities that can be accessed.

The signedpermissions field is required on the URI unless it is specified as part of a stored access policy. The startpk, startrk, endpk, and endrk fields can only be specified on a table resource.

The signedstart and signedexpiry fields must be expressed as UTC times and must adhere to a valid ISO 8061 format. Supported ISO 8061 formats include the following:

  • YYYY-MM-DD

  • YYYY-MM-DDThh:mmTZD

  • YYYY-MM-DDThh:mm:ssTZD

For the date portion of these formats, YYYY is a four-digit year representation, MM is a two-digit month representation, and DD is a two-digit day representation. For the time portion, hh is the hour representation in 24-hour notation, mm is the two-digit minute representation, and ss is the two-digit second representation. A time designator T separates the date and time portions of the string, while a time zone designator TZD specifies a time zone.

The permissions specified on the shared access signature URI indicate which operations are permitted on the shared resource. The following tables show the permissions supported by each resource type.

Permissions for a blob

 

Permission URI symbol Allowed operations

Read

r

Read the content, properties, metadata and block list. Use the blob as the source of a copy operation.

Write

w

Create or write content, properties, metadata, or block list. Snapshot or lease the blob. Resize the blob (page blob only). Use the blob as the destination of a copy operation within the same account.

Delete

d

Delete the blob.

Permissions for a container

 

Permission URI symbol Allowed operations

Read

r

Read the content, properties, metadata or block list of any blob in the container. Use any blob in the container as the source of a copy operation.

Write

w

For any blob in the container, create or write content, properties, metadata, or block list. Snapshot or lease the blob. Resize the blob (page blob only). Use the blob as the destination of a copy operation within the same account.

noteNote
You cannot grant permissions to read or write container properties or metadata, nor to lease a container.

Delete

d

Delete any blob in the container.

noteNote
You cannot grant permissions to delete a container.

List

l

List blobs in the container.

Permissions for a queue

 

Permission URI symbol Allowed operations

Read

r

Read metadata and properties, including message count. Peek at messages.

Add

a

Add messages to the queue.

Update

u

Update messages in the queue.

noteNote
Use the Process permission with Update so you can first get the message you want to update.

Process

p

Get and delete messages from the queue.

Permissions for a table

 

Permission URI symbol Allowed operations

Query

r (for read)

Get entities and query entities.

Add

a

Add entities.

noteNote
Add and Update permissions are required for upsert operations.

Update

u

Update entities.

noteNote
Add and Update permissions are required for upsert operations.

Delete

d

Delete entities.

Specify permissions by combining URI symbols in the signedpermissions field of your SAS URI. Permissions can be grouped to allow multiple operations to be performed with the given signature. You must include permissions in the order that they appear in the table for the resource type. For example, to grant all permissions to a container, the URI must specify sp=rwdl. To grant only read/write permissions, the URI must specify sp=rw.

Shared access signatures cannot grant access to some operations:

  • Containers, queues, and tables cannot be created, deleted, or listed.

  • Container metadata and properties cannot be read or written.

  • Queues cannot be cleared and their metadata may not be written.

  • Containers cannot be leased.

ImportantImportant
Shared access signature URIs are keys that grant permissions to storage resources, and should be protected in the same manner as a shared key. Operations that use shared access signature URIs should only be performed over an HTTPS connection, and shared access signature URIs should only be distributed on a secure connection such as HTTPS.

The startpk, startrk, endpk, and endrk fields define a range of table entities associated with a shared access signature. Table queries will only return results that are within the range, and attempts to use the shared access signature to add, update, or delete entities outside this range will fail. If startpk equals endpk, the shared access signature only authorizes access to entities in one partition in the table. If startpk equals endpk and startrk equals endrk, the shared access signature can only access one entity in one partition. Use the following table to understand how these fields constrain access to entities in a table.

 

Fields present Scope of constraint

startpk

partitionKey >= startpk

endpk

partitionKey <= endpk

startpk, startrk

(partitionKey > startpk) || (partitionKey == startpk && rowKey >= startrk)

endpk, endrk

(partitionKey < endpk) || (partitionKey == endpk && rowKey <= endrk)

Specifying the signedidentifier field on the URI relates the given shared access signature to a corresponding stored access policy. A stored access policy provides an additional measure of control over one or more shared access signatures, including the ability to revoke the signature if needed. Each container, queue, or table can have up to 5 stored access policies.

The following table describes how to refer to a signed identifier on the URI.

 

Field name Query parameter Description

signedidentifier

si

Optional. A unique value up to 64 characters in length that correlates to an access policy specified for the container, queue, or table.

A stored access policy includes a signed identifier, a value up to 64 characters long that is unique within the resource. The value of this signed identifier can be specified for the signedidentifier field in the URI for the shared access signature. Specifying a signed identifier on the URI associates the signature with the stored access policy. To establish a container-level access policy using the REST API, see Delegating Access with a Shared Access Signature (REST API).

Shared access signatures grant users access rights to storage account resources. When planning to use a shared access signature, think about the lifetime of the signature and whether your application may need to revoke access rights under certain circumstances.

One way that you can manage a shared access signature is to control its lifetime by setting the signedexpiry field of the access policy. If you want to continue to grant a client access to the resource after the expiry time, you must issue a new signature. It’s recommended that you keep the lifetime of a shared access signature short. Before version 2012-02-12, a shared access signature not associated with a stored access policy could not have an active period that exceeded one hour.

Another way to manage a shared access signature is to associate the signature with a stored access policy. The stored access policy is represented by the signedidentifier field on the URI. A stored access policy provides an additional measure of control over one or more shared access signatures, including the ability to revoke the signature if needed.

To revoke a shared access signature that is tied to a stored access policy, you can remove the stored access policy. If the storage service cannot locate the stored access policy specified in the shared access signature, the client will not be able to access the resource indicated by the URI.

To revoke a Shared Access signature that is not tied to a stored access policy, you must change the shared key on the storage account that was used to create the signature.

Best practices recommend that a shared access signature be used together with a signed identifier that references a stored access policy, or, if no signed identifier is specified, that the interval over which the signature is valid be kept short. For more information on associating a signature with a stored access policy, see Use a Stored Access Policy.

noteNote
The access policy for a shared access signature consists of the start time, expiry time, and permissions for the signature. You can specify all of these parameters on the signature URI and none within the stored access policy; all on the container and none on the URI; or some combination of the two. However, you cannot specify a given parameter on both the signature URI and the stored access policy. See Use a Stored Access Policy for more information.

The signature part of the URI is used to authenticate the request made with the shared access signature. The Blob service uses a Shared Key authentication scheme to authenticate the shared access signature. The following table describes how to specify the signature on the URI.

 

Field name Query parameter Description

signature

sig

The string-to-sign is a unique string constructed from the fields that must be verified in order to authenticate the request. The signature is an HMAC computed over the string-to-sign and key using the SHA256 algorithm, and then encoded using Base64 encoding.

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.

Versions Prior to 2012-02-12

To construct the string-to-sign for Blob service resources for versions prior to 2012-02-12, use the following format:


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

Version 2012-02-12

To construct the string-to-sign for Blob service resources for version 2012-02-12, use the following format:


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

Version 2013-08-15

To construct the string-to-sign for Blob service resources using the 2013-08-15 version or later, use the following format:

StringToSign = signedpermissions + "\n"
               signedstart + "\n"
               signedexpiry + "\n"
               canonicalizedresource + "\n"
               signedidentifier + "\n"
               signedversion + "\n"
               rscc + "\n"
               rscd + "\n"
               rsce + "\n"
               rscl + "\n"
               rsct

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


TableStringToSign = StringToSign + "\n"
                    startpk + "\n"
                    startrk + "\n"
                    endpk + "\n"
                    endrk

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.

  • String-to-sign for a table must include the additional parameters, even if they are empty strings.

  • The signedpermission portion of the string must include the permission designations in a fixed order that is specific to each resource type. Any combination of these permissions is acceptable, but the order of permission letters must match the order in the following table.

     

    Resource type Ordering of permissions

    blob

    rwd

    container

    rwdl

    queue

    raup

    table

    raud

    For example, valid permissions settings for a container 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 and the resource name, and must be URL-decoded. Names of blobs must include the blob’s container. Table names must be lower-case. The following examples show how to construct the canonicalizedresource portion of the string.

    If the signed resource is a container:

    URL = https://myaccount.blob.core.windows.net/music
    canonicalizedresource = "/myaccount/music"
    
    If the signed resource is a blob:

    URL = https://myaccount.blob.core.windows.net/music/intro.mp3
    canonicalizedresource = "/myaccount/music/intro.mp3"
    
    
    If the signed resource is a queue:

    URL = https://myaccount.queue.core.windows.net/thumbnails
    canonicalizedresource = "/myaccount/thumbnails"
    
    
    If the signed resource is a table, assure the table name is lower-case in the canonicalized format:

    URL = https://myaccount.table.core.windows.net/Employees(PartitionKey='Jeff',RowKey='Price')
    canonicalizedresource = "/myaccount/employees"
    
    
  • Provide a value for the signedidentifier portion of the string if you are associating the request with a stored access policy.

  • A shared access signature that specifies a storage service version before 2012-02-12 can only share a blob or container, and must omit signedversion and the newline before it.

See Also

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.