Skip to content

Provision your device

There are two channels to provision your device:

  • Using the MQTT channel,
  • Using the Azure IoT Hub channel.

MQTT

Login password

The fastest way - but not the safest.

  • On Kamea, provision a new device using Mqtt / Login-Password

    If you don't know how to create / provision a device, check the user documentation

  • After successfully provisioned your device on Kamea, download the broker_ca.crt and send it to the target's /var/KameaLinuxAgent/config/trust-store/ directory as you will need it to connect to the cloud.

  • Provide the login information to /var/KameaLinuxAgent/config/config-provisioning.json

    hostname the MQTT endpoint without the mqtts:// and without everything after the last : (which is the port)
    port: the endpoint port.
    deviceId: the login credentials
    password: the password credentials
    mode: must be set to login-password
    channel: must be set to mqtt
    trust-store: the path to the broker certificate. Should be config/trust-store/broker_ca.crt
    passphrase and key-store are unused and can be left empty

Self-signed certificate

Uses a self-signed X.509 certificate for device authentication. The certificate is generated directly on the device and uploaded to Kamea.

  • Generate a self-signed certificate on the device, under the config/trust-store/ folder inside the data directory:

shell step certificate create <device-id> \ mqtt-self-signed.crt \ mqtt-self-signed.key \ --profile self-signed --subtle \ --no-password --insecure

Replace <device-id> with your device ID — it will be used as the certificate's Common Name (CN).

  • Bundle the certificate and private key into a single PEM file (required by Paho MQTT):

shell cat mqtt-self-signed.crt mqtt-self-signed.key > mqtt-self-signed.pem

  • On Kamea, provision a new device using Mqtt / X.509 Self Signed and upload the mqtt-self-signed.crt file.

    If you don't know how to create / provision a device, check the user documentation

  • After successfully provisioned your device on Kamea, download the broker_ca.crt and send it to the target's /var/KameaLinuxAgent/config/trust-store/ directory.

  • Provide the information to /var/KameaLinuxAgent/config/config-provisioning.json:

    deviceId: the certificate's common-name (device ID)
    hostname: the MQTT endpoint without the mqtts:// and without everything after the last : (which is the port)
    port: the endpoint port
    mode: must be set to self-signed
    channel: must be set to mqtt
    trust-store: the path to the broker certificate. Should be config/trust-store/broker_ca.crt
    key-store: the path to the bundled PEM. Should be config/trust-store/mqtt-self-signed.pem

    password and passphrase are unused and can be left empty

CA-signed certificate

The safest MQTT channel but needs a slightly more involved setup.

Ensure you recovered these files from Kamea Support:

  • The intermediate CA certificate (mqtt-ca.crt)
  • The intermediate CA private key (mqtt-ca.key)

  • Generate a device certificate signed by the intermediate CA: shell step certificate create <device-id> \ device-ca-signed-mqtt.crt \ device-ca-signed-mqtt.key \ --ca mqtt-ca.crt \ --ca-key mqtt-ca.key \ --no-password --insecure

    Replace <device-id> with your device ID — it will be used as the certificate's Common Name (CN).

  • Bundle the device certificate, intermediate CA and private key into a single PEM file.

shell cat device-ca-signed-mqtt.crt mqtt-ca.crt device-ca-signed-mqtt.key > device-ca-signed-mqtt.pem

Order matters: device cert → intermediate CA cert → private key.

  • On Kamea, provision a new device using Mqtt / X.509 CA Signed and paste the device ID as the common-name.

    If you don't know how to create / provision a device, check the user documentation

  • After successfully provisioned your device on Kamea, download the broker_ca.crt (by clicking on the blue button at the end of Kamea provisioning step) and send it to the target /var/KameaLinuxAgent/config/trust-store/ directory with scp.

  • Also send the bundled PEM file (device-ca-signed-mqtt.pem) to the target /var/KameaLinuxAgent/config/trust-store/.
  • Provide the information to /var/KameaLinuxAgent/config/config-provisioning.json:

    deviceId: the certificate's common-name (device ID)
    hostname: the MQTT endpoint without the mqtts:// and without everything after the last : (which is the port)
    port: the endpoint port
    mode: must be set to ca-signed
    channel: must be set to mqtt
    trust-store: the path to the broker certificate. Should be config/trust-store/broker_ca.crt
    key-store: the path to the bundled PEM. Should be config/trust-store/device-ca-signed-mqtt.pem

