Tutorial: Create and provision a simulated X.509 device using Java device and service SDK and group enrollments for IoT Hub Device Provisioning Service

Article
02/09/2022

These steps show how to simulate an X.509 device on your development machine running Windows OS, and use a code sample to connect this simulated device with the Device Provisioning Service and your IoT hub using enrollment groups.

Make sure to complete the steps in the Setup IoT Hub Device Provisioning Service with the Azure portal before you proceed.

Prerequisites

Make sure you have Java SE Development Kit 8 installed on your machine.
Download and install Maven.
Make sure git is installed on your machine and is added to the environment variables accessible to the command window. See Software Freedom Conservancy's Git client tools for the latest version of git tools to install, which includes the Git Bash, the command-line app that you can use to interact with your local Git repository.
Use the following Certificate Overview to create your test certificates.

Note

This step requires OpenSSL, which can either be built and installed from source or downloaded and installed from a 3rd-party such as this. If you have already created your root, intermediate and device certificates you may skip this step.
1. Run through the first two steps to create your root and intermediate certificates.
2. Sign in to the Azure portal, click on the All resources button on the left-hand menu and open your provisioning service.
  1. On the Device Provisioning Service summary blade, select Certificates and click the Add button at the top.
  2. Under the Add Certificate, enter the following information:
    - Enter a unique certificate name.
    - Select the RootCA.pem file you created.
    - Once complete, click the Save button.
  3. Select the newly created certificate:
    - Click Generate Verification Code. Copy the code generated.
    - Run the verification step. Enter the verification code or right-click to paste in your running PowerShell window. Press Enter.
    - Select the newly created verifyCert4.pem file in the Azure portal. Click Verify.
3. Finish by running the steps to create your device certificates and clean-up resources.
  
  Note
  
  When creating device certificates be sure to use only lower-case alphanumerics and hyphens in your device name.

Create a device enrollment entry

Open a command prompt. Clone the GitHub repo for Java SDK code samples:

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

In the downloaded source code, navigate to the sample folder azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-group-sample. Open the file /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java in an editor of your choice, and add the following details:
1. Add the [Provisioning Connection String] for your provisioning service, from the portal as following:
  1. Navigate to your provisioning service in the Azure portal.
  2. Open the Shared access policies, and select a policy that has the EnrollmentWrite permission.
  3. Copy the Primary key connection string.
  4. In the sample code file ServiceEnrollmentGroupSample.java, replace the [Provisioning Connection String] with the Primary key connection string.
```
private static final String PROVISIONING_CONNECTION_STRING = "[Provisioning Connection String]";
```
2. Open your intermediate signing certificate file in a text editor. Update the PUBLIC_KEY_CERTIFICATE_STRING value with the value of your intermediate signing certificate.
  
  If you generated your device certificates with Bash shell, ./certs/azure-iot-test-only.intermediate.cert.pem contains the intermediate certificate key. If your certs were generated with PowerShell, ./Intermediate1.pem will be your intermediate certificate file.
```
private static final String PUBLIC_KEY_CERTIFICATE_STRING =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";
```
3. Navigate to the IoT hub linked to your provisioning service in the Azure portal. Open the Overview tab for the hub, and copy the Hostname. Assign this Hostname to the IOTHUB_HOST_NAME parameter.
```
private static final String IOTHUB_HOST_NAME = "[Host name].azure-devices.net";
```
4. Study the sample code. It creates, updates, queries, and deletes a group enrollment for X.509 devices. To verify successful enrollment in portal, temporarily comment out the following lines of code at the end of the ServiceEnrollmentGroupSample.java file:
```
// ************************************** Delete info of enrollmentGroup ***************************************
System.out.println("\nDelete the enrollmentGroup...");
provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);
```
5. Save the file ServiceEnrollmentGroupSample.java.
Open a command window, and navigate to the folder azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-group-sample.
Build the sample code by using this command:
```
mvn install -DskipTests
```

Run the sample by using these commands at the command window:

cd target
java -jar ./service-enrollment-group-sample-{version}-with-deps.jar

Observe the output window for successful enrollment.
Navigate to your provisioning service in the Azure portal. Click Manage enrollments. Notice that your group of X.509 devices appears under the Enrollment Groups tab, with an auto-generated GROUP NAME.

Simulate the device

On the Device Provisioning Service summary blade, select Overview and note your ID Scope and Provisioning Service Global Endpoint.

Open a command prompt. Navigate to the sample project folder.

cd azure-iot-sdk-java/provisioning/provisioning-samples/provisioning-X509-sample

Edit /src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningX509Sample.java to include your ID Scope and Provisioning Service Global Endpoint that you noted previously.

private static final String idScope = "[Your ID scope here]";
private static final String globalEndpoint = "[Your Provisioning Service Global Endpoint here]";
private static final ProvisioningDeviceClientTransportProtocol PROVISIONING_DEVICE_CLIENT_TRANSPORT_PROTOCOL = ProvisioningDeviceClientTransportProtocol.HTTPS;
private static final int MAX_TIME_TO_WAIT_FOR_REGISTRATION = 10000; // in milli seconds
private static final String leafPublicPem = "<Your Public PEM Certificate here>";
private static final String leafPrivateKey = "<Your Private PEM Key here>";

Update the leafPublicPem and leafPrivateKey variables with your public and private device certificates.

If you generated your device certificates with PowerShell, the files mydevice* contain the public key, private key, and PFX for the device.

If you generated your device certificates with Bash shell, ./certs/new-device.cert.pem contains the public key. The device's private key will be in the ./private/new-device.key.pem file.

Open your public key file and update the leafPublicPem variable with that value. Copy the text from -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY-----.

private static final String leafPublicPem = "-----BEGIN CERTIFICATE-----\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "-----END CERTIFICATE-----\n";

Open your private key file and update the leafPrivatePem variable with that value. Copy the text from -----BEGIN RSA PRIVATE KEY----- to -----END RSA PRIVATE KEY-----.

private static final String leafPrivateKey = "-----BEGIN RSA PRIVATE KEY-----\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "-----END RSA PRIVATE KEY-----\n";

Add a new variable just below leafPrivateKey for your intermediate certificate. Name this new variable intermediateKey. Give it the value of your intermediate signing certificate.

If you generated your device certificates with Bash shell, ./certs/azure-iot-test-only.intermediate.cert.pem contains the intermediate certificate key. If your certs were generated with PowerShell, ./Intermediate1.pem will be your intermediate certificate file.

private static final String intermediateKey = "-----BEGIN CERTIFICATE-----\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
    "-----END CERTIFICATE-----\n";

In the main function, add the intermediateKey to the signerCertificates collection before the initialization of securityProviderX509.

public static void main(String[] args) throws Exception
{
    ...

    try
    {
        ProvisioningStatus provisioningStatus = new ProvisioningStatus();

        // Add intermediate certificate as part of the certificate key chain.
        signerCertificates.add(intermediateKey);

        SecurityProvider securityProviderX509 = new SecurityProviderX509Cert(leafPublicPem, leafPrivateKey, signerCertificates);

Save your changes and build the sample. Navigate to the target folder and execute the created jar file.
```
mvn clean install
cd target
java -jar ./provisioning-x509-sample-{version}-with-deps.jar
```
In the portal, navigate to the IoT hub linked to your provisioning service and open the Device Explorer blade. On successful provisioning of the simulated X.509 device to the hub, its device ID appears on the Device Explorer blade, with STATUS as enabled. Note that you might need to click the Refresh button at the top if you already opened the blade prior to running the sample device application.

Clean up resources

If you plan to continue working on and exploring the device client sample, do not clean up the resources created in this Quickstart. If you do not plan to continue, use the following steps to delete all resources created by this Quickstart.

Close the device client sample output window on your machine.
From the left-hand menu in the Azure portal, click All resources and then select your Device Provisioning Service. Open the Manage Enrollments blade for your service, and then click the Individual Enrollments tab. Select the REGISTRATION ID of the device you enrolled in this Quickstart, and click the Delete button at the top.
From the left-hand menu in the Azure portal, click All resources and then select your IoT hub. Open the IoT Devices blade for your hub, select the DEVICE ID of the device you registered in this Quickstart, and then click Delete button at the top.

Next steps

In this tutorial, you’ve created a simulated X.509 device on your Windows machine and provisioned it to your IoT hub using the Azure IoT Hub Device Provisioning Service and enrollment groups. To learn more about your X.509 device, continue to device concepts.

IoT Hub Device Provisioning Service concepts