com.azure.storage.blob.sas

Class BlobServiceSasSignatureValues

java.lang.Object

com.azure.storage.blob.sas.BlobServiceSasSignatureValues

public final class BlobServiceSasSignatureValues
extends Object

Used to generate a Shared Access Signature (SAS) for an Azure Blob Storage service. Once all the values here are set, call generateSasQueryParameters(StorageSharedKeyCredential) or generateSasQueryParameters(UserDelegationKey, String) to obtain a representation of the SAS which can be applied to blob urls.

Generating SAS query parameters with StorageSharedKeyCredential

The following code generates SAS query parameters for an Azure storage blob.

BlobSasPermission blobPermission = new BlobSasPermission().setReadPermission(true);

// We are creating a SAS to a blob because we set both the container name and blob name.
BlobServiceSasSignatureValues builder = new BlobServiceSasSignatureValues()
    .setProtocol(SasProtocol.HTTPS_ONLY) // Users MUST use HTTPS (not HTTP).
    .setExpiryTime(OffsetDateTime.now().plusDays(2))
    .setContainerName("my-container")
    .setBlobName("HelloWorld.txt")
    .setPermissions(blobPermission);

StorageSharedKeyCredential credential = new StorageSharedKeyCredential("account-name", "key");
BlobServiceSasQueryParameters sasQueryParameters = builder.generateSasQueryParameters(credential);

Generating SAS query parameters with UserDelegationKey

The following sample generates SAS query parameters for an Azure storage container.

BlobSasPermission blobPermission = new BlobSasPermission()
    .setReadPermission(true)
    .setWritePermission(true);

// We are creating a SAS to a container because only container name is set.
BlobServiceSasSignatureValues builder = new BlobServiceSasSignatureValues()
    .setProtocol(SasProtocol.HTTPS_ONLY) // Users MUST use HTTPS (not HTTP).
    .setExpiryTime(OffsetDateTime.now().plusDays(2))
    .setContainerName("my-container")
    .setPermissions(blobPermission);

// Get a user delegation key after signing in with Azure AD
UserDelegationKey credential = new UserDelegationKey();
String account = "my-blob-storage-account";
BlobServiceSasQueryParameters sasQueryParameters = builder.generateSasQueryParameters(credential, account);

See Also:

BlobServiceSasQueryParameters, Storage SAS overview, Constructing a Service SAS

Constructor Summary

Constructors

Constructor and Description
BlobServiceSasSignatureValues() Creates an object with empty values for all fields.
BlobServiceSasSignatureValues(String version, SasProtocol sasProtocol, OffsetDateTime startTime, OffsetDateTime expiryTime, String permission, SasIpRange sasIpRange, String identifier, String cacheControl, String contentDisposition, String contentEncoding, String contentLanguage, String contentType)

Method Summary

Modifier and Type	Method and Description
BlobServiceSasQueryParameters	generateSasQueryParameters(StorageSharedKeyCredential storageSharedKeyCredentials) Uses an account's shared key credential to sign these signature values to produce the proper SAS query parameters.
BlobServiceSasQueryParameters	generateSasQueryParameters(UserDelegationKey delegationKey, String accountName) Uses a user delegation key to sign these signature values to produce the proper SAS query parameters.
String	getBlobName() Decodes and gets the name of the blob the SAS user may access.
String	getCacheControl()
String	getContainerName() Gets the name of the container the SAS user may access.
String	getContentDisposition()
String	getContentEncoding()
String	getContentLanguage()
String	getContentType()
OffsetDateTime	getExpiryTime()
String	getIdentifier()
String	getPermissions()
SasProtocol	getProtocol()
SasIpRange	getSasIpRange()
String	getSnapshotId()
OffsetDateTime	getStartTime()
String	getVersion()
BlobServiceSasSignatureValues	setBlobName(String blobName) Sets the blob the SAS user may access.
BlobServiceSasSignatureValues	setCacheControl(String cacheControl) Sets the cache-control header for the SAS.
BlobServiceSasSignatureValues	setContainerName(String containerName) Sets the container the SAS user may access.
BlobServiceSasSignatureValues	setContentDisposition(String contentDisposition) Sets the content-disposition header for the SAS.
BlobServiceSasSignatureValues	setContentEncoding(String contentEncoding) Sets the content-encoding header for the SAS.
BlobServiceSasSignatureValues	setContentLanguage(String contentLanguage) Sets the content-language header for the SAS.
BlobServiceSasSignatureValues	setContentType(String contentType) Sets the content-type header for the SAS.
BlobServiceSasSignatureValues	setExpiryTime(OffsetDateTime expiryTime) Sets the time after which the SAS will no longer work.
BlobServiceSasSignatureValues	setIdentifier(String identifier) Sets the name of the access policy on the container this SAS references if any.
BlobServiceSasSignatureValues	setPermissions(BlobContainerSasPermission permissions) Sets the Container permissions allowed by the SAS.
BlobServiceSasSignatureValues	setPermissions(BlobSasPermission permissions) Sets the Blob permissions allowed by the SAS.
BlobServiceSasSignatureValues	setProtocol(SasProtocol protocol) Sets the SasProtocol which determines the protocols allowed by the SAS.
BlobServiceSasSignatureValues	setSasIpRange(SasIpRange sasIpRange) Sets the SasIpRange which determines the IP ranges that are allowed to use the SAS.
BlobServiceSasSignatureValues	setSnapshotId(String snapshotId) Sets the specific snapshot the SAS user may access.
BlobServiceSasSignatureValues	setStartTime(OffsetDateTime startTime) Sets when the SAS will take effect.
BlobServiceSasSignatureValues	setVersion(String version) Sets the version of the service this SAS will target.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BlobServiceSasSignatureValues

public BlobServiceSasSignatureValues()

Creates an object with empty values for all fields.

BlobServiceSasSignatureValues

public BlobServiceSasSignatureValues(String version,
                                     SasProtocol sasProtocol,
                                     OffsetDateTime startTime,
                                     OffsetDateTime expiryTime,
                                     String permission,
                                     SasIpRange sasIpRange,
                                     String identifier,
                                     String cacheControl,
                                     String contentDisposition,
                                     String contentEncoding,
                                     String contentLanguage,
                                     String contentType)

Method Detail

getVersion

public String getVersion()

Returns:

the version of the service this SAS will target. If not specified, it will default to the version targeted by the library.

setVersion

public BlobServiceSasSignatureValues setVersion(String version)

Sets the version of the service this SAS will target. If not specified, it will default to the version targeted by the library.

Parameters:

version - Version to target

Returns:

the updated BlobServiceSASSignatureValues object

getProtocol

public SasProtocol getProtocol()

Returns:

the SasProtocol which determines the protocols allowed by the SAS.

setProtocol

public BlobServiceSasSignatureValues setProtocol(SasProtocol protocol)

Sets the SasProtocol which determines the protocols allowed by the SAS.

Parameters:

protocol - Protocol for the SAS

Returns:

the updated BlobServiceSASSignatureValues object

getStartTime

public OffsetDateTime getStartTime()

Returns:

when the SAS will take effect.

setStartTime

public BlobServiceSasSignatureValues setStartTime(OffsetDateTime startTime)

Sets when the SAS will take effect.

Parameters:

startTime - When the SAS takes effect

Returns:

the updated BlobServiceSASSignatureValues object

getExpiryTime

public OffsetDateTime getExpiryTime()

Returns:

the time after which the SAS will no longer work.

setExpiryTime

public BlobServiceSasSignatureValues setExpiryTime(OffsetDateTime expiryTime)

Sets the time after which the SAS will no longer work.

Parameters:

expiryTime - When the SAS will no longer work

Returns:

the updated BlobServiceSASSignatureValues object

getPermissions

public String getPermissions()

Returns:

the permissions string allowed by the SAS. Please refer to either BlobContainerSasPermission or BlobSasPermission depending on the resource being accessed for help determining the permissions allowed.

setPermissions

public BlobServiceSasSignatureValues setPermissions(BlobSasPermission permissions)

Sets the Blob permissions allowed by the SAS.

Parameters:

permissions - BlobSasPermission

Returns:

the updated BlobServiceSASSignatureValues object

Throws:

NullPointerException - if permissions is null.

setPermissions

public BlobServiceSasSignatureValues setPermissions(BlobContainerSasPermission permissions)

Sets the Container permissions allowed by the SAS.

Parameters:

permissions - BlobContainerSasPermission

Returns:

the updated BlobServiceSASSignatureValues object

Throws:

NullPointerException - if permissions is null.

getSasIpRange

public SasIpRange getSasIpRange()

Returns:

the SasIpRange which determines the IP ranges that are allowed to use the SAS.

setSasIpRange

public BlobServiceSasSignatureValues setSasIpRange(SasIpRange sasIpRange)

Sets the SasIpRange which determines the IP ranges that are allowed to use the SAS.

Parameters:

sasIpRange - Allowed IP range to set

Returns:

the updated BlobServiceSASSignatureValues object

getContainerName

public String getContainerName()

Gets the name of the container the SAS user may access.

Returns:

The name of the container the SAS user may access.

setContainerName

public BlobServiceSasSignatureValues setContainerName(String containerName)

Sets the container the SAS user may access.

Parameters:

containerName - The name of the container.

Returns:

The updated BlobServiceSASSignatureValues object.

getBlobName

public String getBlobName()

Decodes and gets the name of the blob the SAS user may access. null or an empty string is returned when a creating a container SAS.

Returns:

The decoded name of the blob the SAS user may access. null or an empty string is returned when a creating a container SAS.

setBlobName

public BlobServiceSasSignatureValues setBlobName(String blobName)

Sets the blob the SAS user may access. Use null or an empty string to create a container SAS.

Parameters:

blobName - The name of the blob. Use null or an empty string to create a container SAS.

Returns:

The updated BlobServiceSASSignatureValues object.

getSnapshotId

public String getSnapshotId()

Returns:

the specific snapshot the SAS user may access.

setSnapshotId

public BlobServiceSasSignatureValues setSnapshotId(String snapshotId)

Sets the specific snapshot the SAS user may access.

BlobServiceSasSignatureValues.resource will be set to BlobServiceSasSignatureValues.SAS_BLOB_SNAPSHOT_CONSTANT if the passed snapshotId isn't null amd BlobServiceSasSignatureValues.resource is set to BlobServiceSasSignatureValues.SAS_BLOB_CONSTANT.

Parameters:

snapshotId - Identifier of the snapshot

Returns:

the updated BlobServiceSASSignatureValues object

getIdentifier

public String getIdentifier()

Returns:

the name of the access policy on the container this SAS references if any. Please see here for more information.

setIdentifier

public BlobServiceSasSignatureValues setIdentifier(String identifier)

Sets the name of the access policy on the container this SAS references if any. Please see here for more information.

Parameters:

identifier - Name of the access policy

Returns:

the updated BlobServiceSASSignatureValues object

getCacheControl

public String getCacheControl()

Returns:

the cache-control header for the SAS.

setCacheControl

public BlobServiceSasSignatureValues setCacheControl(String cacheControl)

Sets the cache-control header for the SAS.

Parameters:

cacheControl - Cache-Control header value

Returns:

the updated BlobServiceSASSignatureValues object

getContentDisposition

public String getContentDisposition()

Returns:

the content-disposition header for the SAS.

setContentDisposition

public BlobServiceSasSignatureValues setContentDisposition(String contentDisposition)

Sets the content-disposition header for the SAS.

Parameters:

contentDisposition - Content-Disposition header value

Returns:

the updated BlobServiceSASSignatureValues object

getContentEncoding

public String getContentEncoding()

Returns:

the content-encoding header for the SAS.

setContentEncoding

public BlobServiceSasSignatureValues setContentEncoding(String contentEncoding)

Sets the content-encoding header for the SAS.

Parameters:

contentEncoding - Content-Encoding header value

Returns:

the updated BlobServiceSASSignatureValues object

getContentLanguage

public String getContentLanguage()

Returns:

the content-language header for the SAS.

setContentLanguage

public BlobServiceSasSignatureValues setContentLanguage(String contentLanguage)

Sets the content-language header for the SAS.

Parameters:

contentLanguage - Content-Language header value

Returns:

the updated BlobServiceSASSignatureValues object

getContentType

public String getContentType()

Returns:

the content-type header for the SAS.

setContentType

public BlobServiceSasSignatureValues setContentType(String contentType)

Sets the content-type header for the SAS.

Parameters:

contentType - Content-Type header value

Returns:

the updated BlobServiceSASSignatureValues object

generateSasQueryParameters

public BlobServiceSasQueryParameters generateSasQueryParameters(StorageSharedKeyCredential storageSharedKeyCredentials)

Uses an account's shared key credential to sign these signature values to produce the proper SAS query parameters.

Notes on SAS generation

• If version is not set, the latest service version is used.
• If identifier is set, expiryTime and permissions should not be set. These values are inherited from the stored access policy.
• Otherwise, expiryTime and permissions must be set.

The type of SAS query parameters returned depends on the following:

1. If BlobServiceSasSignatureValues.getBlobName() is not set, container SAS query parameters are returned.
2. If BlobServiceSasSignatureValues.getBlobName() and BlobServiceSasSignatureValues.getSnapshotId() are set, blob snapshot SAS query parameters are returned.
3. If only BlobServiceSasSignatureValues.getBlobName() is set, blob SAS query parameters are returned.

See class level JavaDocs for code snippets.

Parameters:

storageSharedKeyCredentials - A StorageSharedKeyCredential object used to sign the SAS values.

Returns:

BlobServiceSasQueryParameters

Throws:

IllegalStateException - If the HMAC-SHA256 algorithm isn't supported, if the key isn't a valid Base64 encoded string, or the UTF-8 charset isn't supported.

IllegalArgumentException - if BlobServiceSasSignatureValues.getPermissions() contains an invalid character for the SAS resource.

NullPointerException - if storageSharedKeyCredentials is null.

generateSasQueryParameters

public BlobServiceSasQueryParameters generateSasQueryParameters(UserDelegationKey delegationKey,
                                                                String accountName)

Uses a user delegation key to sign these signature values to produce the proper SAS query parameters.

Notes on SAS generation

• If version is not set, the latest service version is used.
• If identifier is set, expiryTime and permissions should not be set. These values are inherited from the stored access policy.
• Otherwise, expiryTime and permissions must be set.

The type of SAS query parameters returned depends on the following:

1. If BlobServiceSasSignatureValues.getBlobName() is not set, container SAS query parameters are returned.
2. If BlobServiceSasSignatureValues.getBlobName() and BlobServiceSasSignatureValues.getSnapshotId() are set, blob snapshot SAS query parameters are returned.
3. If only BlobServiceSasSignatureValues.getBlobName() is set, blob SAS query parameters are returned.

See class level JavaDocs for code snippets.

Parameters:

delegationKey - A UserDelegationKey object used to sign the SAS values.

accountName - Azure Storage account name to generate SAS for.

Returns:

BlobServiceSasQueryParameters

Throws:

IllegalStateException - If the HMAC-SHA256 algorithm isn't supported, if the key isn't a valid Base64 encoded string, or the UTF-8 charset isn't supported.

IllegalArgumentException - if BlobServiceSasSignatureValues.getPermissions() contains an invalid character for the SAS resource.

NullPointerException - if delegationKey or account is null.

See Also:

Create a user delegation SAS