Azure IoT Hub

Symmetric key

  • On Kamea, provision a new device using Iot Hub / Symmetric key

    If you don't know how to create / provision a device, check the user documentation

  • After successfully provisioned your device on Kamea, copy the Iot hub hostname, primary and secondary connection string.

  • Provide the copied information to /var/KameaLinuxAgent/config/config-provisioning.json. This file should look like this:

    hostname: "hostname from kamea"
    port: 8883
    mode: symmkey
    channel: azure-iot-hub
    primary-connection-string: "primary-connection-string"
    secondary-connection-string: "secondary-connection-string"

Self-signed certificate

  • On Kamea, provision a new device using Iot Hub / X.509 Self Signed method. Then, go the device settings and save the internal ID as it will be required to create the certificate. Also, save the hostname for later.

    If you don't know how to create / provision a device, check the user documentation

  • On the device, create the certificate under the config/trust-store/ folder inside the data directory, with this command:

shell step certificate create <device-id> device.crt device.key --profile self-signed --subtle --no-password --insecure

Don't forget to replace "device-id" with the kamea device internal saved previously
Then, retrieve the certificate fingerprint and pastes it to the kamea X.509 Self Signed settings, both on primary and secondary. To retrieve the fingerprint, use:

shell step certificate fingerprint device.crt

  • Finally, provide the information to /var/KameaLinuxAgent/config/config-provisioning.json as followed:

    hostname: "hostname from kamea",
    port: 8883,
    mode: self-signed,
    channel: azure-iot-hub,
    deviceId: "device-id",
    trust-store: "config/trust-store/device.crt",
    key-store: "config/trust-store/device.key"

CA-signed certificate

Uses a certificate signed by an intermediate Certificate Authority (CA) registered in Azure IoT Hub. Unlike self-signed, the CA chain allows Azure to verify the device without manually uploading thumbprints for each device.

  • On Kamea, provision a new device using Iot Hub / X.509 CA Signed method. Save the hostname and the device ID (internal ID) from the device settings.

    If you don't know how to create / provision a device, check the user documentation

  • On the device, generate a CA-signed certificate under the config/trust-store/ folder inside the data directory:

shell step certificate create <device-id> \ device-ca-signed.crt \ device-ca-signed.key \ --ca <CA-certificate-path>.crt \ --ca-key <CA-key-path>.key \ --no-password --insecure

Replace <device-id> with the device internal ID saved previously.

The --no-password --insecure flags disable private key encryption. This is acceptable for embedded devices where the key is stored on a secure filesystem, but should be reviewed for your security requirements.

The <CA-certificate-path>.crt and <CA-key-path>.key files are the intermediate CA certificate and key registered in Azure IoT Hub. Contact the Kamea team to retrieve them.

  • Provide the information to /var/KameaLinuxAgent/config/config-provisioning.json:

hostname: "hostname from kamea"
port: 8883
mode: ca-signed
channel: azure-iot-hub
deviceId: "device-id"
trust-store: path to the CA-signed device certificate (e.g. config/trust-store/device-ca-signed.crt)
key-store: path to the device private key (e.g. config/trust-store/device-ca-signed.key)

Device Provisioning Service (DPS)

The DPS allows automatic device registration to Azure IoT Hub using a CA-signed X.509 certificate. The device ID is automatically extracted from the certificate's Common Name (CN).

  • On Kamea, provision a new device using Iot Hub / DPS. You can contact the Kamea team to retrieve the ID Scope of the DPS instance.

    If you don't know how to create / provision a device, check the user documentation

  • On the device, generate a CA-signed certificate under the config/trust-store/ folder inside the data directory:

shell step certificate create <device-id> \ device-ca-signed.crt \ device-ca-signed.key \ --ca <CA-certificate-path>.crt \ --ca-key <CA-key-path>.key \ --no-password --insecure

Replace <device-id> with the desired device identifier. This value will be used as the certificate CN and will become the device's registration ID in DPS.

The <CA-certificate-path>.crt and <CA-key-path>.key files are the CA certificate and key registered in the Azure DPS enrollment group. Contact the Kamea team to retrieve them.

  • Provide the information to /var/KameaLinuxAgent/config/config-provisioning.json:

mode: dps
channel: azure-iot-hub
trust-store: path to the CA-signed device certificate
key-store: path to the device private key
dps-scope-id: the ID Scope from the Azure Device Provisioning Service instance (retrieved from Kamea)