Create an account SAS

As of version 2015-04-05, Azure Storage supports creating a new type of shared access signature (SAS) at the level of the storage account. By creating an account SAS, you can:

  • Delegate access to service-level operations that aren't currently available with a service-specific SAS, such as the Get/Set Service Properties and Get Service Stats operations.

  • Delegate access to more than one service in a storage account at a time. For example, you can delegate access to resources in both Azure Blob Storage and Azure Files by using an account SAS.

  • Delegate access to write and delete operations for containers, queues, tables, and file shares, which are not available with an object-specific SAS.

  • Specify an IP address or a range of IP addresses from which to accept requests.

  • Specify the HTTP protocol from which to accept requests (either HTTPS or HTTP/HTTPS).

Stored access policies are currently not supported for an account SAS.

Caution

Shared access signatures are keys that grant permissions to storage resources, and you should protect them just as you would protect an account key. It's important to protect a SAS from malicious or unintended use. Use discretion in distributing a SAS, and have a plan in place for revoking a compromised SAS. Operations that use shared access signatures should be performed only over an HTTPS connection, and SAS URIs should be distributed only on a secure connection, such as HTTPS.

Authorize an account SAS

You secure an account SAS by using a storage account key. When you create an account SAS, your client application must possess the account key.

To use Microsoft Entra credentials to secure a SAS for a container or blob, create a user delegation SAS.

Construct an account SAS URI

The account SAS URI consists of the URI to the resource for which the SAS will delegate access, followed by a SAS token. The SAS token is the query string that includes all the information that's required to authorize a request to the resource. It specifies the service, resource, and permissions that are available for access, and the time period during which the signature is valid.

Specify the account SAS parameters

The required and optional parameters for the SAS token are described in the following table:

SAS query parameter Description
api-version Optional. Specifies the storage service version to use to execute the request that's made using the account SAS URI. For more information, see Authorize requests by using a shared access signature.
SignedVersion (sv) Required. Specifies the signed storage service version to use to authorize requests that are made with this account SAS. It must be set to version 2015-04-05 or later. For more information, see Authorize requests by using a shared access signature.
SignedServices (ss) Required. Specifies the signed services that are accessible with the account SAS. Possible values include:

- Blob (b)
- Queue (q)
- Table (t)
- File (f)

You can combine values to provide access to more than one service. For example, ss=bf specifies access to the Blob Storage and Azure Files endpoints.
SignedResourceTypes (srt) Required. Specifies the signed resource types that are accessible with the account SAS.

- Service (s): Access to service-level APIs (for example, Get/Set Service Properties, Get Service Stats, List Containers/Queues/Tables/Shares).
- Container (c): Access to container-level APIs (for example, Create/Delete Container, Create/Delete Queue, Create/Delete Table, Create/Delete Share, List Blobs/Files and Directories).
- Object (o): Access to object-level APIs for blobs, queue messages, table entities, and files (for example, Put Blob, Query Entity, Get Messages, Create File).

You can combine values to provide access to more than one resource type. For example, srt=sc specifies access to service and container resources.
SignedPermissions (sp) Required. Specifies the signed permissions for the account SAS. Permissions are valid only if they match the specified signed resource type. If they don't match, they're ignored.

- Read (r): Valid for all signed resources types (Service, Container, and Object). Permits read permissions to the specified resource type.
- Write (w): Valid for all signed resources types (Service, Container, and Object). Permits write access for the specified resource type, allowing a user to create and update resources.
- Delete (d): Valid for Container and Object resource types, except for queue messages.
- Permanent Delete (y): Valid for Object resource type of Blob only.
- List (l): Valid for Service and Container resource types only.
- Add (a): Valid for the following Object resource types only: queue messages, table entities, and append blobs.
- Create (c): Valid for Container resource types and the following Object resource types: blobs and files. Users can create new resources, but may not overwrite existing resources.
- Update (u): Valid for the following Object resource types only: queue messages and table entities.
- Process (p): Valid for the following Object resource type only: queue messages.
- Tag (t): Valid for the following Object resource type only: blobs. Permits blob tag operations.
- Filter (f): Valid for the following Object resource type only: blob. Permits filtering by blob tag.
- Set Immutability Policy (i): Valid for the following Object resource type only: blob. Permits set/delete immutability policy and legal hold on a blob.
SignedStart (st) Optional. The time when the SAS becomes valid, expressed in one of the accepted ISO 8601 UTC formats. If it's omitted, the start time is assumed to be the time when the storage service receives the request. For more information about accepted UTC formats, see Formatting DateTime values.
SignedExpiry (se) Required. The time when the shared access signature becomes invalid, expressed in one of the accepted ISO 8601 UTC formats. For more information about accepted UTC formats, see Formatting DateTime values.
SignedIP (sip) Optional. Specifies an IP address or a range of IP addresses from which to accept requests. When you specify a range, keep in mind that the range is inclusive. Only IPv4 addresses are supported.

