Merge pull request #292611 from gsteve88/add-cert-module-twins

Add certificate authentication steps to how-to module twins

Author: denrea

articles/iot-hub/how-to-module-twins.md

@@ -8,7 +8,7 @@ manager: lizross
 ms.service: azure-iot-hub
 ms.devlang: csharp
 ms.topic: how-to
-ms.date: 09/03/2024
+ms.date: 01/03/2025
 zone_pivot_groups: iot-hub-howto-c2d-2
 ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
 ---

includes/iot-hub-howto-auth-device-cert-node.md

@@ -15,15 +15,29 @@ The X.509 certificate is attached to the device-to-IoT Hub connection transport.
 
 To configure a device-to-IoT Hub connection using an X.509 certificate:
 
-1. Call [fromConnectionString](/javascript/api/azure-iothub/client?#azure-iothub-client-fromconnectionstring) to add the device connection string and transport type. Add `x509=true` to the device connection string to indicate that a certificate is added to `DeviceClientOptions`. For example: `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`.
+1. Call [fromConnectionString](/javascript/api/azure-iothub/client?#azure-iothub-client-fromconnectionstring) to add the device or identity module connection string, and transport type to the `Client` object. Add `x509=true` to the connection string to indicate that a certificate is added to `DeviceClientOptions`. For example:
+
+   * A **device** connection string:
+   
+     `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
+   * An **identity module** connection string:
+   
+     `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
+
 1. Configure a JSON variable with certificate details and pass it to [DeviceClientOptions](/javascript/api/azure-iot-device/deviceclientoptions).
 1. Call [setOptions](/javascript/api/azure-iot-device/client?#azure-iot-device-client-setoptions-1) to add an X.509 certificate and key (and optionally, passphrase) to the client transport.
 1. Call [open](/javascript/api/azure-iothub/client?#azure-iothub-client-open) to open the connection from the device to IoT Hub.
 
-This example shows certificate configuration information within a JSON variable. The certification configuration `options` are passed to `setOptions` and the connection is opened using `open`.
+This example shows certificate configuration information within a JSON variable. The certification configuration `clientOptions` are passed to `setOptions`, and the connection is opened using `open`.
 
 ```javascript
-var options = {
+const Client = require('azure-iot-device').Client;
+const Protocol = require('azure-iot-device-mqtt').Mqtt;
+// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
+const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
+const client = Client.fromConnectionString(connectionString, Protocol);
+
+var clientOptions = {
    cert: myX509Certificate,
    key: myX509Key,
    passphrase: passphrase,
@@ -33,7 +47,8 @@ var options = {
      }
    }
  }
- client.setOptions(options, callback);
+
+ client.setOptions(clientOptions);
  client.open(connectCallback);
 ```
 

includes/iot-hub-howto-module-twins-dotnet.md

@@ -7,7 +7,7 @@ ms.author: kgremban
 ms.service: iot-hub
 ms.devlang: csharp
 ms.topic: include
-ms.date: 11/19/2024
+ms.date: 1/3/2025
 ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
 ---
 
@@ -55,6 +55,9 @@ private static ModuleClient _moduleClient = null;
 _moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);
 ```
 
+> [!NOTE]
+> C#/.NET does not support connection of a device app to an IoT Hub module identity twin using a certificate.
+
 ### Retrieve a module identity twin and examine properties
 
 Call [GetTwinAsync](/dotnet/api/microsoft.azure.devices.client.moduleclient.gettwinasync?#microsoft-azure-devices-client-moduleclient-gettwinasync) to retrieve the current module identity twin properties into a [Twin](/dotnet/api/microsoft.azure.devices.shared.twin?) object.

includes/iot-hub-howto-module-twins-node.md

@@ -7,7 +7,7 @@ ms.author: kgremban
 ms.service: iot-hub
 ms.devlang: nodejs
 ms.topic: include
-ms.date: 11/19/2024
+ms.date: 1/3/2025
 ms.custom: mqtt, devx-track-js
 ---
 
@@ -25,19 +25,28 @@ This section describes how to use the [azure-iot-device](/javascript/api/azure-i
 * Update module identity reported twin properties
 * Receive notice of module identity twin desired property changes
 
-[!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
+The [azure-iot-device](/javascript/api/azure-iot-device) package contains objects that interface with IoT devices. The [Twin](/javascript/api/azure-iot-device/twin) class includes twin-specific objects. This section describes `Client` class code that is used to read and write device module identity twin data.
 
-### Install SDK packages
+### Install SDK package
 
 Run this command to install the **azure-iot-device** device SDK on your development machine:
 
 ```cmd/sh
 npm install azure-iot-device --save
 ```
 
-The [azure-iot-device](/javascript/api/azure-iot-device) package contains objects that interface with IoT devices. The [Twin](/javascript/api/azure-iot-device/twin) class includes twin-specific objects. This section describes `Client` class code that is used to read and write device module identity twin data.
+### Connect a device to IoT Hub
+
+A device app can authenticate with IoT Hub using the following methods:
+
+* Shared access key
+* X.509 certificate
 
-### Choose a transport protocol
+[!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
+
+#### Authenticate using a shared access key
+
+##### Choose a transport protocol
 
 The `Client` object supports these protocols:
 
@@ -57,7 +66,7 @@ npm install azure-iot-device-amqp --save
 
 For more information about the differences between MQTT, AMQP, and HTTPS support, see [Cloud-to-device communications guidance](../articles/iot-hub/iot-hub-devguide-c2d-guidance.md) and [Choose a device communication protocol](../articles/iot-hub/iot-hub-devguide-protocols.md).
 
-### Create a client object
+##### Create a client object
 
 Create a `Client` object using the installed package.
 
@@ -67,7 +76,7 @@ For example:
 const Client = require('azure-iot-device').Client;
 ```
 
-### Create a protocol object
+##### Create a protocol object
 
 Create a `Protocol` object using an installed transport package.
 
@@ -77,7 +86,7 @@ This example assigns the AMQP protocol:
 const Protocol = require('azure-iot-device-amqp').Amqp;
 ```
 
-### Add the device connection string and transport protocol
+##### Add the device connection string and transport protocol
 
 Call [fromConnectionString](/javascript/api/azure-iot-device/client?#azure-iot-device-client-fromconnectionstring) to supply device connection parameters:
 
@@ -92,7 +101,7 @@ const Protocol = require('azure-iot-device-mqtt').Amqp;
 let client = Client.fromConnectionString(deviceConnectionString, Protocol);
 ```
 
-### Open the connection to IoT Hub
+##### Open the connection to IoT Hub
 
 Use the [open](/javascript/api/azure-iot-device/client?#azure-iot-device-client-open) method to open a connection between an IoT device and IoT Hub.
 
@@ -107,6 +116,10 @@ client.open(function(err) {
 })
 ```
 
+#### Authenticate using an X.509 certificate
+
+[!INCLUDE [iot-hub-howto-auth-device-cert-node](iot-hub-howto-auth-device-cert-node.md)]
+
 ### Retrieve a module identity twin and examine reported properties
 
 Call [getTwin](/javascript/api/azure-iot-device/client?#azure-iot-device-client-gettwin-1) to retrieve current module identity twin information into a [Twin](/javascript/api/azure-iot-device/twin) object.

includes/iot-hub-howto-module-twins-python.md

@@ -80,6 +80,9 @@ device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)
 await device_client.connect()
 ```
 
+> [!NOTE]
+> Python does not support connection of a device app to an IoT Hub module identity twin using a certificate.
+
 ### Retrieve a module identity twin and examine properties
 
 Call [get_twin](/python/api/azure-iot-device/azure.iot.device.iothubmoduleclient?#azure-iot-device-iothubmoduleclient-get-twin) to retrieve the module identity twin from the Azure IoT Hub service. The twin information is placed into a variable that can be examined.