Create a Shared Access Signature

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 Use a Shared Access Signature (REST API) to learn how this parameter affects authentication of requests made with a Shared Access Signature.

Determining version of a Shared Access Signature request

In legacy scenarios where signedversion is not used, the Blobs service applies rules to determine version. See these rules in Versioning for the Blob, Queue, and Table services in Windows Azure.

Important
Client software might experience unexpected protocol behavior when using a Shared Access Signature URL that uses a storage service version that is newer than the client software. Code that constructs Shared Access Signature URLs 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 URL.

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

The access policy portion of the URL 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 URL described in the following table comprise the access policy.

The signedpermissions field is required on the URL 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 URL indicate which operations are permitted on the shared resource. The following tables show the permissions supported by each resource type.

Permissions for a blob

Permissions for a container

Permission	URL 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). Note You cannot grant permissions to read or write container properties or metadata.
Delete	d	Delete any blob in the container. Note You cannot grant permissions to delete a container.
List	l	List blobs in the container.

Permissions for a queue

Permission	URL 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. Note 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	URL symbol	Allowed operations
Query	r (for read)	Get entities and query entities.
Add	a	Add entities. Note Add and Update permissions are required for upsert operations.
Update	u	Update entities. Note Add and Update permissions are required for upsert operations.
Delete	d	Delete entities.

Specify permissions by combining URL symbols in the signedpermissions field of your SAS URL. 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 URL must specify sp=rwdl. To grant only read/write permissions, the URL 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.
  
  

Important
Shared Access Signature URLs 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 URLs should only be performed over an HTTPS connection, and Shared Access Signature URLs 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.

Specifying the signedidentifier field on the URL 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 URL.

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 URL for the Shared Access Signature. Specifying a signed identifier on the URL associates the signature with the stored access policy. To establish a container-level access policy using the REST API, see Use a Shared Access Signature (REST API).

Lifetime and Revocation of a Shared Access Signature

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 URL. 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 URL.

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.

Note

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 URL and none within the stored access policy; all on the container and none on the URL; or some combination of the two. However, you cannot specify a given parameter on both the signature URL and the stored access policy. See Use a Stored Access Policy for more information.

The signature part of the URL 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 URL.