For example, sip=168.1.5.65 or sip=168.1.5.60-168.1.5.70.
SignedProtocol (spr) Optional. Specifies the protocol that's permitted for a request made with the account SAS. Possible values are both HTTPS and HTTP (https,http) or HTTPS only (https). The default value is https,http.

Note that HTTP only is not a permitted value.
SignedEncryptionScope (ses) Optional. Indicates the encryption scope to use to encrypt the request contents. This field is supported with version 2020-12-06 and later.
Signature (sig) Required. The signature part of the URI is used to authorize the request that's made with the shared access signature.

The string-to-sign is a unique string that's constructed from the fields that must be verified to authorize the request. The signature is a hash-based message authentication code (HMAC) that's computed over the string-to-sign and key by using the SHA256 algorithm, and then encoded by using Base64 encoding.

Specify the signedVersion field

The signedVersion (sv) field contains the service version of the shared access signature. This value specifies the version of Shared Key authorization that's used by this shared access signature (in the signature field). The value also specifies the service version for requests that are made with this shared access signature.

For information about which version is used when you execute requests via a shared access signature, see Versioning for Azure Storage services.

For information about how this parameter affects the authorization of requests made with a shared access signature, see Delegate access with a shared access signature.

Field name Query parameter Description
signedVersion sv Required. Supported in version 2015-04-05 and later. The storage service version to use to authorize and handle requests that you make with this shared access signature. For more information, see Versioning for Azure Storage services.

Specify an IP address or IP range

As of version 2015-04-05, the optional signedIp (sip) field specifies a public IP address or a range of public IP addresses from which to accept requests. If the IP address from which the request originates doesn't match the IP address or address range that's specified on the SAS token, the request isn't authorized. Only IPv4 addresses are supported.

When you're specifying a range of IP addresses, keep in mind that the range is inclusiveFor example, specifying sip=168.1.5.65 or sip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses.

The following table describes whether to include the signedIp field on a SAS token for a specified scenario, based on the client environment and the location of the storage account.

Client environment Storage account location Recommendation
Client running in Azure In the same region as the client A SAS that's provided to the client in this scenario shouldn't include an outbound IP address for the signedIp field. Requests that are made from within the same region that use a SAS with a specified outbound IP address will fail.

Instead, use an Azure virtual network to manage network security restrictions. Requests to Azure Storage from within the same region always take place over a private IP address. For more information, see Configure Azure Storage firewalls and virtual networks.
Client running in Azure In a different region from the client A SAS that's provided to the client in this scenario may include a public IP address or range of addresses for the signedIp field. A request made with the SAS must originate from the specified IP address or range of addresses.
Client running on-premises or in a different cloud environment In any Azure region A SAS that's provided to the client in this scenario may include a public IP address or range of addresses for the signedIp field. A request made with the SAS must originate from the specified IP address or range of addresses.

If the request passes through a proxy or gateway, provide the public outbound IP address of that proxy or gateway for the signedIp field.

Specify the HTTP protocol

As of version 2015-04-05, the optional signedProtocol (spr) field specifies the protocol that's permitted for a request made with the SAS. Possible values are both HTTPS and HTTP (https,http) or HTTPS only (https). The default value is https,http. Note that HTTP only isn't a permitted value.

Specify the encryption scope

By using the signedEncryptionScope field on the URI, you can specify the encryption scope that the client application can use. It enforces the server-side encryption with the specified encryption scope when you upload blobs (PUT) with the SAS token. The GET and HEAD will not be restricted and performed as before.

The following table describes how to refer to a signed encryption scope on the URI:

Field name Query parameter Description
signedEncryptionScope ses Optional. Indicates the encryption scope to use to encrypt the request contents.

This field is supported with version 2020-12-06 or later. If you add the ses before the supported version, the service returns error response code 403 (Forbidden).

If you set the default encryption scope for the container or file system, the ses query parameter respects the container encryption policy. If there's a mismatch between the ses query parameter and x-ms-default-encryption-scope header, and the x-ms-deny-encryption-scope-override header is set to true, the service returns error response code 403 (Forbidden).

When you provide the x-ms-encryption-scope header and the ses query parameter in the PUT request, the service returns error response code 400 (Bad Request) if there's a mismatch.

Construct the signature string

To construct the signature string for an account SAS, first construct the string-to-sign from the fields that compose the request, and then encode the string as UTF-8 and compute the signature by using the HMAC-SHA256 algorithm.

Note

The fields that are included in the string-to-sign must be URL-decoded.

To construct the string-to-sign for an account SAS, use the following format:

