AzureStor (version 3.4.0)

get_account_sas: Generate shared access signatures

Description

The simplest way for a user to access files and data in a storage account is to give them the account's access key. This gives them full control of the account, and so may be a security risk. An alternative is to provide the user with a shared access signature (SAS), which limits access to specific resources and only for a set length of time. AzureStor supports generating two kinds of SAS: account and user delegation, with the latter applying only to blob and ADLS2 storage.

Usage

get_account_sas(account, ...)
# S3 method for az_storage
get_account_sas(account, key = account$list_keys()[1], ...)
# S3 method for storage_endpoint
get_account_sas(account, key = account$key, ...)
# S3 method for default
get_account_sas(account, key, start = NULL,
  expiry = NULL, services = "bqtf", permissions = "rl",
  resource_types = "sco", ip = NULL, protocol = NULL,
  auth_api_version = getOption("azure_storage_api_version"), ...)
get_user_delegation_key(account, ...)
# S3 method for az_resource
get_user_delegation_key(account, token = account$token, ...)
# S3 method for blob_endpoint
get_user_delegation_key(account,
  token = account$token, key_start, key_expiry, ...)
revoke_user_delegation_keys(account)
# S3 method for az_storage
revoke_user_delegation_keys(account)
get_user_delegation_sas(account, ...)
# S3 method for az_storage
get_user_delegation_sas(account, key, ...)
# S3 method for blob_endpoint
get_user_delegation_sas(account, key, ...)
# S3 method for default
get_user_delegation_sas(account, key, resource,
  start = NULL, expiry = NULL, permissions = "rl",
  resource_types = "c", ip = NULL, protocol = NULL,
  snapshot_time = NULL,
  auth_api_version = getOption("azure_storage_api_version"), ...)

Arguments

account

An object representing a storage account. Depending on the generic, this can be one of the following: an Azure resource object (of class az_storage); a client storage endpoint (of class storage_endpoint); a blob storage endpoint (of class blob_endpoint); or a string with the name of the account.

...

Arguments passed to lower-level functions.

key

For get_account_sas, the account key, which controls full access to the storage account. For get_user_delegation_sas, a user delegation key, as obtained from get_user_delegation_key.

start, expiry

The start and end dates for the account or user delegation SAS. These should be Date or POSIXct values, or strings coercible to such. If not supplied, the default is to generate start and expiry values for a period of 8 hours, starting from the current time.

services

For get_account_sas, the storage service(s) for which the SAS is valid. Defaults to bqtf, meaning blob (including ADLS2), queue, table and file storage.

permissions

For get_account_sas and get_user_delegation_sas, the permissions that the SAS grants. The default rl (read and list) essentially means read-only access.

resource_types

The resource types for which the SAS is valid. For get_account_sas the default is sco meaning service, container and object. For get_user_delegation_sas the default is c meaning container-level access (including blobs within the container).

ip

The IP address(es) or IP address range(s) for which the SAS is valid. The default is not to restrict access by IP.

protocol

The protocol required to use the SAS. Possible values are https meaning HTTPS-only, or https,http meaning HTTP is also allowed. Note that the storage account itself may require HTTPS, regardless of what the SAS allows.

auth_api_version

The storage API version to use for authenticating.

token

For get_user_delegation_key, an AAD token from which to obtain user details. The token must have https://storage.azure.com as its audience.

key_start, key_expiry

For get_user_delegation_key, the start and end dates for the user delegation key.

resource

For get_user_delegation_sas, the resource for which the SAS is valid. This can be either the name of a blob container, or a blob. If the latter, it should include the container as well (containername/blobname).

snapshot_time

For get_user_delegation_sas, the blob snapshot for which the SAS is valid. Only required if resource_types="bs".

Details

Listed here are S3 generics and methods to obtain a SAS for accessing storage; in addition, the az_storage resource class has R6 methods for get_account_sas, get_user_delegation_key and revoke_user_delegation_keys which simply call the corresponding S3 method.

Note that you don't need to worry about these methods if you have been given a SAS, and only want to use it to access a storage account.

An account SAS is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a user delegation SAS are also available via an account SAS. You can also delegate access to read, write, and delete operations on blob containers, tables, queues, and file shares. To obtain an account SAS, call get_account_sas.

A user delegation SAS is a SAS secured with Azure AD credentials. It's recommended that you use Azure AD credentials when possible as a security best practice, rather than using the account key, which can be more easily compromised. When your application design requires shared access signatures, use Azure AD credentials to create a user delegation SAS for superior security.

Every SAS is signed with a key. To create a user delegation SAS, you must first request a user delegation key, which is then used to sign the SAS. The user delegation key is analogous to the account key used to sign a service SAS or an account SAS, except that it relies on your Azure AD credentials. To request the user delegation key, call get_user_delegation_key. With the user delegation key, you can then create the SAS with get_user_delegation_sas.

To invalidate all user delegation keys, as well as the SAS's generated with them, call revoke_user_delegation_keys.

See the examples and Microsoft Docs pages below for how to specify arguments like the services, permissions, and resource types. Also, while not explicitly mentioned in the documentation, ADLSgen2 storage can use any SAS that is valid for blob storage.

See Also

blob_endpoint, file_endpoint, Date, POSIXt, Azure Storage Provider API reference, Azure Storage Services API reference, Create an account SAS, Create a user delegation SAS

Examples

# NOT RUN {
# account SAS valid for 7 days
get_account_sas("mystorage", "access_key", start=Sys.Date(), expiry=Sys.Date() + 7)

# SAS with read/write/create/delete permissions
get_account_sas("mystorage", "access_key", permissions="rwcd")

# SAS limited to blob (+ADLS2) and file storage
get_account_sas("mystorage", "access_key", services="bf")

# SAS for file storage, allows access to files only (not shares)
get_account_sas("mystorage", "access_key", services="f", resource_types="o")

# getting the key from an endpoint object
endp <- storage_endpoint("https://mystorage.blob.core.windows.net", key="access_key")
get_account_sas(endp, permissions="rwcd")

# }
# NOT RUN {
# user delegation key valid for 24 hours
token <- AzureRMR::get_azure_token("https://storage.azure.com", "mytenant", "app_id")
endp <- storage_endpoint("https://mystorage.blob.core.windows.net", token=token)
userkey <- get_user_delegation_key(endp, start=Sys.Date(), expiry=Sys.Date() + 1)

# user delegation SAS for a container
get_user_delegation_sas(endp, userkey, resource="mycontainer")

# user delegation SAS for a specific file, read/write/create/delete access
# (order of permissions is important!)
get_user_delegation_sas(endp, userkey, resource="mycontainer/myfile",
                        resource_types="b", permissions="rcwd")

# }

Run the code above in your browser using DataCamp Workspace