Skip to content

Commit 6d545ad

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #211614 from diberry/diberry/0916-storage-dev-guide-DAC
Blob Storage - JS - Dev Guide - passwordless auth
2 parents 868644e + 5d9622b commit 6d545ad

File tree

1 file changed

+35
-138
lines changed

1 file changed

+35
-138
lines changed

‎articles/storage/blobs/storage-blob-javascript-get-started.md

Lines changed: 35 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ ms.author: pauljewell
88

99
ms.service: storage
1010
ms.topic: how-to
11-
ms.date: 07/06/2022
11+
ms.date: 09/19/2022
1212

1313
ms.subservice: blobs
1414
ms.custom: template-how-to
@@ -44,7 +44,7 @@ The [BlobServiceClient](/javascript/api/@azure/storage-blob/blobserviceclient) o
4444

4545
## Set up your project
4646

47-
1. Open a command prompt and change into your project folder:
47+
1. Open a command prompt and change into your project folder. Change `YOUR-DIRECTORY` to your folder name:
4848

4949
```bash
5050
cd YOUR-DIRECTORY
@@ -68,195 +68,90 @@ The [BlobServiceClient](/javascript/api/@azure/storage-blob/blobserviceclient) o
6868
npm install @azure/identity
6969
```
7070
71-
1. In your `index.js` file, add the package:
71+
## Authenticate to Azure with passwordless credential
7272
73-
```javascript
74-
const { BlobServiceClient, StorageSharedKeyCredential } = require('@azure/storage-blob');
73+
Azure Active Directory (Azure AD) provides the most secure connection by managing the connection identity ([**managed identity**](../../active-directory/managed-identities-azure-resources/overview.md)). This **passwordless** functionality allows you to develop an application that doesn't require any secrets (keys or connection strings) stored in the code.
7574

76-
// optional but recommended - connect with managed identity (Azure AD)
77-
const { DefaultAzureCredential } = require('@azure/identity');
78-
```
75+
### Set up identity access to the Azure cloud
76+
77+
To connect to Azure without passwords, you need to set up an Azure identity or use an existing identity. Once the identity is set up, make sure to assign the appropriate roles to the identity.
7978