StringToSign = accountname + "\n" +  
    signedpermissions + "\n" +  
    signedservice + "\n" +  
    signedresourcetype + "\n" +  
    signedstart + "\n" +  
    signedexpiry + "\n" +  
    signedIP + "\n" +  
    signedProtocol + "\n" +  
    signedversion + "\n"  
  

Version 2020-12-06 adds support for the signed encryption scope field. To construct the string-to-sign for an account SAS, use the following format:

StringToSign = accountname + "\n" +  
    signedpermissions + "\n" +  
    signedservice + "\n" +  
    signedresourcetype + "\n" +  
    signedstart + "\n" +  
    signedexpiry + "\n" +  
    signedIP + "\n" +  
    signedProtocol + "\n" +  
    signedversion + "\n" +
    signedEncryptionScope + "\n"  
  

Account SAS permissions by operation

The tables in the following sections list various APIs for each service and the signed resource types and signed permissions that are supported for each operation.

Blob service

The following table lists Blob service operations and indicates which signed resource type and signed permissions to specify when you delegate access to those operations.

Operation Signed service Signed resource type Signed permission
List Containers Blob (b) Service (s) List (l)
Get Blob Service Properties Blob (b) Service (s) Read (r)
Set Blob Service Properties Blob (b) Service (s) Write (w)
Get Blob Service Stats Blob (b) Service (s) Read (r)
Create Container Blob (b) Container (c) Create(c) or Write (w)
Get Container Properties Blob (b) Container (c) Read (r)
Get Container Metadata Blob (b) Container (c) Read (r)
Set Container Metadata Blob (b) Container (c) Write (w)
Lease Container Blob (b) Container (c) Write (w) or Delete (d)1
Delete Container Blob (b) Container (c) Delete (d)1
Find Blobs by Tags in Container Blob (b) Container (c) Filter (f)
List Blobs Blob (b) Container (c) List (l)
Put Blob (create new block blob) Blob (b) Object (o) Create (c) or Write (w)
Put Blob (overwrite existing block blob) Blob (b) Object (o) Write (w)
Put Blob (create new page blob) Blob (b) Object (o) Create (c) or Write (w)
Put Blob (overwrite existing page blob) Blob (b) Object (o) Write (w)
Get Blob Blob (b) Object (o) Read (r)
Get Blob Properties Blob (b) Object (o) Read (r)
Set Blob Properties Blob (b) Object (o) Write (w)
Get Blob Metadata Blob (b) Object (o) Read (r)
Set Blob Metadata Blob (b) Object (o) Write (w)
Get Blob Tags Blob (b) Object (o) Tags (t)
Set Blob Tags Blob (b) Object (o) Tags (t)
Find Blobs by Tags Blob (b) Object (o) Filter (f)
Delete Blob Blob (b) Object (o) Delete (d)1
Permanently delete snapshot / version Blob (b) Object (o) Permanent Delete (y)
Lease Blob Blob (b) Object (o) Write (w) or Delete (d)1
Snapshot Blob Blob (b) Object (o) Create (c) or Write (w)
Copy Blob (destination is new blob) Blob (b) Object (o) Create (c) or Write (w)
Copy Blob (destination is an existing blob) Blob (b) Object (o) Write (w)
Incremental Copy Blob (b) Object (o) Create (c) or Write (w)
Abort Copy Blob Blob (b) Object (o) Write (w)
Put Block Blob (b) Object (o) Write (w)
Put Block List (create new blob) Blob (b) Object (o) Write (w)
Put Block List (update existing blob) Blob (b) Object (o) Write (w)
Get Block List Blob (b) Object (o) Read (r)
Put Page Blob (b) Object (o) Write (w)
Get Page Ranges Blob (b) Object (o) Read (r)
Append Block Blob (b) Object (o) Add (a) or Write (w)
Clear Page Blob (b) Object (o) Write (w)

1 The Delete permission allows breaking a lease on a blob or container with version 2017-07-29 and later.

Queue service

The following table lists Queue service operations and indicates which signed resource type and signed permissions to specify when you delegate access to those operations.

Operation Signed service Signed resource type Signed permission
Get Queue Service Properties Queue (q) Service (s) Read (r)
Set Queue Service Properties Queue (q) Service (s) Write (w)
List Queues Queue (q) Service (s) List (l)
Get Queue Service Stats Queue (q) Service (s) Read (r)
Create Queue Queue (q) Container (c) Create(c) or Write (w)
Delete Queue Queue (q) Container (c) Delete (d)
Get Queue Metadata Queue (q) Container (c) Read (r)
Set Queue Metadata Queue (q) Container (c) Write (w)
Put Message Queue (q) Object (o) Add (a)
Get Messages Queue (q) Object (o) Process (p)
Peek Messages Queue (q) Object (o) Read (r)
Delete Message Queue (q) Object (o) Process (p)
Clear Messages Queue (q) Object (o) Delete (d)
Update Message Queue (q) Object (o) Update (u)

