Skip to content

Commit 79d7859

Browse files
BCS2022BCS2022
authored
Merge pull request #204829 from diberry/diberry/0717-storage-sas-mi
Blob Storage - JS - SAS tokens
2 parents 17b7ebd + afada6a commit 79d7859

File tree

2 files changed

+161
-1
lines changed

2 files changed

+161
-1
lines changed

‎articles/storage/blobs/TOC.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -589,7 +589,11 @@ items:
589589
- name: Get started
590590
href: storage-blob-javascript-get-started.md
591591
- name: Work with SAS tokens
592-
href: storage-blob-account-delegation-sas-create-javascript.md
592+
items:
593+
- name: Account SAS
594+
href: storage-blob-account-delegation-sas-create-javascript.md
595+
- name: User SAS
596+
href: storage-blob-create-user-delegation-sas-javascript.md
593597
- name: Work with containers
594598
items:
595599
- name: Create a container

‎articles/storage/blobs/storage-blob-create-user-delegation-sas-javascript.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: Create user delegation SAS tokens - JavaScript
3+
titleSuffix: Azure Storage
4+
description: Create and use user delegation SAS tokens in a JavaScript application that works with Azure Blob Storage. This article helps you set up a project and authorizes access to an Azure Blob Storage endpoint.
5+
services: storage
6+
author: normesta
7+
8+
ms.service: storage
9+
ms.topic: how-to
10+
ms.date: 07/15/2022
11+
ms.author: normesta
12+
ms.subservice: blobs
13+
ms.custom: template-how-to, devx-track-js
14+
15+
---
16+
17+
# Create a user delegation SAS token with Azure Blob Storage and JavaScript
18+
19+
This article shows you how to create a user delegation SAS token in the Azure Blob Storage client library v12 for JavaScript. A [user delegation SAS](/rest/api/storageservices/delegate-access-with-shared-access-signature#types-of-shared-access-signatures), introduced with version 2018-11-09, is secured with Azure AD credentials and is supported for the Blob service only to:
20+
21+
* Grant access to an existing **container**.
22+
* Grant access to create, use, and delete **blobs**.
23+
24+
To create a user delegation SAS, a client must have permissions to call the [blobServiceClient.getUserDelegationKey](/javascript/api/@azure/storage-blob/blobserviceclient#@azure-storage-blob-blobserviceclient-getuserdelegationkey) operation. The key returned by this operation is used to sign the user delegation SAS. The security principal that calls this operation must be assigned an RBAC role that includes the Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action.
25+
26+
The permissions granted to a client who possesses the SAS are the intersection of the permissions that were granted to the security principal that requested the user delegation key and the permissions that were granted to the resource on the SAS token in the signed [permissions](/rest/api/storageservices/create-user-delegation-sas#specify-permissions) (sp) field. If a permission that's granted to the security principal via RBAC isn't also granted on the SAS token, that permission isn't granted to the client who attempts to use the SAS to access the resource.
27+
28+
The [sample code snippets](https://github.com/Azure-Samples/AzureStorageSnippets/tree/master/blobs/howto/JavaScript/NodeJS-v12/dev-guide) are available in GitHub as runnable Node.js files.
29+
30+
[Package (npm)](https://www.npmjs.com/package/@azure/storage-blob) | [Samples](../common/storage-samples-javascript.md?toc=%2fazure%2fstorage%2fblobs%2ftoc.json#blob-samples) | [API reference](/javascript/api/preview-docs/@azure/storage-blob) | [Library source code](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/storage/storage-blob) | [Give Feedback](https://github.com/Azure/azure-sdk-for-js/issues)
31+
32+
## Best practices for user delegation SAS tokens
33+
34+
Because anyone with the SAS token can use it to access the container and blobs, you should define the SAS token with the most restrictive permissions that still allow the token to complete the required tasks.
35+
36+
[Best practices for SAS tokens](../common/storage-sas-overview.md#best-practices-when-using-sas)
37+
38+
## Use the DefaultAzureCredential in Azure Cloud
39+
40+
To authenticate to Azure, _without secrets_, set up **managed identity**. This allows your code to use [DefaultAzureCredential](/javascript/api/overview/azure/identity-readme#defaultazurecredential).
41+
42+
To set up managed identity for the Azure cloud:
43+
44+
* Create a managed identity
45+
* Set the appropriate [Storage roles](/rest/api/storageservices/create-user-delegation-sas#assign-permissions-with-rbac) for the identity
46+
* Configure your Azure environment to work with your managed identity
47+
48+
When these two tasks are complete, use the DefaultAzureCredential instead of a connection string or account key. This allows all your environments to use the _exact same source code_ without the issue of using secrets in source code.
49+
50+
## Use the DefaultAzureCredential in local development
51+
52+
In your local development environment, your Azure identity (your personal or development account you use to sign in to [Azure portal](https://portal.azure.com)) needs to [authenticate to Azure](/javascript/api/overview/azure/identity-readme#authenticate-the-client-in-development-environment) to use the same code in local and cloud runtimes.
53+
54+
## Container: add required dependencies to your application
55+
56+
Include the required dependencies to create a container SAS token.
57+
58+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/list-blobs-from-container-sas-token.js" id="Snippet_Dependencies":::
59+
60+
## Container: get environment variables
61+
62+
The Blob Storage account name and container name are the minimum required values to create a container SAS token:
63+
64+
```
65+
// Get environment variables for DefaultAzureCredential
66+
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
67+
const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;
68+
```
69+
70+
## Create a SAS with DefaultAzureCredential
71+
72+
The following conceptual steps are required to create a SAS token with DefaultAzureCredential:
73+
74+
* Set up DefaultAzureCredential
75+
* Local development - use personal identity and set roles for storage
76+
* Azure cloud - create managed identity
77+
* Use DefaultAzureCredential to get the user delegation key with [UserDelegationKey](/rest/api/storageservices/create-user-delegation-sas)
78+
* Use the user delegation key to construct the SAS token with the appropriate fields with [generateBlobSASQueryParameters](/javascript/api/@azure/storage-blob#@azure-storage-blob-generateblobsasqueryparameters)
79+
80+
## Container: create SAS token with DefaultAzureCredential
81+
82+
With identity configured, use the following code to create **User delegation SAS token** for an existing account and container:
83+
84+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/list-blobs-from-container-sas-token.js" id="Snippet_CreateContainerSas" highlight="18, 25, 42":::
85+
86+
The preceding server code creates a flow of values in order to create the container SAS token:
87+
88+
* Create the [**BlobServiceClient**](/javascript/api/@azure/storage-blob/blobserviceclient) with the [_DefaultAzureCredential_](/javascript/api/@azure/identity/defaultazurecredential)
89+
* Use the [blobServiceClient.getUserDelegationKey](/javascript/api/@azure/storage-blob/blobserviceclient#@azure-storage-blob-blobserviceclient-getuserdelegationkey) operation to create a [**UserDelegationKey**](/rest/api/storageservices/create-user-delegation-sas)
90+
* Use the key to create the [**SAS token**](../common/storage-sas-overview.md?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json#sas-token) string with [generateBlobSASQueryParameters](/javascript/api/@azure/storage-blob#@azure-storage-blob-generateblobsasqueryparameters)
91+
92+
Once you're created the container SAS token, you can provide it to the client that will consume the token. The client can then use it to list the blobs in a container. A [client code example](#container-use-sas-token) shows how to test the SAS as a consumer.
93+
94+
## Container: use SAS token
95+
96+
Once the container SAS token is created, use the token. As an example of using the SAS token, you:
97+
98+
* Construct a full URL including container name and query string. The query string is the SAS token.
99+
* Create a [ContainerClient](/javascript/api/@azure/storage-blob/containerclient#@azure-storage-blob-containerclient-constructor-2) with the container URL.
100+
* Use the client: in this example, list blobs in the container with [listBlobsFlat](/javascript/api/@azure/storage-blob/containerclient#@azure-storage-blob-containerclient-listblobsflat).
101+
102+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/list-blobs-from-container-sas-token.js" id="Snippet_ListBlobs" highlight="10, 14, 19":::
103+
104+
## Blob: add required dependencies to your application
105+
106+
Include the required dependencies to create n blob SAS token.
107+
108+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-blob-sas-token.js" id="Snippet_Dependencies":::
109+
110+
## Blob: get environment variables
111+
112+
The Blob Storage account name and container name are the minimum required values to create a blob SAS token:
113+
114+
```
115+
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
116+
const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;
117+
```
118+
119+
When you need to create a blob SAS token, you need to have the blob name to create the SAS token. That will be predetermined such as a random blob name, a user-submitted blob name, or a name generated from your application.
120+
121+
```javascript
122+
// Create random blob name for text file
123+
const blobName = `${(0|Math.random()*9e6).toString(36)}.txt`;
124+
```
125+
126+
## Blob: create SAS token with DefaultAzureCredential
127+
128+
With identity configured, use the following code to create **User delegation SAS token** for an existing account and container:
129+
130+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-blob-sas-token.js" id="Snippet_CreateBlobSas" highlight="18, 25, 43":::
131+
132+
The preceding code creates a flow of values in order to create the container SAS token:
133+
134+
* Create the [**BlobServiceClient**](/javascript/api/@azure/storage-blob/blobserviceclient) with [_DefaultAzureCredential_](/javascript/api/@azure/identity/defaultazurecredential)
135+
* Use the [blobServiceClient.getUserDelegationKey](/javascript/api/@azure/storage-blob/blobserviceclient#@azure-storage-blob-blobserviceclient-getuserdelegationkey) operation to create a [**UserDelegationKey**](/rest/api/storageservices/create-user-delegation-sas)
136+
* Use the key to create the [**SAS token**](../common/storage-sas-overview.md?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json#sas-token) string. If the blob name wasn't specified in the options, the SAS token is a container token.
137+
138+
Once you're created the blob SAS token, you can provide it to the client that will consume the token. The client can then use it to upload a blob. A [client code example](#blob-use-sas-token) shows how to test the SAS as a consumer.
139+
140+
## Blob: use SAS token
141+
142+
Once the blob SAS token is created, use the token. As an example of using the SAS token, you:
143+
144+
* Construct a full URL including container name, blob name and query string. The query string is the SAS token.
145+
* Create a [BlockBlobClient](/javascript/api/@azure/storage-blob/blockblobclient) with the container URL.
146+
* Use the client: in this example, upload blob with [upload](/javascript/api/@azure/storage-blob/blockblobclient#@azure-storage-blob-blockblobclient-upload).
147+
148+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-blob-sas-token.js" id="Snippet_UploadToBlob" highlight="9, 13, 16":::
149+
150+
151+
## See also
152+
153+
- [Types of SAS tokens](../common/storage-sas-overview.md?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json)
154+
- [API reference](/javascript/api/@azure/storage-blob/)
155+
- [Library source code](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/storage/storage-blob)
156+
- [Give Feedback](https://github.com/Azure/azure-sdk-for-js/issues)

0 commit comments

Comments
 (0)