Create a OneLake shared access signature (SAS) (Preview)

You can create a OneLake SAS to provide short-term, delegated access to a folder or file in OneLake backed by your Microsoft Entra credentials. OneLake SAS can provide temporary access to applications without support for Microsoft Entra, allowing them to load data or serve as proxies between other customer applications or Independent Software Vendors (ISVs).

To create a OneLake SAS, you must first request a user delegation key, which you then use to sign the SAS. To request a user delegation key, call the Get User Delegation Key operation. OneLake SAS can grant access to files and folders within data items only, and can't be used for management operations such as creating or deleting items or workspaces.

A OneLake SAS can grant access to files and folders within data items only, and can't be used for management operations such as creating workspaces or items.

A OneLake SAS is created similarly to Azure Storage user-delegated SAS, using the same parameters for compatibility with tools and applications compatible with Azure Storage.

Assign permissions

Requesting a user delegation key is a tenant-level operation in Fabric. To request a user delegation key, the user or security principle requesting the user delegation key must have at least read permissions in one workspace in the Fabric tenant. The requesting user's identity is used to authenticate the SAS, which means that the user must have permission to the data they grant the SAS access to.

Acquire an OAuth 2.0 token

To get the user delegation key, first request an OAuth 2.0 token from Microsoft Entra ID. Authorize the call to the Get User Delegation Key operation by providing the token with the Bearer scheme. For more information about requesting an OAuth token from Microsoft Entra ID, see Authentication flows and application scenarios.

Request the user delegation key

Calling the Get User Delegation Key operation returns the key as a set of values that are used as parameters on the user delegation SAS token. These parameters are described in the Get User Delegation Key reference and in the next section.

When a client requests a user delegation key using an OAuth 2.0 token, OneLake returns a user delegation key on behalf of the client. A SAS created with this user delegation key is granted at most the permissions granted to the client, scoped down to the permissions explicitly granted in the SAS.

You can create any number of OneLake SASs for the lifetime of the user delegation key. However, a OneLake SAS and user delegation keys can be valid for at most one hour, and can't exceed the lifetime of the token requesting them. These lifetime restrictions are shorter than the maximum lifetime of an Azure Storage user delegated SAS.

Construct a user delegation SAS

The following table summarizes the fields that are supported for a OneLake SAS token. Subsequent sections provide more details about these parameters and how they differ from Azure Storage SAS tokens. OneLake doesn't support every optional parameter supported by Azure Storage, and a OneLake SAS constructed with an unsupported parameter will be rejected.

Specify Permissions

The permissions specified in the signedPermissions (sp) field on the SAS token indicate which operations a client possessing the SAS can perform on the resource.

Permissions can be combined to permit a client to perform multiple operations with the same SAS. When you construct the SAS, you must include permissions in the following order: racwdxltmeop.

Examples of valid permission settings include rw, rd, rl, wd, wl, and rl. You can't specify a permission more than once.

To ensure parity with existing Azure Storage tools, OneLake uses the same permission format as Azure Storage. OneLake evaluates the permissions granted to a SAS in signedPermissions, the permissions of the signing identity in Fabric, and any OneLake data access roles, if applicable. Remember that some operations, such as setting permissions or deleting workspaces, aren't permitted on OneLake via Azure Storage APIs generally, and therefore granting that permission (sp=op) won't allow a OneLake SAS to perform those operations.

Specify the signature

The signature (sig) field is used to authorize a request made by a client 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 an HMAC that's computed over the string-to-sign and key by using the SHA256 algorithm, and then encoded by using bBase65 encoding.

To construct the signature string of a user delegation SAS, create the string-to-sign from the fields made by the request, encode the string as UTF-8, and then compute the signature by using the HMAC-SHA256 algorithm. The fields that are included in the string-to-sign must be URL-decoded.

The fields required in the string-to-sign depend on the service version that's used for authorization (sv) field. The following section describes the string-to-sign configurations for versions that support OneLake SASs.

Version 2020-12-06 and later

StringToSign =  signedPermissions + "\n" +
                signedStart + "\n" +
                signedExpiry + "\n" +
                canonicalizedResource + "\n" +
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +
                signedProtocol + "\n" +
                signedVersion + "\n" +
                signedResource + "\n" +
                signedSnapshotTime + "\n" +
                signedEncryptionScope + "\n" +
                rscc + "\n" +
                rscd + "\n" +
                rsce + "\n" +
                rscl + "\n" +
                rsct

Version 2020-01-10

StringToSign =  signedPermissions + "\n" +
                signedStart + "\n" +
                signedExpiry + "\n" +
                canonicalizedResource + "\n" +
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +
                signedProtocol + "\n" +
                signedVersion + "\n" +
                signedResource + "\n" +
                signedSnapshotTime + "\n" +
                rscc + "\n" +
                rscd + "\n" +
                rsce + "\n" +
                rscl + "\n" +
                rsct

Versions earlier than 2020-02-10

StringToSign =  signedPermissions + "\n" +  
                signedStart + "\n" +  
                signedExpiry + "\n" +  
                canonicalizedResource + "\n" +  
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +  
                signedProtocol + "\n" +  
                signedVersion + "\n" +  
                signedResource + "\n" +
                rscc + "\n" +
                rscd + "\n" +  
                rsce + "\n" +  
                rscl + "\n" +  
                rsct

Canonicalized resource

The canonicalizedResource portion of the string is a canonical path to the resource. It must include the OneLake endpoint and the resource name, and must be URL decoded. A OneLake path must include its workspace, and a directory path must include the number of subdirectories that correspond to the sdd parameter.

The following examples show how to convert your OneLake URL to the corresponding canonicalized resource. Remember that OneLake supports both DFS and Blob operations and endpoints, and that the account name for your OneLake is always onelake.

Blob File

URL = https://onelake.blob.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/sales.csv
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/sales.csv"

DFS Directory

URL = https://onelake.dfs.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/"

OneLake SAS example

The following example shows a OneLake SAS URI with a OneLake SAS token appended to it. The SAS token provides read and write permissions to the Files folder in the lakehouse.

https://onelake.blob.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/?sp=rw&st=2023-05-24T01:13:55Z&se=2023-05-24T09:13:55Z&skoid=<object-id>&sktid=<tenant-id>&skt=2023-05-24T01:13:55Z&ske=2023-05-24T09:13:55Z&sks=b&skv=2022-11-02&sv=2022-11-02&sr=d&sig=<signature>

Related content

• Create an Azure Storage user delegation SAS
• Request a user delegation key
• Get started with OneLake data access roles