Specifying a Container-Level Access Policy
A container-level access policy provides an additional level of control over Shared Access Signatures on the server side. Establishing a container-level access policy serves to group Shared Access Signatures and to provide additional restrictions for signatures that are bound by the policy. You can use a container-level access policy to change the start time, expiry time, or permissions for a signature, or to revoke it, after it has been issued.
A container-level access policy gives you greater flexibility in issuing Shared Access Signatures. Instead of specifying the signature's lifetime and permissions on the URL, you can specify these parameters within the access policy, stored as metadata on the container where your signed resource (container or blob) resides. To change these parameters for one or more signatures, you can modify the container-level access policy, rather than reissuing the signatures. You can also quickly revoke the signature by modifying the container-level access policy.
For example, suppose you have issued a Shared Access Signature that's associated with a container-level access policy. If you've specified the expiry time within the container-level access policy, you can modify the access policy to extend the life of the signature, without having to reissue a new signature.
Best practices recommend specifying a container-level access policy for any signed resource (container or blob) for which you are issuing a Shared Access Signature, as the container-level policy can be used to modify or revoke the signature after it has been issued. If you don't specify a container-level policy, it's recommended that you limit the lifetime of your signature in order to minimize any risk to your storage account resources. For more information, see Creating a Shared Access Signature.
A container-level access policy includes a signed identifier, a value that may be up to 64 characters long and must be unique within the container. 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 container-level access policy. For information about constructing the URL for a Shared Access Signature, see Creating a Shared Access Signature.
Any number of signatures can be associated with a single container-level access policy.
The container-level access policy can specify the following access policy parameters for the signatures with which it's associated:
Depending on how you want to control access to your container or blob resource, you can specify all of these parameters within the container-level access policy, and omit them from the URL for the Shared Access Signature. Doing so permits you to modify the associated signature's behavior at any time, as well as to revoke it. Or you can specify one or more of the access policy parameters within the container-level access policy, and the others on the URL. Finally, you can specify all of the parameters on the URL. In this case, you can use the container-level access policy to revoke the signature, but not to modify its behavior.
Together the Shared Access Signature and the container-level access policy must include all fields required to authenticate the signature. If any required fields are missing, the request will fail. Likewise, if a field is specified both in the Shared Access Signature URL and in the container-level access policy, the request will fail with status code 400 (Bad Request). See Creating a Shared Access Signature for more information about the fields that comprise the signature.
To establish a container-level access policy, call the Set Container ACL 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.
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 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.