fix anchor links; add certificate prework steps

Author: kgremban

articles/iot-hub/authenticate-authorize-x509.md

@@ -101,7 +101,7 @@ A successful device connection to IoT Hub completes the authentication process a
 
 ## Revoke a device certificate
 
-IoT Hub doesn't check certificate revocation lists from the certificate authority when authenticating devices with certificate-based authentication. If you have a device that needs to be blocked from connecting to IoT Hub because of a potentially compromised certificate, you should disable the device in the identity registry. For more information, see [Disable or delete a device in an IoT hub](./iot-hub-create-through-portal.md#disable-or-delete-a-device-in-an-iot-hub).
+IoT Hub doesn't check certificate revocation lists from the certificate authority when authenticating devices with certificate-based authentication. If you have a device that needs to be blocked from connecting to IoT Hub because of a potentially compromised certificate, you should disable the device in the identity registry. For more information, see [Disable or delete a device](./create-connect-device.md#disable-or-delete-a-device).
 
 ## Example scenario
 

articles/iot-hub/c2d-messaging-dotnet.md

@@ -45,7 +45,7 @@ You can find more information on cloud-to-device messages in [D2C and C2D Messag
 
 * An IoT hub in your Azure subscription. If you don't have a hub yet, you can follow the steps in [Create an IoT hub](iot-hub-create-through-portal.md).
 
-* A device registered in your IoT hub. If you haven't registered a device yet, register one in the [Azure portal](iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
+* A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in [Register a device](create-connect-device.md#register-a-device).
 
 * This article uses sample code from the [Azure IoT SDK for C#](https://github.com/Azure/azure-iot-sdk-csharp).
 

articles/iot-hub/c2d-messaging-java.md

@@ -45,7 +45,7 @@ To learn more about cloud-to-device messages, see [Send cloud-to-device messages
 
 * An IoT hub in your Azure subscription. If you don't have a hub yet, you can follow the steps in [Create an IoT hub](iot-hub-create-through-portal.md).
 
-* A device registered in your IoT hub. If you haven't registered a device yet, register one in the [Azure portal](iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
+* A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in [Register a device](create-connect-device.md#register-a-device).
 
 * This article uses sample code from the [Azure IoT SDK for Java](https://github.com/Azure/azure-iot-sdk-java).
 

articles/iot-hub/c2d-messaging-node.md

@@ -45,7 +45,7 @@ To learn more about cloud-to-device messages, see [Send cloud-to-device messages
 
 * An IoT hub in your Azure subscription. If you don't have a hub yet, you can follow the steps in [Create an IoT hub](iot-hub-create-through-portal.md).
 
-* A device registered in your IoT hub. If you haven't registered a device yet, register one in the [Azure portal](iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
+* A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in [Register a device](create-connect-device.md#register-a-device).
 
 * This article uses sample code from the [Azure IoT SDK for Node.js](https://github.com/Azure/azure-iot-sdk-node).
 

articles/iot-hub/c2d-messaging-python.md

@@ -43,7 +43,7 @@ To learn more about cloud-to-device messages, see [Send cloud-to-device messages
 
 * An IoT hub. Create one with the [CLI](iot-hub-create-using-cli.md) or the [Azure portal](iot-hub-create-through-portal.md).
 
-* A registered device. Register one in the [Azure portal](iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
+* A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in [Register a device](create-connect-device.md#register-a-device).
 
 * [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.
 

articles/iot-hub/create-connect-device.md

@@ -14,24 +14,44 @@ ms.date: 06/10/2024
 
 Create a device identity for your device to connect to Azure IoT Hub. This article introduces key tasks for managing a device identity including registering the device, collecting its connection information, and then deleting or disabling a device at the end of its lifecycle.
 
-## Register a new device in the IoT hub
+## Register a device
 
 In this section, you create a device identity in the [identity registry in your IoT hub](./iot-hub-devguide-identity-registry.md). A device can't connect to a hub unless it has a device identity.
 
 The IoT Hub identity registry only stores device identities to enable secure access to the IoT hub. It stores device IDs and keys to use as security credentials, and an enabled/disabled flag that you can use to disable access for an individual device.
 
 IoT Hub supports three methods for device authentication:
 
-* **Symmetric key** - When you register a new device, you can provide keys or IoT Hub will generate keys for you. Both the device and the IoT hub have a copy of the symmetric key that can be compared when the device connects.
-* **X.509 self-signed** - Also called thumbprint authentication, you upload a portion of the device's X.509 certificate to the IoT hub. When the device connects, it presents its certificate and the IoT hub can validate it against the portion it knows. For more information, see [Authenticate identities with X.509 certificates](./authenticate-authorize-x509.md).
-* **X.509 CA signed** - You upload and verify an X.509 certificate authority (CA) certificate to the IoT hub. The device has an X.509 certificate with the verified X.509 CA in its certificate chain of trust. When the device connects, it presents its full certificate chain and the IoT hub can validate it because it knows the X.509 CA. Multiple devices can authenticate against the same verified X.509 CA. For more information, see [Authenticate identities with X.509 certificates](./authenticate-authorize-x509.md).
+* **Symmetric key** - When you register a device, you can provide keys or IoT Hub will generate keys for you. Both the device and the IoT hub have a copy of the symmetric key that can be compared when the device connects.
+* **X.509 self-signed** - If your device has a self-signed X.509 certificate, then you need to give IoT Hub a version of the certificate for authentication. When you register a device, you upload a certificate *thumbprint*, which is a hash of the device's X.509 certificate. When the device connects, it presents its certificate and the IoT hub can validate it against the hash it knows. For more information, see [Authenticate identities with X.509 certificates](./authenticate-authorize-x509.md).
+* **X.509 CA signed** - If your device has a CA-signed X.509 certificate, then you can give IoT Hub a root or intermediate certificate in the signing chain for authentication. *This option is recommended for production scenarios.* Before you register a device, you upload and verify an X.509 certificate authority (CA) certificate to the IoT hub. The device has an X.509 certificate with the verified X.509 CA in its certificate chain of trust. When the device connects, it presents its full certificate chain and the IoT hub can validate it because it knows the X.509 CA. Multiple devices can authenticate against the same verified X.509 CA. For more information, see [Authenticate identities with X.509 certificates](./authenticate-authorize-x509.md).
+
+### Prepare certificates
+
+If you're using either of the X.509 certificate authentication methods, make sure your certificates are ready before registering a device.
+
+The tutorial [Create and upload certificates for testing](./tutorial-x509-test-certs.md) provides a good introduction for how to create CA-signed certificates and upload them to IoT Hub. After completing that tutorial, you're ready to register a device with **X.509 CA signed** authentication.
+
+If your device uses self-signed certificates, then you need two device certificates (a primary and a secondary certificate) on the device and thumbprints for both to upload to IoT Hub. One way to retrieve the thumbprint from a certificate is with the following OpenSSL command:
+
+```bash
+openssl x509 -in <certificate filename>.pem -text -fingerprint
+```
+
+The thumbprint is included in the output of the command. For example:
+
+```output
+SHA1 Fingerprint=D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12
+```
+
+### Add a device
 
 ### [Azure portal](#tab/portal)
 
 1. In the [Azure portal](https://portal.azure.com), navigate to your IoT hub.
 1. Select **Device management** > **Devices**, then select **Add Device** to add a device in your IoT hub.
 
-    :::image type="content" source="./media/iot-hub-include-create-device/create-identity-portal.png" alt-text="Screen capture that shows how to create a device identity in the portal." border="true":::
+    <!-- :::image type="content" source="./media/iot-hub-include-create-device/create-identity-portal.png" alt-text="Screen capture that shows how to create a device identity in the portal." border="true"::: -->
 
 1. In **Create a device**, provide the information for your new device identity:
 
@@ -40,10 +60,9 @@ IoT Hub supports three methods for device authentication:
    | **Device ID** |  | Provide a name for your new device. |
    | **Authentication type** |  | Select either **Symmetric key**, **X.509 self-signed**, or **X.509 CA signed**. |
    |  | **Auto-generate keys** | For **Symmetric key** authentication, check this box to have IoT Hub generate keys for your device. Or, uncheck this box and provide primary and secondary keys for your device. |
+   |  | **Primary thumbprint** and **Secondary thumbprint** | For **X.509 self-signed** authentication, provide the thumbprint hash from the device's primary and secondary certificates. |
 
-   1.  a name for your new device.
-
-   [!INCLUDE [iot-hub-pii-note-naming-device](iot-hub-pii-note-naming-device.md)]
+   [!INCLUDE [iot-hub-pii-note-naming-device](../../includes/iot-hub-pii-note-naming-device.md)]
 
 1. Select **Save**.
 
@@ -60,17 +79,17 @@ IoT Hub supports three methods for device authentication:
 
 1. After the device is created, open the device from the list in the **Devices** pane. Copy the value of **Primary connection string**. This connection string is used by device code to communicate with the IoT hub.
 
-    By default, the keys and connection strings are masked because they're sensitive information. If you click the eye icon, they're revealed. It's not necessary to reveal them to copy them with the copy button.
+   By default, the keys and connection strings are masked because they're sensitive information. If you click the eye icon, they're revealed. It's not necessary to reveal them to copy them with the copy button.
 
-    :::image type="content" source="./media/iot-hub-include-create-device/device-details.png" alt-text="Screen capture that shows the device connection string." border="true" lightbox="./media/iot-hub-include-create-device/device-details.png":::
+    <!-- :::image type="content" source="./media/iot-hub-include-create-device/device-details.png" alt-text="Screen capture that shows the device connection string." border="true" lightbox="./media/iot-hub-include-create-device/device-details.png"::: -->
 
 ### [Azure CLI](#tab/cli)
 
 ### [PowerShell](#tab/powershell)
 
 ---
 
-## Disable or delete a device in an IoT hub
+## Disable or delete a device
 
 If you want to keep a device in your IoT hub's identity registry, but want to prevent it from connecting then you can change its status to *disabled.*
 

articles/iot-hub/device-management-dotnet.md

@@ -30,7 +30,7 @@ This article shows you how to create:
 
 * An IoT hub. Create one with the [CLI](iot-hub-create-using-cli.md) or the [Azure portal](iot-hub-create-through-portal.md).
 
-* A registered device. Register one in the [Azure portal](iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
+* A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in [Register a device](create-connect-device.md#register-a-device).
 
 * Make sure that port 8883 is open in your firewall. The device sample in this article uses MQTT protocol, which 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).
 

articles/iot-hub/device-management-java.md

@@ -31,7 +31,7 @@ This article shows you how to create:
 
 * An IoT hub. Create one with the [CLI](iot-hub-create-using-cli.md) or the [Azure portal](iot-hub-create-through-portal.md).
 
-* A registered device. Register one in the [Azure portal](iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
+* A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in [Register a device](create-connect-device.md#register-a-device).
 
 * [Java SE Development Kit 8](/java/azure/jdk/). Make sure you select **Java 8** under **Long-term support** to get to downloads for JDK 8.
 

articles/iot-hub/device-management-node.md

@@ -28,7 +28,7 @@ This article shows you how to create:
 
 * An IoT hub. Create one with the [CLI](iot-hub-create-using-cli.md) or the [Azure portal](iot-hub-create-through-portal.md).
 
-* A registered device. Register one in the [Azure portal](iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
+* A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in [Register a device](create-connect-device.md#register-a-device).
 
 * Node.js version 10.0.x or later. [Prepare your development environment](https://github.com/Azure/azure-iot-sdk-node/tree/main/doc/node-devbox-setup.md) describes how to install Node.js for this article on either Windows or Linux.
 

articles/iot-hub/device-management-python.md

@@ -33,7 +33,7 @@ This article shows you how to create:
 
 * An IoT hub. Create one with the [CLI](iot-hub-create-using-cli.md) or the [Azure portal](iot-hub-create-through-portal.md).
 
-* A registered device. Register one in the [Azure portal](iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
+* A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in [Register a device](create-connect-device.md#register-a-device).
 
 * [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.