How to connect devices with X.509 certificates using Node.js device SDK for IoT Central Application

IoT Central supports both shared access signatures (SAS) and X.509 certificates to secure the communication between a device and your application. The Create and connect a client application to your Azure IoT Central application tutorial uses SAS. In this article, you learn how to modify the code sample to use X.509. X.509 certificates are recommended in production environments. For more information, see Get connected to Azure IoT Central.

This article shows two ways of using X.509 - group enrollments typically used in a production environment, and individual enrollments useful for testing.

Prerequisites

Use a group enrollment

Use X.509 certificates with a group enrollment in a production environment. In a group enrollment, you add a root or intermediate X.509 certificate to your IoT Central application. Devices with leaf certificates derived from the root or intermediate certificate can connect to your application.

Generate root and device cert

In this section, you use an X.509 certificate to connect a device with a cert derived from the enrollment group's cert, which can connect to your IoT Central application.

Warning

This way of generating X.509 certs is for testing only. For a production environment you should use your official, secure mechanism for certificate generation.

  1. Open a command prompt. Clone the GitHub repository for the certificate generation scripts:

    git clone https://github.com/Azure/azure-iot-sdk-node.git
    
  2. Navigate to the certificate generator script and install the required packages:

    cd azure-iot-sdk-node/provisioning/tools
    npm install
    
  3. Create a root certificate and then derive a device certificate by running the script:

    node create_test_cert.js root mytestrootcert
    node create_test_cert.js device sample-device-01 mytestrootcert
    

    Tip

    A device ID can contain letters, numbers, and the - character.

These commands produce three files each for the root and the device certificate

filename contents
<name>_cert.pem The public portion of the X509 certificate
<name>_key.pem The private key for the X509 certificate
<name>_fullchain.pem The entire keychain for the X509 certificate.

Create a group enrollment

  1. Open your IoT Central application and navigate to Administration in the left pane and select Device connection.

  2. Select + Create enrollment group, and create a new enrollment group called MyX509Group with an attestation type of Certificates (X.509).

  3. Open the enrollment group you created and select Manage Primary.

  4. Select file option and upload the root certificate file called mytestrootcert_cert.pem that you generated previously:

    Certificate Upload

  5. To complete the verification, generate the verification code, copy it, and then use it to create an X.509 verification certificate at the command prompt:

    node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}
    
  6. Upload the signed verification certificate verification_cert.pem to complete the verification:

    Verified Certificate

You can now connect devices that have an X.509 certificate derived from this primary root certificate.

After you save the enrollment group, make a note of the ID Scope.

Run sample device code

  1. Copy the sampleDevice01_key.pem and sampleDevice01_cert.pem files to the azure-iot-sdk-node/device/samples/pnp folder that contains the simple_thermostat.js application. You used this application when you completed the Connect a device (JavaScript) tutorial.

  2. Navigate to the azure-iot-sdk-node/device/samples/pnp folder that contains the simple_thermostat.js application and run the following command to install the X.509 package:

    npm install azure-iot-security-x509 --save
    
  3. Open the simple_thermostat.js file in a text editor.

  4. Edit the require statements to include the following:

    const fs = require('fs');
    const X509Security = require('azure-iot-security-x509').X509Security;
    
  5. Add the following four lines to the "DPS connection information" section to initialize the deviceCert variable:

    const deviceCert = {
      cert: fs.readFileSync(process.env.IOTHUB_DEVICE_X509_CERT).toString(),
      key: fs.readFileSync(process.env.IOTHUB_DEVICE_X509_KEY).toString()
    };
    
  6. Edit the provisionDevice function that creates the client by replacing the first line with the following:

    var provSecurityClient = new X509Security(registrationId, deviceCert);
    
  7. In the same function, modify the line that sets the deviceConnectionString variable as follows:

    deviceConnectionString = 'HostName=' + result.assignedHub + ';DeviceId=' + result.deviceId + ';x509=true';
    
  8. In the main function, add the following line after the line that calls Client.fromConnectionString:

    client.setOptions(deviceCert);
    
  9. In your shell environment, set the following two environment variables:

    set IOTHUB_DEVICE_X509_CERT=sampleDevice01_cert.pem
    set IOTHUB_DEVICE_X509_KEY=sampleDevice01_key.pem
    

    Tip

    You set the other required environment variables when you completed the Create and connect a client application to your Azure IoT Central application tutorial.

  10. Execute the script and verify the device was provisioned successfully:

    node simple_thermostat.js
    

    You can also verify that telemetry appears on the dashboard.

    Verify Device Telemetry

Use an individual enrollment

Use X.509 certificates with an individual enrollment to test your device and solution. In an individual enrollment, there's no root or intermediate X.509 certificate in your IoT Central application. Devices use a self-signed X.509 certificate to connect to your application.

Generate self-signed device cert

In this section, you use a self-signed X.509 certificate to connect devices for individual enrollment, which are used to enroll a single device. Self-signed certificates are for testing only.

Create a self-signed X.509 device certificate by running the script. Be sure to only use lower-case alphanumerics and hyphens for certificate name:

  cd azure-iot-sdk-node/provisioning/tools
  node create_test_cert.js device mytestselfcertprimary
  node create_test_cert.js device mytestselfcertsecondary 

Create individual enrollment

  1. In the Azure IoT Central application, select Devices, and create a new device with Device ID as mytestselfcertprimary from the thermostat device template. Make a note of the ID Scope, you use it later.

  2. Open the device you created and select Connect.

  3. Select Individual Enrollments as the Connect Method and Certificates (X.509) as the mechanism:

    Individual enrollment

  4. Select file option under primary and upload the certificate file called mytestselfcertprimary_cert.pem that you generated previously.

  5. Select the file option for the secondary certificate and upload the certificate file called mytestselfcertsecondary_cert.pem. Then select Save:

    Individual enrollment Certificate Upload

The device is now provisioned with X.509 certificate.

Run a sample individual enrollment device

  1. Copy the mytestselfcertprimary_key.pem and mytestselfcertprimary_cert.pem files to the azure-iot-sdk-node/device/samples/pnp folder that contains the simple_thermostat.js application. You used this application when you completed the Connect a device (JavaScript) tutorial.

  2. Modify the environment variables you used in as follows:

    set IOTHUB_DEVICE_DPS_DEVICE_ID=mytestselfcertprimary
    set IOTHUB_DEVICE_X509_CERT=mytestselfcertprimary_cert.pem
    set IOTHUB_DEVICE_X509_KEY=mytestselfcertprimary_key.pem
    
  3. Execute the script and verify the device was provisioned successfully:

    node environmentalSensor.js
    

    You can also verify that telemetry appears on the dashboard.

    Telemetry Individual enrollment

You can repeat the above steps for mytestselfcertsecondary certificate as well.

Next steps

Now that you've learned how to connect devices using X.509 certificates, the suggested next step is to learn how to Monitor device connectivity using Azure CLI