Merge pull request #222943 from diberry/diberry/0104-event-hub

Event hubs JS quickstart passwordless

Author: 19BMG00

articles/event-hubs/event-hubs-node-get-started-send.md

@@ -1,14 +1,14 @@
 ---
-title: Send or receive events from Azure Event Hubs using JavaScript (latest)
-description: This article provides a walkthrough for creating a JavaScript application that sends/receives events to/from Azure Event Hubs using the latest azure/event-hubs package.
+title: Send or receive events from Azure Event Hubs using JavaScript
+description: This article provides a walkthrough for creating a JavaScript application that sends/receives events to/from Azure Event Hubs.
 ms.topic: quickstart
-ms.date: 02/22/2022
+ms.date: 01/04/2023
 ms.devlang: javascript
-ms.custom: devx-track-js, mode-api
+ms.custom: devx-track-js, mode-api, passwordless-js
 ---
 
-# Send events to or receive events from event hubs by using JavaScript  (azure/event-hubs)
-This quickstart shows how to send events to and receive events from an event hub using the **azure/event-hubs** JavaScript package. 
+# Send events to or receive events from event hubs by using JavaScript
+This quickstart shows how to send events to and receive events from an event hub using the **@azure/event-hubs** npm package. 
 
 
 ## Prerequisites