80-
## Connect with Azure AD
79+
To authorize passwordless access with Azure AD, you'll need to use an Azure credential. Which type of credential you need depends on where your application runs. Use this table as a guide.
8180
82-
Azure Active Directory (Azure AD) provides the most secure connection by managing the connection identity ([**managed identity**](../../active-directory/managed-identities-azure-resources/overview.md)). This functionality allows you to develop code that doesn't require any secrets (keys or connection strings) stored in the code or environment. Managed identity requires [**setup**](assign-azure-role-data-access.md?tabs=portal) for any identities such as developer (personal) or cloud (hosting) environments. You need to complete the setup before using the code in this section.
81+
|Environment|Method|
82+
|--|--|
83+
|Developer environment|[Visual Studio Code](/azure/developer/javascript/sdk/authentication/local-development-environment-developer-account?tabs=azure-portal%2Csign-in-vscode)|
84+
|Developer environment|[Service principal](../common/identity-library-acquire-token.md)|
85+
|Azure-hosted apps|[Azure-hosted apps setup](/azure/storage/blobs/authorize-managed-identity)|
86+
|On-premises|[On-premises app setup](/azure/storage/common/storage-auth-aad-app?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=dotnet)|
8387
84-
After you complete the setup, your Storage resource needs to have one or more of the following roles assigned to the identity resource you plan to connect with:
88+
### Set up storage account roles
8589
90+
Your storage resource needs to have one or more of the following [Azure RBAC](/azure/role-based-access-control/built-in-roles) roles assigned to the identity resource you plan to connect with. [Setup the Azure Storage roles](assign-azure-role-data-access.md?tabs=portal) for each identity you created in the previous step: Azure cloud, local development, on-premises.
91+
92+
After you complete the setup, each identity needs at least one of the appropriate roles:
93+
8694
* A [data access](../common/authorize-data-access.md) role - such as:
8795
* **Storage Blob Data Reader**
8896
* **Storage Blob Data Contributor**
8997
* A [resource](../common/authorization-resource-provider.md) role - such as:
9098
* **Reader**
9199
* **Contributor**
92100
93-
To authorize with Azure AD, you'll need to use an Azure credential. Which type of credential you need depends on where your application runs. Use this table as a guide.
94-
95-
| Where the application runs | Security principal | Guidance |
96-
|--|--|---|
97-
| Local machine (developing and testing) | User identity or service principal | [Use the Azure Identity library to get an access token for authorization](../common/identity-library-acquire-token.md) |
98-
| Azure | Managed identity | [Authorize access to blob data with managed identities for Azure resources](authorize-managed-identity.md) |
99-
| Servers or clients outside of Azure | Service principal | [Authorize access to blob or queue data from a native or web application](../common/storage-auth-aad-app.md?toc=/azure/storage/blobs/toc.json) |
100-
101-
Create a [DefaultAzureCredential](/javascript/api/overview/azure/identity-readme#defaultazurecredential) instance. Use that object to create a [BlobServiceClient](/javascript/api/@azure/storage-blob/blobserviceclient).
102-
103-
```javascript
104-
const { BlobServiceClient } = require('@azure/storage-blob');
105-
const { DefaultAzureCredential } = require('@azure/identity');
106-
require('dotenv').config()
107-
108-
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
109-
if (!accountName) throw Error('Azure Storage accountName not found');
110101
111-
const blobServiceClient = new BlobServiceClient(
112-
`https://${accountName}.blob.core.windows.net`,
113-
new DefaultAzureCredential()
114-
);
102+
### Connect with passwordless authentication to Azure
115103
116-
async function main(){
104+
Once your Azure storage account identity roles and your local environment are set up, create a JavaScript file which includes the [``@azure/identity``](https://www.npmjs.com/package/@azure/identity) package. Using the `DefaultAzureCredential` class provided by the Azure.Identity client library is the recommended approach for implementing passwordless connections to Azure services in your code, including Blob Storage.
117105
118-
// this call requires Reader role on the identity
119-
const serviceGetPropertiesResponse = await blobServiceClient.getProperties();
120-
console.log(`${JSON.stringify(serviceGetPropertiesResponse)}`);
106+
Create a [DefaultAzureCredential](/javascript/api/overview/azure/identity-readme#defaultazurecredential) instance. Use that object to create a [BlobServiceClient](/javascript/api/@azure/storage-blob/blobserviceclient).
121107
122-
}
108+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/connect-with-default-azure-credential.js":::
123109
124-
main()
125-
.then(() => console.log(`done`))
126-
.catch((ex) => console.log(`error: ${ex.message}`));
127-
```
110+
The `dotenv` package is used to read your storage account name from a `.env` file. This file should not be checked into source control. If you use a local service principal as part of your DefaultAzureCredential set up, any security information for that credential will also go into the `.env` file.
128111
129112
If you plan to deploy the application to servers and clients that run outside of Azure, you can obtain an OAuth token by using other classes in the [Azure Identity client library for JavaScript](/javascript/api/overview/azure/identity-readme) which derive from the [TokenCredential](/javascript/api/@azure/core-auth/tokencredential) class.
130113
131114
## Connect with an account name and key
132115
133116
Create a [StorageSharedKeyCredential](/javascript/api/@azure/storage-blob/storagesharedkeycredential) by using the storage account name and account key. Then use the StorageSharedKeyCredential to initialize a [BlobServiceClient](/javascript/api/@azure/storage-blob/blobserviceclient).
134117
135-
```javascript
136-
const { BlobServiceClient, StorageSharedKeyCredential } = require('@azure/storage-blob');
137-
require('dotenv').config()
138-
139-
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
140-
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
141-
if (!accountName) throw Error('Azure Storage accountName not found');
142-
if (!accountKey) throw Error('Azure Storage accountKey not found');
143-
144-
const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
145-
146-
const blobServiceClient = new BlobServiceClient(
147-
`https://${accountName}.blob.core.windows.net`,
148-
sharedKeyCredential
149-
);
118+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/connect-with-account-name-and-key.js":::
150119
151-
async function main(){
152-
const serviceGetPropertiesResponse = await blobServiceClient.getProperties();
153-
console.log(`${JSON.stringify(serviceGetPropertiesResponse)}`);
154-
}
155-
156-
main()
157-
.then(() => console.log(`done`))
158-
.catch((ex) => console.log(ex.message));
159-
```
120+
The `dotenv` package is used to read your storage account name and key from a `.env` file. This file should not be checked into source control.
160121
161122
For information about how to obtain account keys and best practice guidelines for properly managing and safeguarding your keys, see [Manage storage account access keys](../common/storage-account-keys-manage.md).
162123
163124
## Connect with a connection string
164125
165126
Create a [BlobServiceClient](/javascript/api/@azure/storage-blob/blobserviceclient) by using a connection string.
166127
167-
```javascript
168-
const { BlobServiceClient } = require('@azure/storage-blob');
169-
require('dotenv').config()
170-
171-
const connString = process.env.AZURE_STORAGE_CONNECTION_STRING;
172-
if (!connString) throw Error('Azure Storage Connection string not found');
173-
174-
const blobServiceClient = BlobServiceClient.fromConnectionString(connString);
128+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/connect-with-connection-string.js":::
175129
176-
async function main(){
177-
const serviceGetPropertiesResponse = await blobServiceClient.getProperties();
178-
console.log(`${JSON.stringify(serviceGetPropertiesResponse)}`);
179-
}
180-
181-
main()
182-
.then(() => console.log(`done`))
183-
.catch((ex) => console.log(ex.message));
184-
```
130+
The `dotenv` package is used to read your storage account connection string from a `.env` file. This file should not be checked into source control.
185131
186132
For information about how to obtain account keys and best practice guidelines for properly managing and safeguarding your keys, see [Manage storage account access keys](../common/storage-account-keys-manage.md).
187133
188-
## Object Authorization with a SAS token
134+
## Connect with a SAS token
189135
190136
Create a Uri to your resource by using the blob service endpoint and SAS token. Then, create a [BlobServiceClient](/javascript/api/@azure/storage-blob/blobserviceclient) with the Uri.
191137
192-
```javascript
193-
const { BlobServiceClient } = require('@azure/storage-blob');
194-
require('dotenv').config()
195-
196-
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
197-
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
198-
if (!accountName) throw Error('Azure Storage accountName not found');
199-
if (!sasToken) throw Error('Azure Storage accountKey not found');
200-
201-
const blobServiceUri = `https://${accountName}.blob.core.windows.net`;
202-
203-
const blobServiceClient = new BlobServiceClient(
204-
`${blobServiceUri}${sasToken}`,
205-
null
206-
);
138+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/connect-with-sas-token.js":::
207139
208-
async function main(){
209-
const serviceGetPropertiesResponse = await blobServiceClient.getProperties();
210-
console.log(`${JSON.stringify(serviceGetPropertiesResponse)}`);
211-
}
212-
213-
main()
214-
.then(() => console.log(`done`))
215-
.catch((ex) => console.log(`error: ${ex.message}`));
216-
```
140+
The `dotenv` package is used to read your storage account name and sas token from a `.env` file. This file should not be checked into source control.
217141
218142
To generate and manage SAS tokens, see any of these articles:
219143
220144
- [Grant limited access to Azure Storage resources using shared access signatures (SAS)](../common/storage-sas-overview.md?toc=/azure/storage/blobs/toc.json)
221145
222146
- [Create a service SAS for a container or blob](sas-service-create.md)
223147
224-
225-
226-
227148
## Connect anonymously
228149
229150
If you explicitly enable anonymous access, then you can connect to Blob Storage without authorization for your request. You can create a new BlobServiceClient object for anonymous access by providing the Blob storage endpoint for the account. This requires you to know the account and container names. To learn how to enable anonymous access, see [Configure anonymous public read access for containers and blobs](anonymous-read-access-configure.md).
230151
231-
```javascript
232-
const { BlobServiceClient, AnonymousCredential } = require('@azure/storage-blob');
233-
require('dotenv').config()
234-
235-
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
236-
if (!accountName) throw Error('Azure Storage accountName not found');
237-
238-
const blobServiceUri = `https://${accountName}.blob.core.windows.net`;
239-
240-
const blobServiceClient = new BlobServiceClient(
241-
blobServiceUri,
242-
new AnonymousCredential()
243-
);
244-
245-
async function getContainerProperties(){
246-
247-
// Access level: 'container'
248-
const containerName = `blob-storage-dev-guide-1`;
249-
250-
const containerClient = blobServiceClient.getContainerClient(containerName);
251-
const containerProperties = await containerClient.getProperties();
252-
console.log(JSON.stringify(containerProperties));
253-
254-
}
152+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/connect-with-anonymous-credential.js":::
255153
256-
getContainerProperties()
257-
.then(() => console.log(`done`))
258-
.catch((ex) => console.log(`error: ${ex.message}`));
259-
```
154+
The `dotenv` package is used to read your storage account name from a `.env` file. This file should not be checked into source control.
260155
261156
Each type of resource is represented by one or more associated JavaScript clients:
262157
@@ -271,10 +166,12 @@ The following guides show you how to use each of these clients to build your app
271166
| Guide | Description |
272167
|--|---|
273168
| [Create a container](storage-blob-container-create-javascript.md) | Create containers. |
169+
| [Get container's URL](storage-blob-get-url-javascript.md) | Get URL of container. |
274170
| [Delete and restore containers](storage-blob-container-delete-javascript.md) | Delete containers, and if soft-delete is enabled, restore deleted containers. |
275171
| [List containers](storage-blob-containers-list-javascript.md) | List containers in an account and the various options available to customize a listing. |
276172
| [Manage properties and metadata](storage-blob-container-properties-metadata-javascript.md) | Get and set properties and metadata for containers. |
277173
| [Upload blobs](storage-blob-upload-javascript.md) | Learn how to upload blobs by using strings, streams, file paths, and other methods. |
174+
| [Get blob's URL](storage-blob-get-url-javascript.md) | Get URL of blob. |
278175
| [Download blobs](storage-blob-download-javascript.md) | Download blobs by using strings, streams, and file paths. |
279176
| [Copy blobs](storage-blob-copy-javascript.md) | Copy a blob from one account to another account. |
280177
| [List blobs](storage-blobs-list-javascript.md) | List blobs in different ways. |

0 commit comments

Comments
 (0)