New content for Node.js Entra include file

Author: gsteve88

includes/iot-hub-howto-connect-service-iothub-entra-node.md

@@ -11,44 +11,84 @@ ms.manager: lizross
 ms.date: 11/06/2024
 ---
 
+A backend app that uses Microsoft Entra must successfully authenticate and obtain a security token credential before connecting to IoT Hub. This token is passed to a IoT Hub connection method. For general information about setting up and using Microsoft Entra for IoT Hub, see [Control access to IoT Hub by using Microsoft Entra ID](/azure/iot-hub/authenticate-authorize-azure-ad).
+
 For an overview of Node.js SDK authentication, see:
 
 * [Getting started with user authentication on Azure](/azure/developer/javascript/how-to/with-authentication/getting-started)
 * [Azure Identity client library for JavaScript](/javascript/api/overview/azure/identity-readme)
 
-##### Microsoft Entra token credential
-
-Use [DefaultAzureCredential](/javascript/api/@azure/identity/defaultazurecredential) to generate a token. The token is supplied to `fromTokenCredential`.
+##### Configure Microsoft Entra app
 
-To create required Microsoft Entra app parameters for `DefaultAzureCredential`, create a Microsoft Entra app registration that contains your selected authentication mechanism:
+You must set up a Microsoft Entra app that is configured for your preferred authentication credential. The app contains parameters such as client secret that are used by the backend application to authenticate. The available app authentication configurations are:
 
 * Client secret
 * Certificate
 * Federated identity credential
 
-For more information, see [Quickstart: Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app).
+Microsoft Entra apps may require specific role permissions depending on operations being performed. For example, [IoT Hub Twin Contributor](/azure/role-based-access-control/built-in-roles/internet-of-things#iot-hub-twin-contributor) is required to enable read and write access to a IoT Hub device and module twins. For more information, see [Manage access to IoT Hub by using Azure RBAC role assignment](/azure/iot-hub/authenticate-authorize-azure-ad?#manage-access-to-iot-hub-by-using-azure-rbac-role-assignment).
 
-Microsoft Entra apps may require permissions depending on operations performed. For example, [IoT Hub Twin Contributor](/azure/role-based-access-control/built-in-roles/internet-of-things#iot-hub-twin-contributor) is required to enable read and write access to a IoT Hub device and module twins. For more information, see [Azure built-in roles](/azure/role-based-access-control/built-in-roles#internet-of-things).
+For more information about setting up a Microsoft Entra app, see [Quickstart: Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app).
 
-##### Connect to IoT Hub
+##### Authenticate using DefaultAzureCredential
 
-Use [fromTokenCredential](/javascript/api/azure-iothub/registry?#azure-iothub-registry-fromtokencredential) to create a service connection to IoT Hub using a Microsoft Entra token credential.
+The easiest way to use Microsoft Entra to authenticate a backend application is to use [DefaultAzureCredential](/javascript/api/@azure/identity/defaultazurecredential), but it's recommended to use a different method in a production environment including a specific `TokenCredential` or pared-down `ChainedTokenCredential`. For simplicity, this section describes authentication using `DefaultAzureCredential` and Client secret.
+For more information about the pros and cons of using `DefaultAzureCredential`, see
+[Credential chains in the Azure Identity client library for JavaScript](/azure/developer/javascript/sdk/credential-chains#use-defaultazurecredential-for-flexibility)
 
-`fromTokenCredential` requires two parameters:
+[DefaultAzureCredential](/javascript/api/@azure/identity/defaultazurecredential) supports different authentication mechanisms and determines the appropriate credential type based on the environment it's executing in. It attempts to use multiple credential types in an order until it finds a working credential.
+
+Microsoft Entra requires this pakage:
 
-* hostname - The Azure service URL
-* tokenCredential - The Azure credential token
+```shell
+npm install --save @azure/identity
+```
 
-In this example, the Azure credential is obtained using `DefaultAzureCredential`. The Azure domain URL and credential are then supplied to `KeyClient`.
+In this example, Microsoft Entra app registration client secret, client ID, and tenant ID have been added to environment variables. These environment variables are used by `DefaultAzureCredential` to authenticate the application. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.
 
 ```javascript
 import { DefaultAzureCredential } from "@azure/identity";
-import { KeyClient } from "@azure/keyvault-keys";
 
-// Configure vault URL
-const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
 // Azure SDK clients accept the credential as a parameter
 const credential = new DefaultAzureCredential();
-// Create authenticated client
-const client = new KeyClient(vaultUrl, credential);
+```
+
+The resulting credential token can then be passed to a connection method to connect to IoT Hub method for any SDK client that accepts Microsoft Entra credentials:
+
+* [Registry](/javascript/api/azure-iothub/registry?#azure-iothub-registry-fromtokencredential)
+* [Client](/javascript/api/azure-iothub/client?#azure-iothub-client-fromtokencredential)
+* [JobClient](/javascript/api/azure-iothub/jobclient?#azure-iothub-jobclient-fromtokencredential)
+
+##### Connect to IoT Hub
+
+Use [fromTokenCredential](/javascript/api/azure-iothub/registry?#azure-iothub-registry-fromtokencredential) to create a service connection to IoT Hub using a Microsoft Entra token credential.
+
+`fromTokenCredential` requires two parameters:
+
+* The Azure service URL - The Azure service URL should be in the format `{Your Entra domain URL}.azure-devices.net` without a `https://` prefix. For example, `MyAzureDomain.azure-devices.net`.
+* The Azure credential token
+
+In this example, the Azure credential is obtained using `DefaultAzureCredential`. The Azure domain URL and credential are then supplied to `Registry.fromTokenCredential` to create the connection to IoT Hub.
+
+```javascript
+const { DefaultAzureCredential } = require("@azure/identity");
+
+let Registry = require('azure-iothub').Registry;
+
+// Define the client secret values
+clientSecretValue = 'xxxxxxxxxxxxxxx'
+clientID = 'xxxxxxxxxxxxxx'
+tenantID = 'xxxxxxxxxxxxx'
+
+// Set environment variables
+process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
+process.env['AZURE_CLIENT_ID'] = clientID;
+process.env['AZURE_TENANT_ID'] = tenantID;
+
+// Acquire a credential object
+const credential = new DefaultAzureCredential()
+
+// Create an instance of the IoTHub registry
+hostName = 'MyAzureDomain.azure-devices.net';
+let registry = Registry.fromTokenCredential(hostName,credential);
 ```

includes/iot-hub-howto-connect-service-iothub-entra-python.md

@@ -85,9 +85,9 @@ os.environ['AZURE_TENANT_ID'] = tenantID
 # Acquire a credential object
 credential = DefaultAzureCredential()
 
-# Use Entra to auth IoT Hub service
+# Use Entra to authorize IoT Hub service
 print("Connecting to IoTHubRegistryManager...")
 iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
-url="{Your Entra domain URL}.azure-devices.net",
+url="MyAzureDomain.azure-devices.net",
 token_credential=credential)
 ```