Set up an Azure IoT Edge device with X.509 certificate authentication

Article
11/25/2022

This article provides the steps to register a new IoT Edge device in IoT Hub and configure the device to authenticate with X.509 certificates.

The steps in this article walk through a process called manual provisioning, where you connect each device to its IoT hub manually. The alternative is automatic provisioning using the IoT Hub Device Provisioning Service, which is helpful when you have many devices to provision.

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 its certificates and IoT Hub can verify that they match the thumbprints.

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

This article walks through the registration and provisioning process with X.509 certificate authentication. If you want to learn how to set up a device with symmetric keys, see Set up an Azure IoT Edge device with symmetric key authentication.

Prerequisites

Before you follow the steps in this article, you should have a device with the IoT Edge runtime installed on it.

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

Create certificates and thumbprints

The device identity certificate is a leaf certificate that connects through a certificate chain of trust to the top X.509 certificate authority (CA) certificate. The device identity certificate must have its common name (CN) set to the device ID that you want the device to have in your IoT hub.

Device identity certificates are only used for provisioning the IoT Edge device and authenticating the device with Azure IoT Hub. They aren't signing certificates, unlike the CA certificates that the IoT Edge device presents to modules or leaf devices for verification. For more information, see Azure IoT Edge certificate usage detail.

After you create the device identity certificate, you should have two files: a .cer or .pem file that contains the public portion of the certificate, and a .cer or .pem file with the private key of the certificate.

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

Two sets of device identity certificates and private key certificates. One set of certificate/key files is provided to the IoT Edge runtime.
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

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.

For X.509 certificate authentication, this 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.

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

Portal
Azure CLI

Prerequisites for the Azure portal

A free or standard IoT hub in your Azure subscription.

Create an IoT Edge device in the Azure portal

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

Sign in to the Azure portal and navigate to your IoT hub.
In the left pane, select IoT Edge from the menu, then select Add an IoT Edge device.
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.
Select Save.

View IoT Edge devices in the Azure portal

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

View all IoT Edge devices in your IoT hub

Prerequisites for the Azure CLI

An IoT hub in your Azure subscription.
Azure CLI in your environment. At a minimum, your Azure CLI version must be 2.0.70 or above. Use az --version to validate. This version supports az extension commands and introduces the Knack command framework.
The IoT extension for Azure CLI.

Create an IoT Edge device with the Azure CLI

Use the az iot hub device-identity create command to create a new device identity in your IoT hub. For example:

az iot hub device-identity create --device-id [device id] --hub-name [hub name] --edge-enabled --auth-method x509_thumbprint --primary-thumbprint [SHA thumbprint] --secondary-thumbprint [SHA thumbprint]

This command includes several parameters:

--device-id or -d: Provide a descriptive name that's unique to your IoT hub. Make a note of this device ID, as you'll use it in the next section.
hub-name or -n: Provide the name of your IoT hub.
--edge-enabled or --ee: Declare that the device is an IoT Edge device.
--auth-method or --am: Declare the authorization type the device is going to use. In this case, we're using X.509 certificate thumbprints.
--primary-thumbprint or --ptp: Provide an X.509 certificate thumbprint to use as a primary key.
--secondary-thumbprint or --stp: Provide an X.509 certificate thumbprint to use as a secondary key.

View IoT Edge devices with the Azure CLI

Use the az iot hub device-identity list command to view all devices in your IoT hub. For example:

az iot hub device-identity list --hub-name [hub name]

Add the flag --edge-enabled or --ee to list only IoT Edge devices in your IoT hub.

Any device that is registered as an IoT Edge device will have the property capabilities.iotEdge set to true.

Configure an IoT Edge device

Once the IoT Edge device has an identity in IoT Hub, you need to configure the device with its cloud identity as well as its identity certificates.

On a Linux device, you provide this information by editing a config.yaml file. On a Windows device, you provide this information by running a PowerShell script.

Linux
Windows

On the IoT Edge device, open the configuration file.
```
sudo nano /etc/iotedge/config.yaml
```
Find the provisioning configurations section of the file.
Comment out the Manual provisioning configuration using a connection string section.

Uncomment the Manual provisioning configuration using an X.509 identity certificate section. Make sure the provisioning: line has no preceding whitespace and that nested items are indented by two spaces.

