Register an IoT Edge device in IoT Hub

Applies to: yes icon IoT Edge 1.1 yes icon IoT Edge 1.2

This article provides the steps to register a new IoT Edge device in IoT Hub.

Every device that connects to an IoT hub has a device ID that's used to track cloud-to-device or device-to-cloud communications. You configure a device with its connection information, which includes the IoT hub hostname, the device ID, and the information the device uses to authenticate to IoT Hub.

The steps in this article walk through a process called manual provisioning, where you connect a single device to its IoT hub. For manual provisioning, you have two options for authenticating IoT Edge devices:

  • Symmetric key: When you create a new device identity in IoT Hub, the service creates two keys. You place one of the keys on the device, and it presents the key to IoT Hub when authenticating.

    This authentication method is faster to get started, but not as secure.

  • X.509 self-signed: You create two X.509 identity certificates and place them on the device. When you create a new device identity in IoT Hub, you provide thumbprints from both certificates. When the device authenticates to IoT Hub, it presents one certificate and IoT Hub verifies that the certificate matches its thumbprint.

    This authentication method is more secure, and recommended for production scenarios.

This article covers both authentication methods.

If you have many devices to set up and don't want to manually provision each one, use one of the following articles to learn how IoT Edge works with the IoT Hub Device Provisioning Service:

Prerequisites

A free or standard IoT hub in your Azure subscription.

Option 1: Register with symmetric keys

You can use several tools to register a new IoT Edge device in IoT Hub and retrieve its connection string, depending on your preference.

In your IoT hub in the Azure portal, IoT Edge devices are created and managed separately from IoT devices that are not edge enabled.

  1. Sign in to the Azure portal and navigate to your IoT hub.

  2. In the left pane, select IoT Edge from the menu, then select Add an IoT Edge device.

    Add an IoT Edge device from the Azure portal

  3. On the Create a device page, provide the following information:

    • Create a descriptive device ID.
    • Select Symmetric key as the authentication type.
    • Use the default settings to auto-generate authentication keys and connect the new device to your hub.
  4. Select Save.

Now that you have a device registered in IoT Hub, retrieve the connection string that you use to complete installation and provisioning of the IoT Edge runtime. Follow the steps later in this article to View registered devices and retrieve connection strings.

Option 2: Register with X.509 certificates

Manual provisioning with X.509 certificates requires IoT Edge version 1.0.10 or newer.

For X.509 certificate authentication, each device's authentication information is provided in the form of thumbprints taken from your device identity certificates. These thumbprints are given to IoT Hub at the time of device registration so that the service can recognize the device when it connects.

Create certificates and thumbprints

When you provision an IoT Edge device with X.509 certificates, you use what is called a device identity certificate. This certificate is only used for provisioning an IoT Edge device and authenticating the device with Azure IoT Hub. It is a leaf certificate that doesn't sign other certificates. The device identity certificate is separate from the certificate authority (CA) certificates that the IoT Edge device presents to modules or downstream devices for verification. For more information about how the CA certificates are used in IoT Edge devices, see Understand how Azure IoT Edge uses certificates.

You need the following files for manual provisioning with X.509:

  • Two of device identity certificates with their matching private key certificates in .cer or .pem formats.

    One set of certificate/key files is provided to the IoT Edge runtime. When you create device identity certificates, set the certificate common name (CN) with the device ID that you want the device to have in your IoT hub.

  • Thumbprints taken from both device identity certificates.

    Thumbprint values are 40-hex characters for SHA-1 hashes or 64-hex characters for SHA-256 hashes. Both thumbprints are provided to IoT Hub at the time of device registration.

If you don't have certificates available, you can Create demo certificates to test IoT Edge device features. Follow the instructions in that article to set up certificate creation scripts, create a root CA certificate, and then create two IoT Edge device identity certificates.

One way to retrieve the thumbprint from a certificate is with the following openssl command:

openssl x509 -in <certificate filename>.pem -text -fingerprint

Register a new device

You can use several tools to register a new IoT Edge device in IoT Hub and upload its certificate thumbprints.

In your IoT hub in the Azure portal, IoT Edge devices are created and managed separately from IoT devices that are not edge enabled.

  1. Sign in to the Azure portal and navigate to your IoT hub.

  2. In the left pane, select IoT Edge from the menu, then select Add an IoT Edge device.

    Add an IoT Edge device from the Azure portal

  3. On the Create a device page, provide the following information:

    • Create a descriptive device ID. Make a note of this device ID, as you'll use it in the next section.
    • Select X.509 Self-Signed as the authentication type.
    • Provide the primary and secondary identity certificate thumbprints. Thumbprint values are 40-hex characters for SHA-1 hashes or 64-hex characters for SHA-256 hashes.
  4. Select Save.

Now that you have a device registered in IoT Hub, you are ready to install and provisioning the IoT Edge runtime on your device. IoT Edge devices that authenticate with X.509 certificates don't use connection strings, so you can continue to the next step:

View registered devices and retrieve connection strings

Devices that use symmetric key authentication need their connection strings to complete installation and provisioning of the IoT Edge runtime.

Devices that use X.509 certificate authentication do not need connection strings. Instead, those devices need their IoT hub name, their device name, and their certificate files to complete installation and provisioning of the IoT Edge runtime.

All the edge-enabled devices that connect to your IoT hub are listed on the IoT Edge page.

Use the Azure portal to view all IoT Edge devices in your IoT hub

When you're ready to set up your device, you need the connection string that links your physical device with its identity in the IoT hub.

Devices that authenticate with symmetric keys have their connection strings available to copy in the portal.

  1. From the IoT Edge page in the portal, click on the device ID from the list of IoT Edge devices.
  2. Copy the value of either Primary Connection String or Secondary Connection String.

Next steps

Now that you have a device registered in IoT Hub, you are ready to install and provisioning the IoT Edge runtime on your device.