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

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.

Prepare the environment

  1. Make sure you have Java SE Development Kit 8 installed on your machine.

  2. Download and install Maven.

  3. 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.

  4. Use the following Certifcate 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. Log 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 just created.
        • Once complete, click the Save button.

        Add certificate

      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.

          Validate certificate

    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

  1. 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
    
  2. 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 which has the EnrollmentWrite permission.

      3. Copy the Primary key connection string.

        Get the provisioning connection string from portal

      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 the RootCA.pem file in a text editor. Assign the value of the Root Cert to the parameter PUBLIC_KEY_CERTIFICATE_STRING as shown below:

      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.

  3. Open a command window, and navigate to the folder azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-group-sample.

  4. Build the sample code by using this command:

    mvn install -DskipTests
    
  5. Run the sample by using these commands at the command window:

    cd target
    java -jar ./service-enrollment-group-sample-{version}-with-deps.jar
    
  6. Observe the output window for successful enrollment.

    Successful enrollment

  7. 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

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

    Service information

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

    cd azure-iot-sdk-java/provisioning/provisioning-samples/provisioning-X509-sample
    
  3. Enter the enrollment group information in the following way:

    • Edit /src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningX509Sample.java to include your Id Scope and Provisioning Service Global Endpoint as noted before. Open your {deviceName}-public.pem file and include this value as your Client Cert. Open your {deviceName}-all.pem file and copy the text from -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY-----. Use this as your Client Cert Private Key.

      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 String leafPublicPem = "<Your Public PEM Certificate here>";
      private static final String leafPrivateKey = "<Your Private PEM Key here>";
      
      • Use the following format for including your certificate and key:

        private static final String leafPublicPem = "-----BEGIN CERTIFICATE-----\n" +
            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
            "+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
            "-----END CERTIFICATE-----\n";
        private static final String leafPrivateKey = "-----BEGIN PRIVATE KEY-----\n" +
            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
            "XXXXXXXXXX\n" +
            "-----END PRIVATE KEY-----\n";
        
  4. 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
    

    Successful registration

  5. 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.

    Device is registered with the IoT hub

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.

  1. Close the device client sample output window on your machine.
  2. 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.
  3. 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.