Azure IoT Device Provisioning Service HTTP Transport

Common errors

• Error: Cannot find module 'azure-iot-provisioning-device'

  cause The core `azure-iot-provisioning-device` client package, a required peer dependency, is not installed in your project.
  fix Install the client package: `npm install --save azure-iot-provisioning-device`.

• TypeError: ProvisioningDeviceClient.create is not a function

  cause The `ProvisioningDeviceClient` class was either not imported correctly (e.g., as a default import instead of a named import) or the `azure-iot-provisioning-device` package itself is missing.
  fix Ensure `ProvisioningDeviceClient` is imported as a named export from `'azure-iot-provisioning-device'` like `import { ProvisioningDeviceClient } from 'azure-iot-provisioning-device';`.

• Error: Provisioning flow must have SecurityClient type and ProvisioningTransport type set.

  cause The `ProvisioningDeviceClient.create` method requires both a transport instance (like `new Http()`) and a security client instance (e.g., `new X509Security(...)` or `new TpmSecurity(...)`) to be provided as its second and third arguments.
  fix Ensure you are passing `new Http()` and an instance of your chosen security client (e.g., `new X509Security(...)`) as the second and third arguments to `ProvisioningDeviceClient.create()`.

Warnings

• breaking As of the April 2022 release (v1.18.0) of the broader Azure IoT SDK for Node.js, including this package's dependencies, Node.js versions `>= 14.0.0` became the minimum supported runtime. Older Node.js 12 environments are no longer officially supported and may lead to unexpected behavior or failures.
  Fix: Upgrade your Node.js runtime environment to version 14.0.0 or higher. The latest LTS version is generally recommended for production.
• gotcha This package provides only the HTTP transport component. For a complete device provisioning solution, you must also install `azure-iot-provisioning-device` (the client library) and either `azure-iot-security-x509` or `azure-iot-security-tpm` for device authentication. Neglecting to install these can lead to runtime errors when attempting to create a provisioning client.
  Fix: Ensure all necessary packages are installed: `npm install --save azure-iot-provisioning-device azure-iot-provisioning-device-http azure-iot-security-x509` (or `-tpm` depending on your authentication method).
• gotcha Dependency vulnerabilities are frequently addressed in new releases across the Azure IoT SDK ecosystem. While the SDK team regularly updates dependencies, it's crucial for applications to keep their packages up-to-date to mitigate potential security risks and benefit from fixes.
  Fix: Regularly update your `azure-iot-provisioning-device-http` and related Azure IoT SDK packages to the latest stable versions using `npm update` or `npm install <package-name>@latest`.

Install

• npm install azure-iot-provisioning-device-http npm
• yarn add azure-iot-provisioning-device-http yarn
• pnpm add azure-iot-provisioning-device-http pnpm

Imports

• Http
  wrong:

  const Http = require('azure-iot-provisioning-device-http');

  correct:

  import { Http } from 'azure-iot-provisioning-device-http';

  While CommonJS `require` might still work, modern TypeScript/Node.js projects should prefer ESM `import`.
• ProvisioningDeviceClient
  wrong:

  import ProvisioningDeviceClient from 'azure-iot-provisioning-device';

  correct:

  import { ProvisioningDeviceClient } from 'azure-iot-provisioning-device';

  The primary client class is a named export from the core provisioning package, not a default export.
• X509Security
  wrong:

  const X509Security = require('azure-iot-security-x509');

  correct:

  import { X509Security } from 'azure-iot-security-x509';

  The security client for X.509 authentication is a separate named export.

Quickstart

Demonstrates how to register a device with Azure IoT Hub Device Provisioning Service (DPS) using HTTP transport and X.509 certificate authentication.

import { ProvisioningDeviceClient } from 'azure-iot-provisioning-device';
import { Http } from 'azure-iot-provisioning-device-http';
import { X509Security } from 'azure-iot-security-x509';
import { readFileSync } from 'fs';

// Replace with your DPS ID Scope and device certificate paths
const idScope = process.env.IOTHUB_DPS_ID_SCOPE ?? '';
const registrationId = process.env.IOTHUB_DPS_REGISTRATION_ID ?? 'my-x509-device';
const certificateFile = process.env.X509_CERT_FILE ?? 'path/to/device_cert.pem';
const keyFile = process.env.X509_KEY_FILE ?? 'path/to/device_key.pem';

async function main() {
  if (!idScope || !certificateFile || !keyFile) {
    console.error("Please set IOTHUB_DPS_ID_SCOPE, X509_CERT_FILE, and X509_KEY_FILE environment variables.");
    process.exit(1);
  }

  try {
    const certificate = readFileSync(certificateFile).toString();
    const privateKey = readFileSync(keyFile).toString();

    // Create a new X509 security client
    const securityClient = new X509Security(registrationId, certificate, privateKey);

    // Create the provisioning client with HTTP transport and X509 security
    const provisioningClient = ProvisioningDeviceClient.create(
      idScope,
      new Http(), // The HTTP transport from this package
      securityClient
    );

    console.log(`Attempting to register device '${registrationId}' with DPS...`);

    // Register the device
    const result = await provisioningClient.register();

    console.log('Registration result:');
    console.log(JSON.stringify(result, null, 2));
    console.log(`Device successfully registered with IoT Hub: ${result.assignedHub}`);
    console.log(`Device ID: ${result.deviceId}`);
  } catch (err: any) {
    console.error('Device registration failed:', err.message);
    if (err.responseBody) {
      console.error('DPS Response:', err.responseBody);
    }
    process.exit(1);
  }
}

main();