Programmatically create a Device Provisioning Service enrollment group for X.509 certificate attestation

• Install .NET 6.0 SDK or later or later on your Windows-based machine. You can use the following command to check your version.

  dotnet --info
  

• Install Node.js v4.0 or above or later on your machine.

• Java SE Development Kit 8. This article uses the Azure IoT SDK for Java, which works on both Windows and Linux. This article uses Windows.

• Maven 3.

This section shows you how to create a .NET Core console application that adds an enrollment group to your provisioning service.

1. Open a Windows command prompt and navigate to a folder where you want to create your app.

2. To create a console project, run the following command:

   dotnet new console --framework net6.0 --use-program-main 
   

3. To add a reference to the DPS service SDK, run the following command:

   dotnet add package Microsoft.Azure.Devices.Provisioning.Service 
   

   This step downloads, installs, and adds a reference to the Azure IoT DPS service client NuGet package and its dependencies. This package includes the binaries for the .NET service SDK.

4. Open Program.cs file in an editor.

5. Replace the namespace statement at the top of the file with the following line:

   namespace CreateEnrollmentGroup;
   

6. Add the following using statements at the top of the file above the namespace statement:

   using System.Security.Cryptography.X509Certificates;
   using System.Threading.Tasks;
   using Microsoft.Azure.Devices.Provisioning.Service;
   

7. Add the following fields to the Program class, and make the indicated changes.

   private static string ProvisioningConnectionString = "{ProvisioningServiceConnectionString}";
   private static string EnrollmentGroupId = "enrollmentgrouptest";
   private static string X509RootCertPath = @"{Path to a .cer or .pem file for a verified root CA or intermediate CA X.509 certificate}";
   

   • Replace the ProvisioningServiceConnectionString placeholder value with the connection string of the provisioning service that you copied in the previous section.

   • Replace the X509RootCertPath placeholder value with the path to a .pem or .cer file. This file represents the public part of a either a root CA X.509 certificate that has been previously uploaded and verified with your provisioning service, or an intermediate certificate that has itself been uploaded and verified or had a certificate in its signing chain uploaded and verified.

   • You may optionally change the EnrollmentGroupId value. The string can contain only lower case characters and hyphens.

   Important

   In production code, be aware of the following security considerations:

   • Hard-coding the connection string for the provisioning service administrator is against security best practices. Instead, the connection string should be held in a secure manner, such as in a secure configuration file or in the registry.
   • Be sure to upload only the public part of the signing certificate. Never upload .pfx (PKCS12) or .pem files containing private keys to the provisioning service.

8. Add the following method to the Program class. This code creates an EnrollmentGroup entry and then calls the ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync method to add the enrollment group to the provisioning service.

   public static async Task RunSample()
   {
       Console.WriteLine("Starting sample...");
   
       using (ProvisioningServiceClient provisioningServiceClient =
               ProvisioningServiceClient.CreateFromConnectionString(ProvisioningConnectionString))
       {
           #region Create a new enrollmentGroup config
           Console.WriteLine("\nCreating a new enrollmentGroup...");
           var certificate = new X509Certificate2(X509RootCertPath);
           Attestation attestation = X509Attestation.CreateFromRootCertificates(certificate);
           EnrollmentGroup enrollmentGroup =
                   new EnrollmentGroup(
                           EnrollmentGroupId,
                           attestation)
                   {
                       ProvisioningStatus = ProvisioningStatus.Enabled
                   };
           Console.WriteLine(enrollmentGroup);
           #endregion
   
           #region Create the enrollmentGroup
           Console.WriteLine("\nAdding new enrollmentGroup...");
           EnrollmentGroup enrollmentGroupResult =
               await provisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync(enrollmentGroup).ConfigureAwait(false);
           Console.WriteLine("\nEnrollmentGroup created with success.");
           Console.WriteLine(enrollmentGroupResult);
           #endregion
   
       }
   }
   

9. Finally, replace the Main method with the following lines:

   static async Task Main(string[] args)
   {
       await RunSample();
       Console.WriteLine("\nHit <Enter> to exit ...");
       Console.ReadLine();
   }
   

10. Save your changes.

This section shows you how to create a Node.js script that adds an enrollment group to your provisioning service.

1. From a command window in your working folder, run:

   npm install azure-iot-provisioning-service
   

   This step downloads, installs, and adds a reference to the Azure IoT DPS service client package and its dependencies. This package includes the binaries for the Node.js service SDK.

2. Using a text editor, create a create_enrollment_group.js file in your working folder. Add the following code to the file and save:

       'use strict';
       var fs = require('fs');
   
       var provisioningServiceClient = require('azure-iot-provisioning-service').ProvisioningServiceClient;
   
       var serviceClient = provisioningServiceClient.fromConnectionString(process.argv[2]);
   
       var enrollment = {
         enrollmentGroupId: 'first',
         attestation: {
           type: 'x509',
           x509: {
             signingCertificates: {
               primary: {
                 certificate: fs.readFileSync(process.argv[3], 'utf-8').toString()
               }
             }
           }
         },
         provisioningStatus: 'disabled'
       };
   
       serviceClient.createOrUpdateEnrollmentGroup(enrollment, function(err, enrollmentResponse) {
         if (err) {
           console.log('error creating the group enrollment: ' + err);
         } else {
           console.log("enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2));
           enrollmentResponse.provisioningStatus = 'enabled';
           serviceClient.createOrUpdateEnrollmentGroup(enrollmentResponse, function(err, enrollmentResponse) {
             if (err) {
               console.log('error updating the group enrollment: ' + err);
             } else {
               console.log("updated enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2));
             }
           });
         }
       });
   

1. Open a Windows command prompt.

2. Clone the GitHub repo for device enrollment code sample using the Java Service SDK:

   git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
   

3. From the location where you downloaded the repo, go to the sample folder:

   cd azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample 
   

4. Open the file /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java in an editor of your choice.

5. Replace [Provisioning Connection String] with the connection string that you copied in Get the connection string for your provisioning service.

6. Replace the PUBLIC_KEY_CERTIFICATE_STRING constant string with the value of your root or intermediate CA certificate .pem file. This file represents the public part of a either a root CA X.509 certificate that has been previously uploaded and verified with your provisioning service, or an intermediate certificate that has itself been uploaded and verified or had a certificate in its signing chain uploaded and verified.

   The syntax of certificate text must follow the pattern below with no extra spaces or characters.

   private static final String PUBLIC_KEY_CERTIFICATE_STRING = 
           "-----BEGIN CERTIFICATE-----\n" +
           "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
               ...
           "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
           "-----END CERTIFICATE-----";
   

   Updating this string value manually can be prone to error. To generate the proper syntax, you can copy and paste the following command into a Git Bash prompt, replace your-cert.pem with the location of your certificate file, and press ENTER. This command generates the syntax for the PUBLIC_KEY_CERTIFICATE_STRING string constant value and writes it to the output.

   sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' your-cert.pem
   

   Copy and paste the output certificate text for the constant value.

   Important

   In production code, be aware of the following security considerations:

   • Hard-coding the connection string for the provisioning service administrator is against security best practices. Instead, the connection string should be held in a secure manner, such as in a secure configuration file or in the registry.
   • Be sure to upload only the public part of the signing certificate. Never upload .pfx (PKCS12) or .pem files containing private keys to the provisioning service.

7. The sample allows you to set an IoT hub in the enrollment group to provision the device to. This must be an IoT hub that has been previously linked to the provisioning service. For this article, we let DPS choose from the linked hubs according to the default allocation policy, evenly weighted distribution. Comment out the following statement in the file:

   enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);                // Optional parameter.
   

8. The sample code creates, updates, queries, and deletes an enrollment group for X.509 devices. To verify successful creation of the enrollment group in Azure portal, comment out the following lines of code near the end of the file:

   // ************************************** Delete info of enrollmentGroup ***************************************
   System.out.println("\nDelete the enrollmentGroup...");
   provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);
   

9. Save the ServiceEnrollmentGroupSample.java file.

1. Run the sample:

   dotnet run
   

2. Upon successful creation, the command window displays the properties of the new enrollment group.

1. Run the following command in your command prompt. Include the quotes around the command arguments and replace <connection string> withe connection string you copied in the previous section, and <certificate .pem file> with the path to your certificate .pem file. This file represents the public part of a either a root CA X.509 certificate that has been previously uploaded and verified with your provisioning service, or an intermediate certificate that has itself been uploaded and verified or had a certificate in its signing chain uploaded and verified.

   node create_enrollment_group.js "<connection string>" "<certificate .pem file>"
   

2. Upon successful creation, the command window displays the properties of the new enrollment group.

1. From the azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample folder in your command prompt, run the following command to build the sample:

   mvn install -DskipTests
   

   This command downloads the Azure IoT DPS service client Maven package to your machine and builds the sample. This package includes the binaries for the Java service SDK.

2. Switch to the target folder and run the sample. The build in the previous step outputs .jar file in the target folder with the following file format: provisioning-x509-sample-{version}-with-deps.jar; for example: provisioning-x509-sample-1.8.1-with-deps.jar. You may need to replace the version in the command below.

   cd target
   java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar
   

3. Upon successful creation, the command window displays the properties of the new enrollment group.

The Azure IoT C SDK has scripts that can help you create and manage certificates. To learn more, see Managing test CA certificates for samples and tutorials.

The Azure IoT Node.js SDK has scripts that can help you create and manage certificates. To learn more, see Tools for the Azure IoT Device Provisioning Device SDK for Node.js.

You can also use tools available in the Azure IoT C SDK. To learn more, see Managing test CA certificates for samples and tutorials.

The Azure IoT Java SDK contains test tooling that can help you create and manage certificates. To learn more, see X509 certificate generator using DICE emulator.