Merge pull request #292512 from gsteve88/add-cert-device-twins

Updated to add cert authentication

Author: prmerger-automator[bot]

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

@@ -38,17 +38,11 @@ This article shows you how to develop two types of applications:
 
 ## Prerequisites
 
-* **An IoT hub**. Some SDK calls require the IoT Hub primary connection string, so make a note of the connection string.
+* An IoT hub
 
-* **A registered device**. Some SDK calls require the device primary connection string, so make a note of the connection string.
+* A registered device
 
-* If your application uses the MQTT protocol, make sure that **port 8883** is open in your firewall. The MQTT protocol communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see [Connecting to IoT Hub (MQTT)](../iot/iot-mqtt-connect-to-iot-hub.md#connecting-to-iot-hub).
-
-* Language SDK requirements:
-  * **.NET SDK** - Requires Visual Studio.
-  * **Python SDK** - [Python version 3.7 or later](https://www.python.org/downloads/) is recommended. Make sure to use the 32-bit or 64-bit installation as required by your setup. When prompted during the installation, make sure to add Python to your platform-specific environment variable.
-  * **Java** - Requires [Java SE Development Kit 8](/azure/developer/java/fundamentals/). Make sure you select **Java 8** under **Long-term support** to navigate to downloads for JDK 8.
-  * **Node.js** - Requires Node.js version 10.0.x or later.
+* If your application uses the MQTT protocol, make sure that port 8883 is open in your firewall. The MQTT protocol communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see [Connecting to IoT Hub (MQTT)](../iot/iot-mqtt-connect-to-iot-hub.md#connecting-to-iot-hub).
 
 :::zone pivot="programming-language-csharp"
 

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

@@ -7,10 +7,12 @@ ms.author: kgremban
 ms.service: azure-iot-hub
 ms.devlang: csharp
 ms.topic: include
-ms.date: 07/12/2024
+ms.date: 12/31/2024
 ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
 ---
 
+  * Requires Visual Studio
+
 ## Overview
 
 This article describes how to use the [Azure IoT SDK for .NET](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/readme.md) to create device and backend service application code for device twins.
@@ -25,13 +27,26 @@ This section describes how to use device application code to:
 * Update reported device twin properties
 * Create a desired property update callback handler
 
-[!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
-
-### Add device NuGet Package
+### Required device NuGet package
 
 Device client applications written in C# require the **Microsoft.Azure.Devices.Client** NuGet package.
 
-### Connect to a device
+Add this `using` statement to use the device library.
+
+```csharp
+using Microsoft.Azure.Devices.Client;
+```
+
+### Connect a device to IoT Hub
+
+A device app can authenticate with IoT Hub using the following methods:
+
+* Shared access key
+* X.509 certificate
+
+[!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
+
+#### Authenticate using a shared access key
 
 The [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class exposes all the methods required to interact with device twins from the device.
 
@@ -61,6 +76,10 @@ _deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString,
    TransportType.Mqtt);
 ```
 
+#### Authenticate using an X.509 certificate
+
+[!INCLUDE [iot-hub-howto-auth-device-cert-dotnet](iot-hub-howto-auth-device-cert-dotnet.md)]
+
 ### Retrieve a device twin and examine properties
 
 Call [GetTwinAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.gettwinasync?#microsoft-azure-devices-client-deviceclient-gettwinasync) to retrieve the current device twin properties. There are many [Twin](/dotnet/api/microsoft.azure.devices.shared.twin?) object [properties](/dotnet/api/microsoft.azure.devices.shared.twin?&#properties) that you can use to access specific areas of the `Twin` JSON data including `Properties`, `Status`, `Tags`, and `Version`.

includes/iot-hub-howto-device-twins-java.md

@@ -11,6 +11,8 @@ ms.date: 07/20/2024
 ms.custom: mqtt, devx-track-java, devx-track-extended-java
 ---
 
+  * Requires [Java SE Development Kit 8](/azure/developer/java/fundamentals/). Make sure you select **Java 8** under **Long-term support** to navigate to downloads for JDK 8.
+
 ## Overview
 
 This article describes how to use the [Azure IoT SDK for Java](https://github.com/Azure/azure-iot-sdk-java) to create device and backend service application code for device twins.
@@ -38,9 +40,18 @@ import com.microsoft.azure.sdk.iot.device.*;
 import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;
 ```
 
-### Connect to the device
+### Connect a device to IoT Hub
+
+A device app can authenticate with IoT Hub using the following methods:
+
+* Shared access key
+* X.509 certificate
+
+[!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
+
+#### Authenticate using a shared access key
 
-To connect to a device:
+To connect a device to IoT Hub:
 
 1. Use [IotHubClientProtocol](/java/api/com.microsoft.azure.sdk.iot.device.iothubclientprotocol) to choose a transport protocol. For example:
 
@@ -61,6 +72,10 @@ To connect to a device:
     client.open(true);
     ```
 
+#### Authenticate using an X.509 certificate
+
+[!INCLUDE [iot-hub-howto-auth-device-cert-java](iot-hub-howto-auth-device-cert-java.md)]
+
 ### Retrieve and view a device twin
 
 After opening the client connection, call [getTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-gettwin(com-microsoft-azure-sdk-iot-service-devicetwin-devicetwindevice)) to retrieve the current twin properties into a `Twin` object.

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

@@ -11,6 +11,8 @@ ms.date: 07/20/2024
 ms.custom: mqtt, devx-track-js
 ---
 
+  *  Requires Node.js version 10.0.x or later
+
 ## Overview
 
 This article describes how to use the [Azure IoT SDK for Node.js](https://github.com/Azure/azure-iot-sdk-node) to create device and backend service application code for device twins.
@@ -27,14 +29,29 @@ This section describes how to use the [azure-iot-device](/javascript/api/azure-i
 
 [!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
 
-### Install SDK packages
+### Install device 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
 ```
 
+### Connect a device to IoT Hub
+
+A device app can authenticate with IoT Hub using the following methods:
+
+* X.509 certificate
+* Shared access key
+
+[!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
+
+#### Authenticate using an X.509 certificate
+
+[!INCLUDE [iot-hub-howto-auth-device-cert-node](iot-hub-howto-auth-device-cert-node.md)]
+
+#### Authenticate using a shared access key
+
 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 twin data.
 
 ### Choose a transport protocol
@@ -245,7 +262,7 @@ This section describes how to create a backend application that:
 * Retrieves and updates a device twin
 * Creates a device twin query
 
-### Install service SDK packages
+### Install service SDK package
 
 Run this command to install **azure-iothub** on your development machine:
 

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

@@ -11,10 +11,26 @@ ms.date: 07/12/2024
 ms.custom: mqtt, devx-track-python, py-fresh-zinc
 ---
 
+  * Python SDK - [Python version 3.7 or later](https://www.python.org/downloads/) is recommended. Make sure to use the 32-bit or 64-bit installation as required by your setup. When prompted during the installation, make sure to add Python to your platform-specific environment variable.
+
 ## Overview
 
 This article describes how to use the [Azure IoT SDK for Python](https://github.com/Azure/azure-iot-sdk-python) to create device and backend service application code for device twins.
 
+## Install packages
+
+The **azure-iot-device** library must be installed to create device applications.
+
+```cmd/sh
+pip install azure-iot-device
+```
+
+The **azure-iot-hub** library must be installed to create backend service applications.
+
+```cmd/sh
+pip install azure-iot-hub
+```
+
 ## Create a device application
 
 Device applications can read and write twin reported properties, and be notified of desired twin property changes that are set by a backend application or IoT Hub.
@@ -26,30 +42,45 @@ This section describes how to create device application code that:
 * Retrieves a device twin and examine reported properties
 * Patch reported device twin properties
 
+### Device import statement
+
+Add this code to import the `IoTHubDeviceClient` functions from the azure.iot.device SDK.
+
+```python
+from azure.iot.device import IoTHubDeviceClient
+```
+
+### Connect a device to IoT Hub
+
+A device app can authenticate with IoT Hub using the following methods:
+
+* Shared access key
+* X.509 certificate
+
 [!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
 
-### Connect to a device
+#### Authenticate using a shared access key
 
-This section shows how to connect an application to a device using a device primary key that includes a shared access key.
+To connect a device to IoT Hub:
 
-To connect an application to a device:
-1. Call [create_from_connection_string](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-create-from-connection-string) to add the device connection string
-1. Call [connect](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-connect) to connect the device client to an Azure IoT hub
+1. Call [create_from_connection_string](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-create-from-connection-string) to add the device primary connection string.
+1. Call [connect](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-connect) to connect the device client.
 
-```python
-# import the device client library
-import asyncio
-from azure.iot.device.aio import IoTHubDeviceClient
+For example:
 
-# substitute the device connection string in conn_str
-# and add it to the IoTHubDeviceClient object
-conn_str = "{IOT hub device connection string}"
-device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)
+```python
+# Add your IoT hub primary connection string
+CONNECTION_STRING = "{Device primary connection string}"
+device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)
 
-# connect the application to the device
-await device_client.connect()
+# Connect the client
+device_client.connect()
 ```
 
+#### Authenticate using an X.509 certificate
+
+[!INCLUDE [iot-hub-howto-auth-device-cert-python](iot-hub-howto-auth-device-cert-python.md)]
+
 ### Retrieve a device twin and examine reported properties
 
 You can retrieve and examine device twin information including tags and properties. The device twin information retrieved matches device twin JSON-formatted data that you can view for a device in the Azure portal.