Table service

The following table lists Table service operations and indicates which signed resource type and signed permissions to specify when you delegate access to those operations.

Operation Signed service Signed resource type Signed permission
Get Table Service Properties Table (t) Service (s) Read (r)
Set Table Service Properties Table (t) Service (s) Write (w)
Get Table Service Stats Table (t) Service (s) Read (r)
Query Tables Table (t) Container (c) List (l)
Create Table Table (t) Container (c) Create (c) or Write (w)
Delete Table Table (t) Container (c) Delete (d)
Query Entities Table (t) Object (o) Read (r)
Insert Entity Table (t) Object (o) Add (a)
Insert Or Merge Entity Table (t) Object (o) Add (a) and Update (u)1
Insert Or Replace Entity Table (t) Object (o) Add (a) and Update (u)1
Update Entity Table (t) Object (o) Update (u)
Merge Entity Table (t) Object (o) Update (u)
Delete Entity Table (t) Object (o) Delete (d)

1 Add and Update permissions are required for upsert operations on the Table service.

File service

The following table lists File service operations and indicates which signed resource type and signed permissions to specify when you delegate access to those operations.

Operation Signed service Signed resource type Signed permission
List Shares File (f) Service (s) List (l)
Get File Service Properties File (f) Service (s) Read (r)
Set File Service Properties File (f) Service (s) Write (w)
Get Share Stats File (f) Container (c) Read (r)
Create Share File (f) Container (c) Create (c) or Write (w)
Snapshot Share File (f) Container (c) Create (c) or Write (w)
Get Share Properties File (f) Container (c) Read (r)
Set Share Properties File (f) Container (c) Write (w)
Get Share Metadata File (f) Container (c) Read (r)
Set Share Metadata File (f) Container (c) Write (w)
Delete Share File (f) Container (c) Delete (d)
List Directories and Files File (f) Container (c) List (l)
Create Directory File (f) Object (o) Create (c) or Write (w)
Get Directory Properties File (f) Object (o) Read (r)
Get Directory Metadata File (f) Object (o) Read (r)
Set Directory Metadata File (f) Object (o) Write (w)
Delete Directory File (f) Object (o) Delete (d)
Create File (create new) File (f) Object (o) Create (c) or Write (w)
Create File (overwrite existing) File (f) Object (o) Write (w)
Get File File (f) Object (o) Read (r)
Get File Properties File (f) Object (o) Read (r)
Get File Metadata File (f) Object (o) Read (r)
Set File Metadata File (f) Object (o) Write (w)
Delete File File (f) Object (o) Delete (d)
Rename File File (f) Object (o) Delete (d) or Write (w)
Put Range File (f) Object (o) Write (w)
List Ranges File (f) Object (o) Read (r)
Abort Copy File File (f) Object (o) Write (w)
Copy File File (f) Object (o) Write (w)
Clear Range File (f) Object (o) Write (w)

Account SAS URI example

The following example shows a Blob service URI with an account SAS token appended to it. The account SAS token provides permissions to the service, container, and objects. The table breaks down each part of the URI:

https://blobsamples.blob.core.windows.net/?sv=2022-11-02&ss=b&srt=sco&sp=rwlc&se=2023-05-24T09:51:36Z&st=2023-05-24T01:51:36Z&spr=https&sig=<signature>
Name SAS portion Description
Resource URI https://myaccount.blob.core.windows.net/?restype=service&comp=properties The service endpoint, with parameters for getting service properties (when called with GET) or setting service properties (when called with SET). Based on the value of the signed services field (ss), this SAS can be used with either Blob Storage or Azure Files.
Delimiter ? The delimiter that precedes the query string. The delimiter is not part of the SAS token.
Storage services version sv=2022-11-02 For Azure Storage services version 2012-02-12 and later, this parameter indicates which version to use.
Services ss=b The SAS applies to the Blob services.
Resource types srt=sco The SAS applies to service-level, container-level, and object-level operations.
Permissions sp=rwlc The permissions grant access to read, write, list, and create operations.
Start time st=2019-08-01T22%3A18%3A26Z Specified in UTC time. If you want the SAS to be valid immediately, omit the start time.
Expiry time se=2019-08-10T02%3A23%3A26Z Specified in UTC time.
Protocol spr=https Only requests that use HTTPS are permitted.
Signature sig=<signature> Used to authorize access to the blob. The signature is an HMAC that's computed over a string-to-sign and key by using the SHA256 algorithm, and then encoded by using Base64 encoding.

Because permissions are restricted to the service level, accessible operations with this SAS are Get Blob Service Properties (read) and Set Blob Service Properties (write). However, with a different resource URI, the same SAS token could also be used to delegate access to Get Blob Service Stats (read).

See also