Get connected to Azure IoT Central

This article applies to operators and device developers.

This article describes how devices connect to an Azure IoT Central application. Before a device can exchange data with IoT Central, it must:

  • Authenticate. Authentication with the IoT Central application uses either a shared access signature (SAS) token or an X.509 certificate. X.509 certificates are recommended in production environments.
  • Register. Devices must be registered with the IoT Central application. You can view registered devices on the Devices page in the application.
  • Associate with a device template. In an IoT Central application, device templates define the UI that operators use to view and manage connected devices.

IoT Central supports the following two device registration scenarios:

  • Automatic registration. The device is registered automatically when it first connects. This scenario enables OEMs to mass manufacture devices that can connect without first being registered. An OEM generates suitable device credentials, and configures the devices in the factory. Optionally, you can require an operator to approve the device before it starts sending data. This scenario requires you to configure an X.509 or SAS group enrollment in your application.
  • Manual registration. Operators either register individual devices on the Devices page, or import a CSV file to bulk register devices. In this scenario you can use X.509 or SAS group enrollment, or X.509 or SAS individual enrollment.

Devices that connect to IoT Central should follow the IoT Plug and Play conventions. One of these conventions is that a device should send the model ID of the device model it implements when it connects. The model ID enables the IoT Central application to associate the device with the correct device template.

IoT Central uses the Azure IoT Hub Device Provisioning service (DPS) to manage the connection process. A device first connects to a DPS endpoint to retrieve the information it needs to connect to your application. Internally, your IoT Central application uses an IoT hub to handle device connectivity. Using DPS enables:

  • IoT Central to support onboarding and connecting devices at scale.
  • You to generate device credentials and configure the devices offline without registering the devices through IoT Central UI.
  • You to use your own device IDs to register devices in IoT Central. Using your own device IDs simplifies integration with existing back-office systems.
  • A single, consistent way to connect devices to IoT Central.

This article describes the following device connection steps:

X.509 group enrollment

In a production environment, using X.509 certificates is the recommended device authentication mechanism for IoT Central. To learn more, see Device Authentication using X.509 CA Certificates.

To connect a device with an X.509 certificate to your application:

  1. Create an enrollment group that uses the Certificates (X.509) attestation type.
  2. Add and verify an intermediate or root X.509 certificate in the enrollment group.
  3. Generate a leaf certificate from the root or intermediate certificate in the enrollment group. Send the leaf certificate from the device when it connects to your application.

To learn more, see How to connect devices with X.509 certificates

For testing purposes only

For testing only, you can use the following utilities to generate root, intermediate, and device certificates:

  • Tools for the Azure IoT Device Provisioning Device SDK: a collection of Node.js tools that you can use to generate and verify X.509 certificates and keys.
  • If you're using a DevKit device, this command-line tool generates a CA certificate that you can add to your IoT Central application to verify the certificates.
  • Manage test CA certificates for samples and tutorials: a collection of PowerShell and Bash scripts to:
    • Create a certificate chain.
    • Save the certificates as .cer files to upload to your IoT Central application.
    • Use the verification code from the IoT Central application to generate the verification certificate.
    • Create leaf certificates for your devices using your device IDs as a parameter to the tool.

SAS group enrollment

To connect a device with device SAS key to your application:

  1. Create an enrollment group that uses the Shared Access Signature (SAS) attestation type.

  2. Copy the group primary or secondary key from the enrollment group.

  3. Use the Azure CLI to generate a device key from the group key:

    az iot central device compute-device-key --primary-key <enrollment group primary key> --device-id <device ID>
    
  4. Use the generated device key when the device connects to your IoT Central application.

Individual enrollment

Customers connecting devices that each have their own authentication credentials, use individual enrollments. An individual enrollment is an entry for a single device that's allowed to connect. Individual enrollments can use either X.509 leaf certificates or SAS tokens (from a physical or virtual trusted platform module) as attestation mechanisms. A device ID can contain letters, numbers, and the - character. For more information, see DPS individual enrollment.

Note

When you create an individual enrollment for a device, it takes precedence over the default group enrollment options in your IoT Central application.

Create individual enrollments

