Set up an Azure IoT Edge device with symmetric key authentication
Article
This article provides the steps to register a new IoT Edge device in IoT Hub and configure the device to authenticate with symmetric keys.
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.
Before you follow the steps in this article, you should have a device with the IoT Edge runtime installed on it.
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 symmetric key authentication, this information is gathered in a connection string that you can retrieve from IoT Hub and then place on your IoT Edge device.
You can use several tools to register a new IoT Edge device in IoT Hub and retrieve its connection string, depending on your preference.
You can use the Azure IoT extensions for Visual Studio Code to perform operations with your IoT Hub. For these operations to work, you need to sign in to your Azure account and select your IoT Hub.
In Visual Studio Code, open the Explorer view.
At the bottom of the Explorer, expand the Azure IoT Hub section.
Click on the ... in the Azure IoT Hub section header. If you don't see the ellipsis, click on or hover over the header.
Choose Select IoT Hub.
If you aren't signed in to your Azure account, follow the prompts to do so.
Select your Azure subscription.
Select your IoT hub.
Create an IoT Edge device with Visual Studio Code
In the VS Code Explorer, expand the Azure IoT Hub Devices section.
Click on the ... in the Azure IoT Hub Devices section header. If you don't see the ellipsis, click on or hover over the header.
Select Create IoT Edge Device.
In the text box that opens, give your device an ID.
In the output screen, you see the result of the command. The device info is printed, which includes the deviceId that you provided and the connectionString that you can use to connect your physical device to your IoT hub.
View IoT Edge devices with Visual Studio Code
All the devices that connect to your IoT hub are listed in the Azure IoT Hub section of the Visual Studio Code Explorer. IoT Edge devices are distinguishable from non-Edge devices with a different icon, and the fact that the $edgeAgent and $edgeHub modules are deployed to each IoT Edge device.
Retrieve the connection string with Visual Studio Code
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.
Right-click on the ID of your device in the Azure IoT Hub section.
Select Copy Device Connection String.
The connection string is copied to your clipboard.
You can also select Get Device Info from the right-click menu to see all the device info, including the connection string, in the output window.
Azure CLI in your environment. At a minimum, your Azure CLI version must be 2.0.70 or newer. Use az --version to validate. This version supports az extension commands and introduces the Knack command framework.
az iot hub device-identity list --hub-name [hub name]
Any device that is registered as an IoT Edge device will have the property capabilities.iotEdge set to true.
Retrieve the connection string with the Azure CLI
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. Use the az iot hub device-identity show-connection-string command to return the connection string for a single device:
The value for the device-id parameter is case-sensitive. Don't copy the quotation marks around the connection string.
Provision an IoT Edge device
Once the IoT Edge device has an identity in IoT Hub and a connection string that it can use for authentication, you need to provision the device itself with this information.
On a Linux device, you provide the connection string by editing a config.yaml file. On a Windows device, you provide the connection string by running a PowerShell script.
On the IoT Edge device, open the configuration file.
sudo nano /etc/iotedge/config.yaml
Find the provisioning configurations of the file and uncomment the Manual provisioning configuration using a connection string section.
Update the value of device_connection_string with the connection string from your IoT Edge device. Make sure any other provisioning sections are commented out. 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"
device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
dynamic_reprovisioning: false
To paste clipboard contents into Nano Shift+Right Click or press Shift+Insert.
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. The command defaults to manual provisioning with Windows containers.
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 -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.
When prompted, provide the device connection string that you retrieved in the previous section. The device connection string associates the physical device with a device ID in IoT Hub and provides authentication information.
The device connection string takes the following format, and should not include quotation marks: HostName={IoT hub name}.azure-devices.net;DeviceId={device name};SharedAccessKey={key}
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.
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.
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.
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:
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.