# Manual provisioning configuration using a connection string
provisioning:
  source: "manual"
  authentication:
    method: "x509"
    iothub_hostname: "<REQUIRED IOTHUB HOSTNAME>"
    device_id: "<REQUIRED DEVICE ID PROVISIONED IN IOTHUB>"
    identity_cert: "<REQUIRED URI TO DEVICE IDENTITY CERTIFICATE>"
    identity_pk: "<REQUIRED URI TO DEVICE IDENTITY PRIVATE KEY>"
  dynamic_reprovisioning: false

Update the following fields:
- iothub_hostname: Hostname of the IoT hub the device will connect to. For example, {IoT hub name}.azure-devices.net.
- device_id: The ID that you provided when you registered the device.
- identity_cert: URI to an identity certificate on the device. For example, file:///path/identity_certificate.pem.
- identity_pk: URI to the private key file for the provided identity certificate. For example, file:///path/identity_key.pem.
Save and close the file.

CTRL + X, Y, Enter
After entering the provisioning information in the configuration file, restart the daemon:
```
sudo systemctl restart iotedge
```

On the IoT Edge device, run PowerShell as an administrator.
Use the Initialize-IoTEdge command to configure the IoT Edge runtime on your machine.
```
. {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
Initialize-IoTEdge -ManualX509
```
- If you are using Linux containers, add the -ContainerOs parameter to the flag. Be consistent with the container option you chose with the Deploy-IoTEdge command that you ran previously.
```
. {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
Initialize-IoTEdge -ManualX509 -ContainerOs Linux
```
- If you downloaded the IoTEdgeSecurityDaemon.ps1 script onto your device for offline or specific version installation, be sure to reference the local copy of the script.
```
. <path>/IoTEdgeSecurityDaemon.ps1
Initialize-IoTEdge -ManualX509
```
When prompted, provide the following information:
- IotHubHostName: Hostname of the IoT hub the device will connect to. For example, {IoT hub name}.azure-devices.net.
- DeviceId: The ID that you provided when you registered the device.
- X509IdentityCertificate: Absolute path to an identity certificate on the device. For example, C:\path\identity_certificate.pem.
- X509IdentityPrivateKey: Absolute path to the private key file for the provided identity certificate. For example, C:\path\identity_key.pem.

When you provision a device manually, you can use additional parameters to modify the process including:

Direct traffic to go through a proxy server
Declare a specific edgeAgent container image, and provide credentials if it's in a private registry

Verify successful setup

Check the status of the IoT Edge service. It should be listed as running.

Linux
Windows

systemctl status iotedge

Get-Service iotedge

Examine service logs.

Linux
Windows

journalctl -u iotedge --no-pager --no-full

If you just finished installing the IoT Edge runtime, you may see a list of errors from the time between running Deploy-IoTEdge and Initialize-IoTEdge. These errors are expected, as the service is trying to start before being configured.

. {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog

Run the troubleshooting tool to check for the most common configuration and networking errors.

iotedge check

Until you deploy your first module to IoT Edge on your device, the $edgeHub system module will not be deployed to the device. As a result, the automated check will return an error for the Edge Hub can bind to ports on host connectivity check. This error can be ignored unless it occurs after deploying a module to the device.

Finally, list running modules:

iotedge list

After a new installation, the only module you should see running is edgeAgent.

Tips and troubleshooting

On resource constrained devices, it is highly recommended that you set the OptimizeForPerformance environment variable to false as per instructions in the troubleshooting guide.

If your device can't connect to IoT Hub and your network has a proxy server, follow the steps in Configure your IoT Edge device to communicate through a proxy server.

Linux
Windows

On Linux devices, you need elevated privileges to run iotedge commands. After installing the runtime, sign out of your machine and sign back in to update your permissions automatically. Until then, use sudo to run commands with elevated privileges.

On Windows devices running Windows containers, the Moby container engine was installed as part of IoT Edge. The Moby engine was designed to run in parallel with Docker Desktop. You can use docker commands if you want to interact directly with the containers on your device. However, you must specifically target the Moby engine in case Docker Desktop is also installed on the device.

For example, to list all Docker images, use the following command:

docker images

To list all Moby images, modify the same command with a pointer to the Moby engine:

docker -H npipe:////./pipe/iotedge_moby_engine images

The engine URI is listed in the output of the installation script, or you can find it in the container runtime settings section for the config.yaml file.

moby_runtime uri in config.yaml

Next steps

Continue to deploy IoT Edge modules to learn how to deploy modules onto your device.