IoT Central supports the following attestation mechanisms for individual enrollments:

  • Symmetric key attestation: Symmetric key attestation is a simple approach to authenticating a device with the DPS instance. To create an individual enrollment that uses symmetric keys, open the Device connection page for the device, select Individual enrollment as the connection method, and Shared access signature (SAS) as the mechanism. Enter base64 encoded primary and secondary keys, and save your changes. Use the ID scope, Device ID, and either the primary or secondary key to connect your device.

    Tip

    For testing, you can use OpenSSL to generate base64 encoded keys: openssl rand -base64 64

  • X.509 certificates: To create an individual enrollment with X.509 certificates, open the Device Connection page, select Individual enrollment as the connection method, and Certificates (X.509) as the mechanism. Device certificates used with an individual enrollment entry have a requirement that the issuer and subject CN are set to the device ID.

    Tip

    For testing, you can use Tools for the Azure IoT Device Provisioning Device SDK for Node.js to generate a self-signed certificate: node create_test_cert.js device "mytestdevice"

  • Trusted Platform Module (TPM) attestation: A TPM is a type of hardware security module. Using a TPM is one of the most secure ways to connect a device. This article assumes you're using a discrete, firmware, or integrated TPM. Software emulated TPMs are well suited for prototyping or testing, but they don't provide the same level of security as discrete, firmware, or integrated TPMs. Don't use software TPMs in production. To create an individual enrollment that uses a TPM, open the Device Connection page, select Individual enrollment as the connection method, and TPM as the mechanism. Enter the TPM endorsement key and save the device connection information.

Device registration

Before a device can connect to an IoT Central application, it must be registered in the application:

  • Devices can automatically register themselves when they first connect. To use this option, you must use either X.509 group enrollment or SAS group enrollment.
  • An operator can import a CSV file to bulk register a list of devices in the application.
  • An operator can manually register an individual device on the Devices page in the application.

IoT Central enables OEMs to mass manufacture devices that can register themselves automatically. An OEM generates suitable device credentials, and configures the devices in the factory. When a customer turns on a device for the first time, it connects to DPS, which then automatically connects the device to the correct IoT Central application. Optionally, you can require an operator to approve the device before it starts sending data to the application.

Tip

On the Administration > Device connection page, the Auto approve option controls whether an operator must manually approve the device before it can start sending data.

Automatically register devices that use X.509 certificates

  1. Generate the leaf-certificates for your devices using the root or intermediate certificate you added to your X.509 enrollment group. Use the device IDs as the CNAME in the leaf certificates. A device ID can contain letters, numbers, and the - character.

  2. As an OEM, flash each device with a device ID, a generated X.509 leaf-certificate, and the application ID scope value. The device code should also send the model ID of the device model it implements.

  3. When you switch on a device, it first connects to DPS to retrieve its IoT Central connection information.

  4. The device uses the information from DPS to connect to, and register with, your IoT Central application.

The IoT Central application uses the model ID sent by the device to associate the registered device with a device template.

Automatically register devices that use SAS tokens

  1. Copy the group primary key from the SAS-IoT-Devices enrollment group:

    Group primary key from SAS-IoT-Devices enrollment group

  2. Use the az iot central device compute-device-key command to generate the device SAS keys. Use the group primary key from the previous step. The device ID can contain letters, numbers, and the - character:

    az iot central device compute-device-key --primary-key <enrollment group primary key> --device-id <device ID>
    
  3. As an OEM, flash each device with the device ID, the generated device SAS key, and the application ID scope value. The device code should also send the model ID of the device model it implements.

  4. When you switch on a device, it first connects to DPS to retrieve its IoT Central registration information.

  5. The device uses the information from DPS to connect to, and register with, your IoT Central application.

The IoT Central application uses the model ID sent by the device to associate the registered device with a device template.

Bulk register devices in advance

To register a large number of devices with your IoT Central application, use a CSV file to import device IDs and device names.

If your devices use SAS tokens to authenticate, export a CSV file from your IoT Central application. The exported CSV file includes the device IDs and the SAS keys.