@@ -17,35 +17,36 @@ If you are new to Azure Event Hubs, see [Event Hubs overview](event-hubs-about.m
 To complete this quickstart, you need the following prerequisites:
 
 - **Microsoft Azure subscription**. To use Azure services, including Azure Event Hubs, you need a subscription.  If you don't have an existing Azure account, you can sign up for a [free trial](https://azure.microsoft.com/free/) or use your MSDN subscriber benefits when you [create an account](https://azure.microsoft.com).
-- Node.js version 8.x or later. Download the latest [long-term support (LTS) version](https://nodejs.org).  
+- Node.js LTS. Download the latest [long-term support (LTS) version](https://nodejs.org).  
 - Visual Studio Code (recommended) or any other integrated development environment (IDE).  
-- An active Event Hubs namespace and event hub. To create them, do the following steps: 
+- **Create an Event Hubs namespace and an event hub**. The first step is to use the [Azure portal](https://portal.azure.com) to create a namespace of type Event Hubs, and obtain the management credentials your application needs to communicate with the event hub. To create a namespace and an event hub, follow the procedure in [this article](event-hubs-create.md). 
 
-   1. In the [Azure portal](https://portal.azure.com), create a namespace of type *Event Hubs*, and then obtain the management credentials that your application needs to communicate with the event hub. 
-   1. To create the namespace and event hub, follow the instructions at [Quickstart: Create an event hub by using the Azure portal](event-hubs-create.md).
-   1. Continue by following the instructions in this quickstart. 
-   1. To get the connection string for your Event Hub namespace, follow the instructions in [Get connection string](event-hubs-get-connection-string.md#azure-portal). Record the connection string to use later in this quickstart.
-- **Create an Event Hubs namespace and an event hub**. The first step is to use the [Azure portal](https://portal.azure.com) to create a namespace of type Event Hubs, and obtain the management credentials your application needs to communicate with the event hub. To create a namespace and an event hub, follow the procedure in [this article](event-hubs-create.md). Then, get the **connection string for the Event Hubs namespace** by following instructions from the article: [Get connection string](event-hubs-get-connection-string.md#azure-portal). You use the connection string later in this quickstart.
-
-### Install the npm package
+### Install the npm package(s) to send events
 To install the [Node Package Manager (npm) package for Event Hubs](https://www.npmjs.com/package/@azure/event-hubs), open a command prompt that has *npm* in its path, change the directory
-to the folder where you want to keep your samples, and then run this command:
+to the folder where you want to keep your samples.
+
+### [Passwordless (Recommended)](#tab/passwordless)
+
+Run these commands:
 
 ```shell
 npm install @azure/event-hubs
+npm install @azure/identity
 ```
 
-For the receiving side, you need to install two more packages. In this quickstart, you use Azure Blob storage to persist checkpoints so that the program doesn't read the events that it has already read. It performs metadata checkpoints on received messages at regular intervals in a blob. This approach makes it easy to continue receiving messages later from where you left off.
+### [Connection String](#tab/connection-string)
 
-Run the following commands:
+Run this command:
 
 ```shell
-npm install @azure/storage-blob
+npm install @azure/event-hubs
 ```
 
-```shell
-npm install @azure/eventhubs-checkpointstore-blob
-```
+---
+
+### Authenticate the app to Azure
+
+[!INCLUDE [event-hub-passwordless-template-tabbed](../../includes/passwordless/event-hub/event-hub-passwordless-template-tabbed-basic.md)]
 
 ## Send events
 
@@ -54,6 +55,55 @@ In this section, you create a JavaScript application that sends events to an eve
 1. Open your favorite editor, such as [Visual Studio Code](https://code.visualstudio.com).
 1. Create a file called *send.js*, and paste the following code into it:
 
+   ## [Passwordless (Recommended)](#tab/passwordless)
+
+    In the code, use real values to replace the following placeholders:
+    * `EVENT HUBS RESOURCE NAME`
+    * `EVENT HUB NAME`
+
+    ```javascript
+    const { EventHubProducerClient } = require("@azure/event-hubs");
+    const { DefaultAzureCredential } = require("@azure/identity");
+    
+    // Event hubs 
+    const eventHubsResourceName = "EVENT HUBS RESOURCE NAME";
+    const fullyQualifiedNamespace = `${eventHubsResourceName}.servicebus.windows.net`; 
+    const eventHubName = "EVENT HUB NAME";
+    
+    // Azure Identity - passwordless authentication
+    const credential = new DefaultAzureCredential();
+    
+    async function main() {
+    
+      // Create a producer client to send messages to the event hub.
+      const producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential);
+    
+      // Prepare a batch of three events.
+      const batch = await producer.createBatch();
+      batch.tryAdd({ body: "passwordless First event" });
+      batch.tryAdd({ body: "passwordless Second event" });
+      batch.tryAdd({ body: "passwordless Third event" });    
+    
+      // Send the batch to the event hub.
+      await producer.sendBatch(batch);
+    
+      // Close the producer client.
+      await producer.close();
+    
+      console.log("A batch of three events have been sent to the event hub");
+    }
+    
+    main().catch((err) => {
+      console.log("Error occurred: ", err);
+    });
+    ```
+
+   ## [Connection String](#tab/connection-string)
+
+    In the code, use real values to replace the following placeholders:
+    * `EVENT HUB NAME`
+    * `EVENT HUBS NAMESPACE CONNECTION STRING`
+
     ```javascript
     const { EventHubProducerClient } = require("@azure/event-hubs");
 
@@ -84,9 +134,9 @@ In this section, you create a JavaScript application that sends events to an eve
       console.log("Error occurred: ", err);
     });
     ```
-1. In the code, use real values to replace the following:
-    * `EVENT HUBS NAMESPACE CONNECTION STRING` 
-    * `EVENT HUB NAME`
+
+    ---
+
 1. Run `node send.js` to execute this file. This command sends a batch of three events to your event hub.
 1. In the Azure portal, verify that the event hub has received the messages. Refresh the page to update the chart. It might take a few seconds for it to show that the messages have been received.
 
@@ -112,15 +162,136 @@ To create an Azure storage account and a blob container in it, do the following
 
 1. [Create an Azure storage account](../storage/common/storage-account-create.md?tabs=azure-portal)  
 2. [Create a blob container in the storage account](../storage/blobs/storage-quickstart-blobs-portal.md#create-a-container)  
-3. [Get the connection string to the storage account](../storage/common/storage-configure-connection-string.md)
+3. Authenticate to the blob container
+    
+## [Passwordless (Recommended)](#tab/passwordless)
+
+[!INCLUDE [event-hub-storage-assign-roles](../../includes/passwordless/event-hub/event-hub-storage-assign-roles.md)]
+    
+## [Connection String](#tab/connection-string)
+
+[Get the connection string to the storage account](../storage/common/storage-configure-connection-string.md)
+
+Note the connection string and the container name. You'll use them in the receive code. 
+
+---
+
+### Install the npm packages to receive events
+
+For the receiving side, you need to install two more packages. In this quickstart, you use Azure Blob storage to persist checkpoints so that the program doesn't read the events that it has already read. It performs metadata checkpoints on received messages at regular intervals in a blob. This approach makes it easy to continue receiving messages later from where you left off.
+
+### [Passwordless (Recommended)](#tab/passwordless)
+
+Run these commands:
+
+```shell
+npm install @azure/storage-blob
+npm install @azure/eventhubs-checkpointstore-blob
+npm install @azure/identity
+```
+
+### [Connection String](#tab/connection-string)
+
+Run these commands:
+
+```shell
+npm install @azure/storage-blob
+npm install @azure/eventhubs-checkpointstore-blob
+```
 
-Be sure to record the connection string and container name for later use in the receive code.
+---
 
 ### Write code to receive events
 
 1. Open your favorite editor, such as [Visual Studio Code](https://code.visualstudio.com).
 1. Create a file called *receive.js*, and paste the following code into it:
 
+    ### [Passwordless (Recommended)](#tab/passwordless)
+
+    In the code, use real values to replace the following placeholders:
+    - `EVENT HUBS RESOURCE NAME`
+    - `EVENT HUB NAME`
+    - `STORAGE ACCOUNT NAME`
+    - `STORAGE CONTAINER NAME`
+
+    ```javascript
+    const { DefaultAzureCredential } = require("@azure/identity");
+    const { EventHubConsumerClient, earliestEventPosition  } = require("@azure/event-hubs");
+    const { ContainerClient } = require("@azure/storage-blob");    
+    const { BlobCheckpointStore } = require("@azure/eventhubs-checkpointstore-blob");
+    
+    // Event hubs 
+    const eventHubsResourceName = "EVENT HUBS RESOURCE NAME";
+    const fullyQualifiedNamespace = `${eventHubsResourceName}.servicebus.windows.net`; 
+    const eventHubName = "EVENT HUB NAME";
+    const consumerGroup = "$Default"; // name of the default consumer group
+    
+    // Azure Storage 
+    const storageAccountName = "STORAGE ACCOUNT NAME";
+    const storageContainerName = "STORAGE CONTAINER NAME";
+    const baseUrl = `https://${storageAccountName}.blob.core.windows.net`;
+    
+    // Azure Identity - passwordless authentication
+    const credential = new DefaultAzureCredential();
+    
+    async function main() {
+    
+      // Create a blob container client and a blob checkpoint store using the client.
+      const containerClient = new ContainerClient(
+        `${baseUrl}/${storageContainerName}`,
+        credential
+      );  
+      const checkpointStore = new BlobCheckpointStore(containerClient);
+    
+      // Create a consumer client for the event hub by specifying the checkpoint store.
+      const consumerClient = new EventHubConsumerClient(consumerGroup, fullyQualifiedNamespace, eventHubName, credential, checkpointStore);
+    
+      // Subscribe to the events, and specify handlers for processing the events and errors.
+      const subscription = consumerClient.subscribe({
+          processEvents: async (events, context) => {
+            if (events.length === 0) {
+              console.log(`No events received within wait time. Waiting for next interval`);
+              return;
+            }
+    
+            for (const event of events) {
+              console.log(`Received event: '${event.body}' from partition: '${context.partitionId}' and consumer group: '${context.consumerGroup}'`);
+            }
+            // Update the checkpoint.
+            await context.updateCheckpoint(events[events.length - 1]);
+          },
+    
+          processError: async (err, context) => {
+            console.log(`Error : ${err}`);
+          }
+        },
+        { startPosition: earliestEventPosition }
+      );
+    
+      // After 30 seconds, stop processing.
+      await new Promise((resolve) => {
+        setTimeout(async () => {
+          await subscription.close();
+          await consumerClient.close();
+          resolve();
+        }, 30000);
+      });
+    }
+    
+    main().catch((err) => {
+      console.log("Error occurred: ", err);
+    });
+    ```
+
+    ### [Connection String](#tab/connection-string)
+
+
+    In the code, use real values to replace the following placeholders:
+    - `EVENT HUBS NAMESPACE CONNECTION STRING`
+    - `EVENT HUB NAME`
+    - `STORAGE CONNECTION STRING`
+    - `STORAGE CONTAINER NAME`
+
     ```javascript
     const { EventHubConsumerClient, earliestEventPosition  } = require("@azure/event-hubs");
     const { ContainerClient } = require("@azure/storage-blob");    
@@ -129,8 +300,8 @@ Be sure to record the connection string and container name for later use in the
     const connectionString = "EVENT HUBS NAMESPACE CONNECTION STRING";    
     const eventHubName = "EVENT HUB NAME";
     const consumerGroup = "$Default"; // name of the default consumer group
-    const storageConnectionString = "AZURE STORAGE CONNECTION STRING";
-    const containerName = "BLOB CONTAINER NAME";
+    const storageConnectionString = "STORAGE CONNECTION STRING";
+    const containerName = "STORAGE CONTAINER NAME";
     
     async function main() {
       // Create a blob container client and a blob checkpoint store using the client.
@@ -176,11 +347,10 @@ Be sure to record the connection string and container name for later use in the
       console.log("Error occurred: ", err);
     });
     ```
-1. In the code, use real values to replace the following values:
-    - `EVENT HUBS NAMESPACE CONNECTION STRING`
-    - `EVENT HUB NAME`
-    - `AZURE STORAGE CONNECTION STRING`
-    - `BLOB CONTAINER NAME`
+
+    ---
+
+
 1. Run `node receive.js` in a command prompt to execute this file. The window should display messages about received events.
 
     ```

includes/passwordless/event-hub/event-hub-assign-roles-basic.md

@@ -0,0 +1,65 @@
+---
+title: "include file"
+description: "include file"
+services: storage
+author: alexwolfmsft
+ms.service: storage
+ms.topic: include
+ms.date: 09/09/2022
+ms.author: alexwolf
+ms.custom: include file
+---
+
+When developing locally, make sure that the user account that connects to Azure Event Hubs has the correct permissions. You'll need the [Azure Event Hubs Data Owner](../../../articles/role-based-access-control/built-in-roles.md#azure-event-hubs-data-owner) role in order to send and receive messages. To assign yourself this role, you'll need the User Access Administrator role, or another role that includes the `Microsoft.Authorization/roleAssignments/write` action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. Learn more about the available scopes for role assignments on the [scope overview](/azure/role-based-access-control/scope-overview) page.
+
+The following example assigns the `Azure Event Hubs Data Owner` role to your user account, which provides full access to Azure Event Hubs resources. In a real scenario, follow the [Principle of Least Privilege](/azure/active-directory/develop/secure-least-privileged-access) to give users only the minimum permissions needed for a more secure production environment.
+
+### Azure built-in roles for Azure Event Hubs
+For Azure Event Hubs, the management of namespaces and all related resources through the Azure portal and the Azure resource management API is already protected using the Azure RBAC model. Azure provides the below Azure built-in roles for authorizing access to an Event Hubs namespace:
+
+- [Azure Event Hubs Data Owner](../../../articles/role-based-access-control/built-in-roles.md#azure-event-hubs-data-owner): Enables data access to Event Hubs namespace and its entities (queues, topics, subscriptions, and filters)
+- [Azure Event Hubs Data Sender](../../../articles/role-based-access-control/built-in-roles.md#azure-event-hubs-data-sender): Use this role to give the sender access to Event Hubs namespace and its entities.
+- [Azure Event Hubs Data Receiver](../../../articles/role-based-access-control/built-in-roles.md#azure-event-hubs-data-receiver): Use this role to give the receiver access to Event Hubs namespace and its entities.
+
+If you want to create a custom role, see [Rights required for Event Hubs operations](../../../articles/service-bus-messaging/service-bus-sas.md#rights-required-for-service-bus-operations).
+
+> [!IMPORTANT]
+> In most cases, it will take a minute or two for the role assignment to propagate in Azure. In rare cases, it may take up to eight minutes. If you receive authentication errors when you first run your code, wait a few moments and try again.
+
+### [Azure portal](#tab/roles-azure-portal)
+
+1. In the Azure portal, locate your Event Hubs namespace using the main search bar or left navigation.
+
+2. On the overview page, select **Access control (IAM)** from the left-hand menu.	
+
+3. On the **Access control (IAM)** page, select the **Role assignments** tab.
+
+4. Select **+ Add** from the top menu and then **Add role assignment** from the resulting drop-down menu.
+
+    :::image type="content" source="media/event-hub-assign-roles/add-role.png" alt-text="A screenshot showing how to assign a role.":::    
+
+5. Use the search box to filter the results to the desired role. For this example, search for `Azure Event Hubs Data Owner` and select the matching result. Then choose **Next**.
+
+6. Under **Assign access to**, select **User, group, or service principal**, and then choose **+ Select members**.
+
+7. In the dialog, search for your Azure AD username (usually your *user@domain* email address) and then choose **Select** at the bottom of the dialog. 
+
+8. Select **Review + assign** to go to the final page, and then **Review + assign** again to complete the process.
+
+### [Azure CLI](#tab/roles-azure-cli)
+
+To assign a role at the resource level using the Azure CLI, you first must retrieve the resource ID using the `az servicebus namespace show` command. You can filter the output properties using the `--query` parameter. 
+
+```azurecli
+az servicebus namespace show -g '<your-event-hub-resource-group>' -n '<your-event-hub-name> --query id
+```
+
+Copy the output `Id` from the preceding command. You can then assign roles using the [az role](/cli/azure/role) command of the Azure CLI.
+
+```azurecli
+az role assignment create --assignee "<user@domain>" \
+--role "Azure Event Hubs Data Owner" \
+--scope "<your-resource-id>"
+```
+
+---