If your devices use X.509 certificates to authenticate, generate X.509 leaf certificates for your devices using the root or intermediate certificate in you uploaded to your X.509 enrollment group. Use the device IDs you imported as the CNAME value in the leaf certificates.

Devices must use the ID Scope value for your application and send a model ID when they connect.

Tip

You can find the ID Scope value in Administration > Device connection.

Register a single device in advance

This approach is useful when you're experimenting with IoT Central or testing devices. Select + New on the Devices page to register an individual device. You can use the device connection SAS keys to connect the device to your IoT Central application. Copy the device SAS key from the connection information for a registered device:

SAS keys for an individual device

Associate a device with a device template

IoT Central automatically associates a device with a device template when the device connects. A device sends a model ID when it connects. IoT Central uses the model ID to identify the device template for that specific device model. The discovery process works as follows:

  1. If the device template is already published in the IoT Central application, the device is associated with the device template.
  2. If the device template isn't already published in the IoT Central application, IoT Central looks for the device model in the public model repository. If IoT Central finds the model, it uses it to generate a basic device template.
  3. If IoT Central doesn't find the model in the public model repository, the device is marked as Unassociated. An operator can create a device template for the device and then migrate the unassociated device to the new device template.

Device status values

When a real device connects to your IoT Central application, its device status changes as follows:

  1. The device status is first Registered. This status means the device is created in IoT Central, and has a device ID. A device is registered when:

    • A new real device is added on the Devices page.
    • A set of devices is added using Import on the Devices page.
  2. The device status changes to Provisioned when the device that connected to your IoT Central application with valid credentials completes the provisioning step. In this step, the device uses DPS to automatically retrieve a connection string from the IoT Hub used by your IoT Central application. The device can now connect to IoT Central and start sending data.

  3. An operator can block a device. When a device is blocked, it can't send data to your IoT Central application. Blocked devices have a status of Blocked. An operator must reset the device before it can resume sending data. When an operator unblocks a device the status returns to its previous value, Registered or Provisioned.

  4. If the device status is Waiting for Approval, it means the Auto approve option is disabled. An operator must explicitly approve a device before it starts sending data. Devices not registered manually on the Devices page, but connected with valid credentials will have the device status Waiting for Approval. Operators can approve these devices from the Devices page using the Approve button.

  5. If the device status is Unassociated, it means the device connecting to IoT Central doesn't have an associated device template. This situation typically happens in the following scenarios:

    • A set of devices is added using Import on the Devices page without specifying the device template.
    • A device was registered manually on the Devices page without specifying the device template. The device then connected with valid credentials.

    The Operator can associate a device to a device template from the Devices page using the Migrate button.

Best practices

Don't persist or cache the device connection string that DPS returns when you first connect the device. To reconnect a device, go through the standard device registration flow to get the correct device connection string. If the device caches the connection string, the device software runs into the risk of having a stale connection string. If IoT Central updates the underlying Azure IoT hub it uses, a device with a stale connection string can't connect.

SDK support

The Azure Device SDKs offer the easiest way for you implement your device code. The following device SDKs are available:

SDK features and IoT Hub connectivity

All device communication with IoT Hub uses the following IoT Hub connectivity options:

The following table summarizes how Azure IoT Central device features map on to IoT Hub features:

Azure IoT Central Azure IoT Hub
Telemetry Device-to-cloud messaging
Property Device twin reported properties
Property (writeable) Device twin desired and reported properties
Command Direct methods

Protocols

The Device SDKs support the following network protocols for connecting to an IoT hub:

  • MQTT
  • AMQP
  • HTTPS

For information about these difference protocols and guidance on choosing one, see Choose a communication protocol.

If your device can't use any of the supported protocols, use Azure IoT Edge to do protocol conversion. IoT Edge supports other intelligence-on-the-edge scenarios to offload processing from the Azure IoT Central application.

Security

All data exchanged between devices and your Azure IoT Central is encrypted. IoT Hub authenticates every request from a device that connects to any of the device-facing IoT Hub endpoints. To avoid exchanging credentials over the wire, a device uses signed tokens to authenticate. For more information, see, Control access to IoT Hub.

Next steps

If you're a device developer, some suggested next steps are to: