Tutorial: Provision multiple X.509 devices using enrollment groups

Article
03/28/2023

In this tutorial, you'll learn how to provision groups of IoT devices that use X.509 certificates for authentication. Sample device code from the Azure IoT SDK will be executed on your development machine to simulate provisioning of X.509 devices. On real devices, device code would be deployed and run from the IoT device.

The Azure IoT Hub Device Provisioning Service supports two types of enrollments for provisioning devices:

Enrollment groups: Used to enroll multiple related devices. This tutorial demonstrates provisioning with enrollment groups.
Individual Enrollments: Used to enroll a single device.

The Azure IoT Hub Device Provisioning Service supports three forms of authentication for provisioning devices:

X.509 certificates. This tutorial demonstrates X.509 certificate attestation.
Trusted platform module (TPM)
Symmetric keys

This tutorial uses the custom HSM sample, which provides a stub implementation for interfacing with hardware-based secure storage. A Hardware Security Module (HSM) is used for secure, hardware-based storage of device secrets. An HSM can be used with symmetric key, X.509 certificate, or TPM attestation to provide secure storage for secrets. Hardware-based storage of device secrets isn't required, but it's strongly recommended to help protect sensitive information like your device certificate's private key.

A Hardware Security Module (HSM) is used for secure, hardware-based storage of device secrets. An HSM can be used with symmetric key, X.509 certificate, or TPM attestation to provide secure storage for secrets. Hardware-based storage of device secrets isn't required, but it's strongly recommended to help protect sensitive information like your device certificate's private key.

In this tutorial, you'll complete the following objectives:

Create a certificate chain of trust to organize a set of devices using X.509 certificates.
Complete proof of possession with a signing certificate used with the certificate chain.
Create a new group enrollment that uses the certificate chain.
Set up the development environment.
Provision a device using the certificate chain using sample code in the Azure IoT device SDK.

Prerequisites

If you don't have an Azure subscription, create a free account before you begin.
Complete the steps in Set up IoT Hub Device Provisioning Service with the Azure portal.

The following prerequisites are for a Windows development environment used to simulate the devices. For Linux or macOS, see the appropriate section in Prepare your development environment in the SDK documentation.

Install Visual Studio 2022 with the 'Desktop development with C++' workload enabled. Visual Studio 2015, Visual Studio 2017, and Visual Studio 19 are also supported.
Install the latest CMake build system. Make sure you check the option that adds the CMake executable to your path.

Important

Confirm that the Visual Studio prerequisites (Visual Studio and the 'Desktop development with C++' workload) are installed on your machine, before starting the CMake installation. Once the prerequisites are in place, and the download is verified, install the CMake build system. Also, be aware that older versions of the CMake build system fail to generate the solution file used in this tutorial. Make sure to use the latest version of CMake.

The following prerequisites are for a Windows development environment. For Linux or macOS, see the appropriate section in Prepare your development environment in the SDK documentation.

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

The following prerequisites are for a Windows development environment. For Linux or macOS, see the appropriate section in Prepare your development environment in the SDK documentation.

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

The following prerequisites are for a Windows development environment.

Python 3.6 or later on your machine.

The following prerequisites are for a Windows development environment. For Linux or macOS, see the appropriate section in Prepare your development environment in the SDK documentation.

Install the Java SE Development Kit 8 or later on your machine.
Download and install Maven.

Install the latest version of Git. Make sure that Git 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 Git Bash, the command-line app that you can use to interact with your local Git repository.
Make sure OpenSSL is installed on your machine. On Windows, your installation of Git includes an installation of OpenSSL. You can access OpenSSL from the Git Bash prompt. To verify that OpenSSL is installed, open a Git Bash prompt and enter openssl version.

Note

Unless you're familiar with OpenSSL and already have it installed on your Windows machine, we recommend using OpenSSL from the Git Bash prompt. Alternatively, you can choose to download the source code and build OpenSSL. To learn more, see the OpenSSL Downloads page. Or, you can download OpenSSL pre-built from a third-party. To learn more, see the OpenSSL wiki. Microsoft makes no guarantees about the validity of packages downloaded from third-parties. If you do choose to build or download OpenSSL make sure that the OpenSSL binary is accessible in your path and that the OPENSSL_CNF environment variable is set to the path of your openssl.cnf file.
Open both a Windows command prompt and a Git Bash prompt.

The steps in this tutorial assume that you're using a Windows machine and the OpenSSL installation that is installed as part of Git. You'll use the Git Bash prompt to issue OpenSSL commands and the Windows command prompt for everything else. If you're using Linux, you can issue all commands from a Bash shell.

Prepare your development environment

In this section, you'll prepare a development environment used to build the Azure IoT C SDK. The SDK includes sample code and tools used by devices provisioning with DPS.

Open a web browser, and go to the Release page of the Azure IoT C SDK.
Select the Tags tab at the top of the page.
Copy the tag name for the latest release of the Azure IoT C SDK.
In your Windows command prompt, run the following commands to clone the latest release of the Azure IoT Device SDK for C GitHub repository. Replace <release-tag> with the tag you copied in the previous step, for example: lts_01_2023.
```
git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
This operation could take several minutes to complete.
When the operation is complete, run the following commands from the azure-iot-sdk-c directory:
```
mkdir cmake
cd cmake
```
The code sample uses an X.509 certificate to provide attestation via X.509 authentication. Run the following command to build a version of the SDK specific to your development platform that includes the device provisioning client. A Visual Studio solution for the simulated device is generated in the cmake directory.

When specifying the path used with -Dhsm_custom_lib in the command below, make sure to use the absolute path to the library in the cmake directory you previously created. The path shown below assumes that you cloned the C SDK in the root directory of the C drive. If you used another directory, adjust the path accordingly.
```
cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..
```
Tip

If cmake doesn't find your C++ compiler, you may get build errors while running the above command. If that happens, try running the command in the Visual Studio command prompt.

When the build succeeds, the last few output lines look similar to the following output:

cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..
-- Building for: Visual Studio 17 2022
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.22000.
-- The C compiler identification is MSVC 19.32.31329.0
-- The CXX compiler identification is MSVC 19.32.31329.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: C:/azure-iot-sdk-c/cmake

In your Windows command prompt, clone the Azure IoT SDK for C# GitHub repository using the following command:

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

In your Windows command prompt, clone the Azure IoT SDK for Node.js GitHub repository using the following command:

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

In your Windows command prompt, clone the Azure IoT Device SDK for Python GitHub repository using the following command:

git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive

Note

The samples used in this tutorial are in the v2 branch of the azure-iot-sdk-python repository. V3 of the Python SDK is available to use in beta. For information about updating V2 code samples to use a V3 release of the Python SDK, see Azure IoT Device SDK for Python migration guide.

In your Windows command prompt, clone the Azure IoT Samples for Java GitHub repository using the following command:
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```
Go to the root azure-iot-sdk-java directory and build the project to download all needed packages.
```
cd azure-iot-sdk-java
mvn install -DskipTests=true
```

Create an X.509 certificate chain

In this section, you'll generate an X.509 certificate chain of three certificates for testing each device with this tutorial. The certificates have the following hierarchy.

Diagram that shows relationship of root C A, intermediate C A, and device certificates.

Root certificate: You'll complete proof of possession to verify the root certificate. This verification enables DPS to trust that certificate and verify certificates signed by it.

Intermediate certificate: It's common to use intermediate certificates to group devices logically by product lines, company divisions, or other criteria. This tutorial uses a certificate chain with one intermediate certificate, but in a production scenario you may have several. The intermediate certificate in this chain is signed by the root certificate. This certificate is provided to the enrollment group created in DPS to logically group a set of devices. This configuration allows managing a whole group of devices that have device certificates signed by the same intermediate certificate.

Device certificates: The device certificates (sometimes called leaf certificates) will be signed by the intermediate certificate and stored on the device along with its private key. Ideally these sensitive items would be stored securely with an HSM. Each device presents its certificate and private key, along with the certificate chain, when attempting provisioning.

Set up the X.509 OpenSSL environment

In this section, you'll create the Openssl configuration files, directory structure, and other files used by the Openssl commands.

In your Git Bash command prompt, navigate to a folder where you want to generate the X.509 certificates and keys for this tutorial.

Create an OpenSSL configuration file for your root CA certificate. OpenSSL configuration files contain policies and definitions that are consumed by OpenSSL commands. Copy and paste the following text into a file named openssl_root_ca.cnf:

# OpenSSL root CA configuration file.

[ ca ]
default_ca = CA_default

[ CA_default ]
# Directory and file locations.
dir               = .
certs             = $dir/certs
crl_dir           = $dir/crl
new_certs_dir     = $dir/newcerts
database          = $dir/index.txt
serial            = $dir/serial
RANDFILE          = $dir/private/.rand

# The root key and root certificate.
private_key       = $dir/private/azure-iot-test-only.root.ca.key.pem
certificate       = $dir/certs/azure-iot-test-only.root.ca.cert.pem

# For certificate revocation lists.
crlnumber         = $dir/crlnumber
crl               = $dir/crl/azure-iot-test-only.intermediate.crl.pem
crl_extensions    = crl_ext
default_crl_days  = 30

# SHA-1 is deprecated, so use SHA-2 instead.
default_md        = sha256

name_opt          = ca_default
cert_opt          = ca_default
default_days      = 375
preserve          = no
policy            = policy_loose

[ policy_strict ]
# The root CA should only sign intermediate certificates that match.
countryName             = optional
stateOrProvinceName     = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional

[ policy_loose ]
# Allow the intermediate CA to sign a more diverse range of certificates.
countryName             = optional
stateOrProvinceName     = optional
localityName            = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional

[ req ]
default_bits        = 2048
distinguished_name  = req_distinguished_name
string_mask         = utf8only

# SHA-1 is deprecated, so use SHA-2 instead.
default_md          = sha256

# Extension to add when the -x509 option is used.
x509_extensions     = v3_ca

[ req_distinguished_name ]
# See <https://en.wikipedia.org/wiki/Certificate_signing_request>.
countryName                     = Country Name (2 letter code)
stateOrProvinceName             = State or Province Name
localityName                    = Locality Name
0.organizationName              = Organization Name
organizationalUnitName          = Organizational Unit Name
commonName                      = Common Name
emailAddress                    = Email Address

# Optionally, specify some defaults.
countryName_default             = US
stateOrProvinceName_default     = WA
localityName_default            =
0.organizationName_default      = My Organization
organizationalUnitName_default  =
emailAddress_default            =

[ v3_ca ]
# Extensions for a typical CA.
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, digitalSignature, cRLSign, keyCertSign

[ v3_intermediate_ca ]
# Extensions for a typical intermediate CA.
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, digitalSignature, cRLSign, keyCertSign

[ usr_cert ]
# Extensions for client certificates.
basicConstraints = CA:FALSE
nsComment = "OpenSSL Generated Client Certificate"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth

[ server_cert ]
# Extensions for server certificates.
basicConstraints = CA:FALSE
nsComment = "OpenSSL Generated Server Certificate"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer:always
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth

[ crl_ext ]
# Extension for CRLs.
authorityKeyIdentifier=keyid:always

[ ocsp ]
# Extension for OCSP signing certificates.
basicConstraints = CA:FALSE
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
keyUsage = critical, digitalSignature
extendedKeyUsage = critical, OCSPSigning

Create an OpenSSL configuration file to use for intermediate and device certificates. Copy and paste the following text into a file named openssl_device_intermediate_ca.cnf:

# OpenSSL root CA configuration file.

[ ca ]
default_ca = CA_default

[ CA_default ]
# Directory and file locations.
dir               = .
certs             = $dir/certs
crl_dir           = $dir/crl
new_certs_dir     = $dir/newcerts
database          = $dir/index.txt
serial            = $dir/serial
RANDFILE          = $dir/private/.rand

# The root key and root certificate.
private_key       = $dir/private/azure-iot-test-only.intermediate.key.pem
certificate       = $dir/certs/azure-iot-test-only.intermediate.cert.pem

# For certificate revocation lists.
crlnumber         = $dir/crlnumber
crl               = $dir/crl/azure-iot-test-only.intermediate.crl.pem
crl_extensions    = crl_ext
default_crl_days  = 30

# SHA-1 is deprecated, so use SHA-2 instead.
default_md        = sha256

name_opt          = ca_default
cert_opt          = ca_default
default_days      = 375
preserve          = no
policy            = policy_loose

[ policy_strict ]
# The root CA should only sign intermediate certificates that match.
countryName             = optional
stateOrProvinceName     = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional

[ policy_loose ]
# Allow the intermediate CA to sign a more diverse range of certificates.
countryName             = optional
stateOrProvinceName     = optional
localityName            = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional

[ req ]
default_bits        = 2048
distinguished_name  = req_distinguished_name
string_mask         = utf8only

# SHA-1 is deprecated, so use SHA-2 instead.
default_md          = sha256

# Extension to add when the -x509 option is used.
x509_extensions     = v3_ca

[ req_distinguished_name ]
# See <https://en.wikipedia.org/wiki/Certificate_signing_request>.
countryName                     = Country Name (2 letter code)
stateOrProvinceName             = State or Province Name
localityName                    = Locality Name
0.organizationName              = Organization Name
organizationalUnitName          = Organizational Unit Name
commonName                      = Common Name
emailAddress                    = Email Address

# Optionally, specify some defaults.
countryName_default             = US
stateOrProvinceName_default     = WA
localityName_default            =
0.organizationName_default      = My Organization
organizationalUnitName_default  =
emailAddress_default            =

[ v3_ca ]
# Extensions for a typical CA.
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, digitalSignature, cRLSign, keyCertSign

[ v3_intermediate_ca ]
# Extensions for a typical intermediate CA.
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, digitalSignature, cRLSign, keyCertSign

[ usr_cert ]
# Extensions for client certificates.
basicConstraints = CA:FALSE
nsComment = "OpenSSL Generated Client Certificate"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth

[ server_cert ]
# Extensions for server certificates.
basicConstraints = CA:FALSE
nsComment = "OpenSSL Generated Server Certificate"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer:always
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth

[ crl_ext ]
# Extension for CRLs.
authorityKeyIdentifier=keyid:always

[ ocsp ]
# Extension for OCSP signing certificates.
basicConstraints = CA:FALSE
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
keyUsage = critical, digitalSignature
extendedKeyUsage = critical, OCSPSigning

Create the directory structure, the database file (index.txt), and the serial number file (serial) used by OpenSSL commands in this tutorial:
```
mkdir certs csr newcerts private
touch index.txt
openssl rand -hex 16 > serial
```

Create the root CA certificate

Run the following commands to create the root CA private key and the root CA certificate. You'll use this certificate and key to sign your intermediate certificate.

Create the root CA private key:

openssl genrsa -aes256 -passout pass:1234 -out ./private/azure-iot-test-only.root.ca.key.pem 4096

Create the root CA certificate:

Windows
Linux

openssl req -new -x509 -config ./openssl_root_ca.cnf -passin pass:1234 -key ./private/azure-iot-test-only.root.ca.key.pem -subj '//CN=Azure IoT Hub CA Cert Test Only' -days 30 -sha256 -extensions v3_ca -out ./certs/azure-iot-test-only.root.ca.cert.pem

Important

The extra forward slash given for the subject name (//CN=Azure IoT Hub CA Cert Test Only) is only required to escape the string with Git on Windows platforms.

openssl req -new -x509 -config ./openssl_root_ca.cnf -passin pass:1234 -key ./private/azure-iot-test-only.root.ca.key.pem -subj '/CN=Azure IoT Hub CA Cert Test Only' -days 30 -sha256 -extensions v3_ca -out ./certs/azure-iot-test-only.root.ca.cert.pem

Examine the root CA certificate:

openssl x509 -noout -text -in ./certs/azure-iot-test-only.root.ca.cert.pem

Observe that the Issuer and the Subject are both the root CA.

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            1d:93:13:0e:54:07:95:1d:8c:57:4f:12:14:b9:5e:5f:15:c3:a9:d4
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = Azure IoT Hub CA Cert Test Only
        Validity
            Not Before: Jun 20 22:52:23 2022 GMT
            Not After : Jul 20 22:52:23 2022 GMT
        Subject: CN = Azure IoT Hub CA Cert Test Only
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (4096 bit)

Create the intermediate CA certificate

Run the following commands to create the intermediate CA private key and the intermediate CA certificate. You'll use this certificate and key to sign your device certificate(s).

Create the intermediate CA private key:

openssl genrsa -aes256 -passout pass:1234 -out ./private/azure-iot-test-only.intermediate.key.pem 4096

Create the intermediate CA certificate signing request (CSR):

Windows
Linux

openssl req -new -sha256 -passin pass:1234 -config ./openssl_device_intermediate_ca.cnf -subj '//CN=Azure IoT Hub Intermediate Cert Test Only' -key ./private/azure-iot-test-only.intermediate.key.pem -out ./csr/azure-iot-test-only.intermediate.csr.pem

Important

The extra forward slash given for the subject name (//CN=Azure IoT Hub Intermediate Cert Test Only) is only required to escape the string with Git on Windows platforms.

openssl req -new -sha256 -passin pass:1234 -config ./openssl_device_intermediate_ca.cnf -subj '/CN=Azure IoT Hub Intermediate Cert Test Only' -key ./private/azure-iot-test-only.intermediate.key.pem -out ./csr/azure-iot-test-only.intermediate.csr.pem

Sign the intermediate certificate with the root CA certificate

openssl ca -batch -config ./openssl_root_ca.cnf -passin pass:1234 -extensions v3_intermediate_ca -days 30 -notext -md sha256 -in ./csr/azure-iot-test-only.intermediate.csr.pem -out ./certs/azure-iot-test-only.intermediate.cert.pem

Examine the intermediate CA certificate:

openssl x509 -noout -text -in ./certs/azure-iot-test-only.intermediate.cert.pem

Observe that the Issuer is the root CA, and the Subject is the intermediate CA.

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            d9:55:87:57:41:c8:4c:47:6c:ee:ba:83:5d:ae:db:39
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = Azure IoT Hub CA Cert Test Only
        Validity
            Not Before: Jun 20 22:54:01 2022 GMT
            Not After : Jul 20 22:54:01 2022 GMT
        Subject: CN = Azure IoT Hub Intermediate Cert Test Only
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (4096 bit)

Create the device certificates

In this section, you create two device certificates and their full chain certificates. The full chain certificate contains the device certificate, the intermediate CA certificate, and the root CA certificate. The device must present its full chain certificate when it registers with DPS.

Create the first device private key.

openssl genrsa -out ./private/device-01.key.pem 4096

Create the device certificate CSR.

The subject common name (CN) of the device certificate must be set to the registration ID that your device will use to register with DPS. The registration ID is a case-insensitive string of alphanumeric characters plus the special characters: '-', '.', '_', ':'. The last character must be alphanumeric or dash ('-'). The common name must adhere to this format. DPS supports registration IDs up to 128 characters long; however, the maximum length of the subject common name in an X.509 certificate is 64 characters. The registration ID, therefore, is limited to 64 characters when using X.509 certificates. For group enrollments, the registration ID is also used as the device ID in IoT Hub.

The subject common name is set using the -subj parameter. In the following command, the common name is set to device-01.
- Windows
- Linux
```
openssl req -config ./openssl_device_intermediate_ca.cnf -key ./private/device-01.key.pem -subj '//CN=device-01' -new -sha256 -out ./csr/device-01.csr.pem
```
Important

The extra forward slash given for the subject name (//CN=device-01) is only required to escape the string with Git on Windows platforms.
```
openssl req -config ./openssl_device_intermediate_ca.cnf -key ./private/device-01.key.pem -subj '/CN=device-01' -new -sha256 -out ./csr/device-01.csr.pem
```

Sign the device certificate.

openssl ca -batch -config ./openssl_device_intermediate_ca.cnf -passin pass:1234 -extensions usr_cert -days 30 -notext -md sha256 -in ./csr/device-01.csr.pem -out ./certs/device-01.cert.pem

Examine the device certificate:

openssl x509 -noout -text -in ./certs/device-01.cert.pem

Observe that the Issuer is the intermediate CA, and the Subject is the device registration ID, device-01.

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            d9:55:87:57:41:c8:4c:47:6c:ee:ba:83:5d:ae:db:3a
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = Azure IoT Hub Intermediate Cert Test Only
        Validity
            Not Before: Jun 20 22:55:39 2022 GMT
            Not After : Jul 20 22:55:39 2022 GMT
        Subject: CN = device-01
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (4096 bit)

The device must present the full certificate chain when it authenticates with DPS. Use the following command to create the certificate chain:

cat ./certs/device-01.cert.pem ./certs/azure-iot-test-only.intermediate.cert.pem ./certs/azure-iot-test-only.root.ca.cert.pem > ./certs/device-01-full-chain.cert.pem

Open the certificate chain file, ./certs/device-01-full-chain.cert.pem, in a text editor to examine it. The certificate chain text contains the full chain of all three certificates. You'll use this certificate chain later in this tutorial to provision device-01.

The full chain text has the following format:

To create the private key, X.509 certificate, and full chain certificate for the second device, copy and paste this script into your Git Bash command prompt. To create certificates for more devices, you can modify the registration_id variable declared at the beginning of the script.

Windows
Linux

registration_id=device-02
echo $registration_id
openssl genrsa -out ./private/${registration_id}.key.pem 4096
openssl req -config ./openssl_device_intermediate_ca.cnf -key ./private/${registration_id}.key.pem -subj "//CN=$registration_id" -new -sha256 -out ./csr/${registration_id}.csr.pem
openssl ca -batch -config ./openssl_device_intermediate_ca.cnf -passin pass:1234 -extensions usr_cert -days 30 -notext -md sha256 -in ./csr/${registration_id}.csr.pem -out ./certs/${registration_id}.cert.pem
cat ./certs/${registration_id}.cert.pem ./certs/azure-iot-test-only.intermediate.cert.pem ./certs/azure-iot-test-only.root.ca.cert.pem > ./certs/${registration_id}-full-chain.cert.pem

registration_id=device-02
echo $registration_id
openssl genrsa -out ./private/${registration_id}.key.pem 4096
openssl req -config ./openssl_device_intermediate_ca.cnf -key ./private/${registration_id}.key.pem -subj "/CN=$registration_id" -new -sha256 -out ./csr/${registration_id}.csr.pem
openssl ca -batch -config ./openssl_device_intermediate_ca.cnf -passin pass:1234 -extensions usr_cert -days 30 -notext -md sha256 -in ./csr/${registration_id}.csr.pem -out ./certs/${registration_id}.cert.pem
cat ./certs/${registration_id}.cert.pem ./certs/azure-iot-test-only.intermediate.cert.pem ./certs/azure-iot-test-only.root.ca.cert.pem > ./certs/${registration_id}-full-chain.cert.pem

Note

This script uses the registration ID as the base filename for the private key and certificate files. If your registration ID contains characters that aren't valid filename characters, you'll need to modify the script accordingly.

Warning

The text for the certificates only contains public key information.

However, the device must also have access to the private key for the device certificate. This is necessary because the device must perform verification using that key at runtime when it attempts to provision. The sensitivity of this key is one of the main reasons it is recommended to use hardware-based storage in a real HSM to help secure private keys.

You'll use the following files in the rest of this tutorial:

Certificate	File	Description
root CA certificate.	certs/azure-iot-test-only.root.ca.cert.pem	Will be uploaded to DPS and verified.
intermediate CA certificate	certs/azure-iot-test-only.intermediate.cert.pem	Will be used to create an enrollment group in DPS.
device-01 private key	private/device-01.key.pem	Used by the device to verify ownership of the device certificate during authentication with DPS.
device-01 full chain certificate	certs/device-01-full-chain.cert.pem	Presented by the device to authenticate and register with DPS.
device-02 private key	private/device-02.key.pem	Used by the device to verify ownership of the device certificate during authentication with DPS.
device-02 full chain certificate	certs/device-02-full-chain.cert.pem	Presented by the device to authenticate and register with DPS.

Verify ownership of the root certificate

For DPS to be able to validate the device's certificate chain during authentication, you must upload and verify ownership of the root CA certificate. Because you created the root CA certificate in the last section, you'll auto-verify that it's valid when you upload it. Alternatively, you can do manual verification of the certificate if you're using a CA certificate from a 3rd-party. To learn more about verifying CA certificates, see How to do proof-of-possession for X.509 CA certificates.

To add the root CA certificate to your DPS instance, follow these steps:

Sign in to the Azure portal, select the All resources button on the left-hand menu and open your Device Provisioning Service instance.
Open Certificates from the left-hand menu and then select + Add at the top of the panel to add a new certificate.
Enter a friendly display name for your certificate. Browse to the location of the root CA certificate file certs/azure-iot-test-only.root.ca.cert.pem. Select Upload.
Select the box next to Set certificate status to verified on upload.
Select Save.
Make sure your certificate is shown in the certificate tab with a status of Verified.

(Optional) Manual verification of root certificate

If you didn't choose to automatically verify the certificate during upload, you manually prove possession:

Select the new CA certificate.
Select Generate Verification Code in the Certificate Details dialog.
Create a certificate that contains the verification code. For example, if you're using the Bash script supplied by Microsoft, run ./certGen.sh create_verification_certificate "<verification code>" to create a certificate named verification-code.cert.pem, replacing <verification code> with the previously generated verification code. For more information, you can download the files relevant to your system to a working folder and follow the instructions in the Managing CA certificates readme to perform proof-of-possession on a CA certificate.
Upload verification-code.cert.pem to your provisioning service in the Certificate Details dialog.
Select Verify.

Update the certificate store on Windows-based devices

On non-Windows devices, you can pass the certificate chain from the code as the certificate store.

On Windows-based devices, you must add the signing certificates (root and intermediate) to a Windows certificate store. Otherwise, the signing certificates won't be transported to DPS by a secure channel with Transport Layer Security (TLS).

Tip

It's also possible to use OpenSSL instead of secure channel (Schannel) with the C SDK. For more information on using OpenSSL, see Using OpenSSL in the SDK.

To add the signing certificates to the certificate store in Windows-based devices:

In a Git bash prompt, convert your signing certificates to .pfx as follows.

Root CA certificate:

openssl pkcs12 -inkey ./private/azure-iot-test-only.root.ca.key.pem -in ./certs/azure-iot-test-only.root.ca.cert.pem -export -passin pass:1234 -passout pass:1234 -out ./certs/root.pfx

Intermediate CA certificate:

openssl pkcs12 -inkey ./private/azure-iot-test-only.intermediate.key.pem -in ./certs/azure-iot-test-only.intermediate.cert.pem -export -passin pass:1234 -passout pass:1234 -out ./certs/intermediate.pfx

Right-click the Windows Start button. Then select Run. Enter certmgr.msc and select Ok to start certificate manager MMC snap-in.
In certificate manager, under Certificates - Current User, select Trusted Root Certification Authorities. Then on the menu, select Action > All Tasks > Import to import root.pfx.
- Make sure to search by Personal information Exchange (.pfx)
- Use 1234 as the password.
- Place the certificate in the Trusted Root Certification Authorities certificate store.
In certificate manager, under Certificates - Current User, select Intermediate Certification Authorities. Then on the menu, select Action > All Tasks > Import to import intermediate.pfx.
- Make sure to search by Personal information Exchange (.pfx)
- Use 1234 as the password.
- Place the certificate in the Intermediate Certification Authorities certificate store.

Your signing certificates are now trusted on the Windows-based device and the full chain can be transported to DPS.

Create an enrollment group

Sign in to the Azure portal and navigate to your Device Provisioning Service instance.
Select Manage enrollments from the Settings section of the navigation menu.
At the top of the page, select Add enrollment group.

On the Registration + provisioning tab of the Add enrollment group page, provide the following information to configure the enrollment group details:

Field	Description
Attestation	Select X.509 intermediate certificates as the Attestation mechanism if you want to upload intermediate certificates to be used for just this enrollment group, or select X.509 certificates uploaded to this Device Provisioning Service if you already have uploaded intermediate certificates.
X.509 certificate settings	Depending on the attestation method that you chose, either upload or select the primary and secondary intermediate certificates for this enrollment group.
Group name	Provide a name for the group of devices. The enrollment group name is a case-insensitive string (up to 128 characters long) of alphanumeric characters plus the special characters: `'-'`, `'.'`, `'_'`, `':'`. The last character must be alphanumeric or dash (`'-'`).
Provisioning status	Check the Enable this enrollment box if you want this enrollment group to be available to provision devices. Uncheck this box if you want the group to be disabled. You can change this setting later.
Reprovision policy	Choose a reprovision policy that reflects how you want DPS to handle devices that request reprovisioning. For more information, see Reprovision policies

Screenshot that shows adding an enrollment group for X.509 certificate attestation.

Select Next: IoT hubs.

On the IoT hubs tab of the Add enrollment group page, provide the following information to determine which IoT hubs the enrollment group can provision devices to:

Field	Description
Target IoT hubs	Select one or more of your linked IoT hubs, or add a new link to an IoT hub. To learn more about linking IoT hubs to your DPS instance, see How to link and manage IoT hubs.
Allocation policy	If you selected more than one linked IoT hub, select how you want to assign devices to the different hubs. To learn more about allocation policies, see How to use allocation policies. If you selected only one linked IoT hub, we recommend using the Evenly weighted distribution policy.

Screenshot that shows connecting IoT hubs to the new enrollment group.

Select Next: Device settings

On the Device settings tab of the Add enrollment group page, provide the following information to define how newly provisioned devices will be configured:

Field	Description
IoT Edge	Check the Enable IoT Edge on provisioned devices if all the devices provisioned through this group will run Azure IoT Edge. Uncheck this box if this group is for non-IoT Edge-enabled devices only. Either all devices in a group will be IoT Edge-enabled or none can be.
Device tags	Use this text box to provide any tags that you want to apply to the device twins of provisioned devices.
Desired properties	Use this text box to provide any desired properties that you want to apply to the device twins of provisioned devices.

For more information, see Understand and use device twins in IoT Hub.

Select Next: Review + create.
On the Review + create tab, verify all of your values then select Create.

Prepare and run the device provisioning code

In this section, you update the sample code with your Device Provisioning Service instance information. If a device is authenticated, it will be assigned to an IoT hub linked to the Device Provisioning Service instance configured in this section.

In this section, you'll use your Git Bash prompt and the Visual Studio IDE.

Configure the provisioning device code

In this section, you update the sample code with your Device Provisioning Service instance information.

In the Azure portal, select the Overview tab for your Device Provisioning Service instance and note the ID Scope value.
Launch Visual Studio and open the new solution file that was created in the cmake directory you created in the root of the azure-iot-sdk-c git repository. The solution file is named azure_iot_sdks.sln.
In Solution Explorer for Visual Studio, navigate to Provision_Samples > prov_dev_client_sample > Source Files and open prov_dev_client_sample.c.
Find the id_scope constant, and replace the value with your ID Scope value that you copied earlier. For example:
```
static const char* id_scope = "0ne00000A0A";
```
Find the definition for the main() function in the same file. Make sure the hsm_type variable is set to SECURE_DEVICE_TYPE_X509 and that all other hsm_type lines are commented out. For example:
```
SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
hsm_type = SECURE_DEVICE_TYPE_X509;
//hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
```
Save your changes.
Right-click the prov_dev_client_sample project and select Set as Startup Project.

Configure the custom HSM stub code

The specifics of interacting with actual secure hardware-based storage vary depending on the device hardware. The certificate chains used by the simulated devices in this tutorial will be hardcoded in the custom HSM stub code. In a real-world scenario, the certificate chain would be stored in the actual HSM hardware to provide better security for sensitive information. Methods similar to the stub methods used in this sample would then be implemented to read the secrets from that hardware-based storage.

While HSM hardware isn't required, it's recommended to protect sensitive information like the certificate's private key. If an actual HSM was being called by the sample, the private key wouldn't be present in the source code. Having the key in the source code exposes the key to anyone that can view the code. This is only done in this tutorial to assist with learning.

To update the custom HSM stub code to simulate the identity of the device with ID device-01:

In Solution Explorer for Visual Studio, navigate to Provision_Samples > custom_hsm_example > Source Files and open custom_hsm_example.c.
Update the string value of the COMMON_NAME string constant using the common name you used when generating the device certificate.
```
static const char* const COMMON_NAME = "device-01";
```

Update the string value of the CERTIFICATE constant string using the certificate chain you saved in ./certs/device-01-full-chain.cert.pem after generating your certificates.

The syntax of certificate text must follow the pattern below with no extra spaces or parsing done by Visual Studio.

// <Device/leaf cert>
// <intermediates>
// <root>
static const char* const CERTIFICATE = "-----BEGIN CERTIFICATE-----\n"
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
"-----END CERTIFICATE-----\n"
"-----BEGIN CERTIFICATE-----\n"
"MIIFPDCCAySgAwIBAgIBATANBgkqhkiG9w0BAQsFADAqMSgwJgYDVQQDDB9BenVy\n"
    ...
"MTEyMjIxMzAzM1owNDEyMDAGA1UEAwwpQXp1cmUgSW9UIEh1YiBJbnRlcm1lZGlh\n"
"-----END CERTIFICATE-----\n"
"-----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 your Git Bash prompt, and press ENTER. This command generates the syntax for the CERTIFICATE string constant value and writes it to the output.

sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' ./certs/device-01-full-chain.cert.pem

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

Update the string value of the PRIVATE_KEY constant with the private key for your device certificate.

The syntax of the private key text must follow the pattern below with no extra spaces or parsing done by Visual Studio.
```
static const char* const PRIVATE_KEY = "-----BEGIN RSA PRIVATE KEY-----\n"
"MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n"
    ...
"X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n"
"-----END RSA PRIVATE KEY-----";
```
Updating this string value manually can be prone to error. To generate the proper syntax, you can copy and paste the following command into your Git Bash prompt, and press ENTER. This command generates the syntax for the PRIVATE_KEY string constant value and writes it to the output.
```
sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' ./private/device-01.key.pem
```
Copy and paste the output private key text for the constant value.
Save your changes.
Right-click the custom_hsm_example project and select Build.

Important

You must build the custom_hsm_example project before you build the rest of the solution in the next section.

Run the sample

On the Visual Studio menu, select Debug > Start without debugging to run the solution. When prompted to rebuild the project, select Yes to rebuild the project before running.

The following output is an example of simulated device device-01 successfully booting up and connecting to the provisioning service. The device was assigned to an IoT hub and registered:
```
Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-hub-2.azure-devices.net, deviceId: device-01
Press enter key to exit:
```

Repeat the steps in Configure the custom HSM stub code for your second device (device-02) and run the sample again. Use the following values for that device:

Description	Value
Common name	`"device-02"`
Full certificate chain	Generate the text using ./certs/device-02-full-chain.cert.pem
Private key	Generate the text using ./private/device-02.key.pem

The following output is an example of simulated device device-02 successfully booting up, and connecting to the provisioning service. The device was assigned to an IoT hub and registered:

Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-hub-2.azure-devices.net, deviceId: device-02
Press enter key to exit:

The C# sample code is set up to use X.509 certificates that are stored in a password-protected PKCS#12 formatted file (.pfx). The full chain certificates you created previously are in the PEM format. To convert the full chain certificates to PKCS#12 format, enter the following commands in your Git Bash prompt from the directory where you previously ran the OpenSSL commands.

device-01

openssl pkcs12 -inkey ./private/device-01.key.pem -in ./certs/device-01-full-chain.cert.pem -export -passin pass:1234 -passout pass:1234 -out ./certs/device-01-full-chain.cert.pfx

device-02

openssl pkcs12 -inkey ./private/device-02.key.pem -in ./certs/device-02-full-chain.cert.pem -export -passin pass:1234 -passout pass:1234 -out ./certs/device-02-full-chain.cert.pfx

In the rest of this section, you'll use your Windows command prompt.

In the Azure portal, select the Overview tab for your Device Provisioning Service.
Copy the ID Scope value.
In your Windows command prompt, change to the X509Sample directory. This directory is located in the .\azure-iot-sdk-csharp\provisioning\device\samples\getting started\X509Sample directory off the directory where you cloned the samples on your computer.

Enter the following command to build and run the X.509 device provisioning sample (replace <id-scope> with the ID Scope that you copied in step 2. Replace <your-certificate-folder> with the path to the folder where you ran your OpenSSL commands.

dotnet run -- -s <id-scope> -c <your-certificate-folder>\certs\device-01-full-chain.cert.pfx -p 1234

The device connects to DPS and is assigned to an IoT hub. Then, the device sends a telemetry message to the IoT hub. You should see output similar to the following:

Loading the certificate...
Found certificate: 3E5AA3C234B2032251F0135E810D75D38D2AA477 CN=Azure IoT Hub CA Cert Test Only; PrivateKey: False
Found certificate: 81FE182C08D18941CDEEB33F53F8553BA2081E60 CN=Azure IoT Hub Intermediate Cert Test Only; PrivateKey: False
Found certificate: 5BA1DB226D50EBB7A6A6071CED4143892855AE43 CN=device-01; PrivateKey: True
Using certificate 5BA1DB226D50EBB7A6A6071CED4143892855AE43 CN=device-01
Initializing the device provisioning client...
Initialized for registration Id device-01.
Registering with the device provisioning service...
Registration status: Assigned.
Device device-01 registered to contoso-hub-2.azure-devices.net.
Creating X509 authentication for IoT Hub...
Testing the provisioned device with IoT Hub...
Sending a telemetry message...
Finished.

Note

If you don't specify certificate and password on the command line, the certificate file will default to ./certificate.pfx and you'll be prompted for your password.

Additional parameters can be passed to change the TransportType (-t) and the GlobalDeviceEndpoint (-g). For a full list of parameters type dotnet run -- --help.

To register your second device, rerun the sample using its full chain certificate.

dotnet run -- -s <id-scope> -c <your-certificate-folder>\certs\device-02-full-chain.cert.pfx -p 1234

In the following steps, use your Windows command prompt.

In the Azure portal, select the Overview tab for your Device Provisioning Service.
Copy the ID Scope value.
In your Windows command prompt, go to the sample directory, and install the packages needed by the sample. The path shown is relative to the location where you cloned the SDK.
```
cd .\azure-iot-sdk-node\provisioning\device\samples
npm install
```

In the provisioning\device\samples folder, open register_x509.js and review the code.

The sample defaults to MQTT as the transport protocol. If you want to use a different protocol, comment out the following line and uncomment the line for the appropriate protocol.

var ProvisioningTransport = require('azure-iot-provisioning-device-mqtt').Mqtt;

The sample uses five environment variables to authenticate and provision an IoT device using DPS. These environment variables are:

Variable name	Description
`PROVISIONING_HOST`	The endpoint to use for connecting to your DPS instance. For this tutorial, use the global endpoint, `global.azure-devices-provisioning.net`.
`PROVISIONING_IDSCOPE`	The ID Scope for your DPS instance.
`PROVISIONING_REGISTRATION_ID`	The registration ID for your device. It must match the subject common name in the device certificate.
`CERTIFICATE_FILE`	The path to your device full chain certificate file.
`KEY_FILE`	The path to your device certificate private key file.

The ProvisioningDeviceClient.register() method attempts to register your device.

Add environment variables for the global device endpoint and ID scope. Replace <id-scope> with the value you copied in step 2.
```
set PROVISIONING_HOST=global.azure-devices-provisioning.net
set PROVISIONING_IDSCOPE=<id-scope>
```
Set the environment variable for the device registration ID. The registration ID for the IoT device must match subject common name on its device certificate. For this tutorial, device-01 is both the subject name and the registration ID for the device.
```
set PROVISIONING_REGISTRATION_ID=device-01
```
Set the environment variables for the device full chain certificate and device private key files you generated previously. Replace <your-certificate-folder> with the path to the folder where you ran your OpenSSL commands.
```
set CERTIFICATE_FILE=<your-certificate-folder>\certs\device-01-full-chain.cert.pem
set KEY_FILE=<your-certificate-folder>\private\device-01.key.pem
```

Run the sample and verify that the device was provisioned successfully.

node register_x509.js

You should see output similar to the following:

registration succeeded
assigned hub=contoso-hub-2.azure-devices.net
deviceId=device-01
Client connected
send status: MessageEnqueued

Update the environment variables for your second device (device-02) according to the table below and run the sample again.

Environment Variable	Value
PROVISIONING_REGISTRATION_ID	`device-02`
CERTIFICATE_FILE	<your-certificate-folder>\certs\device-02-full-chain.cert.pem
KEY_FILE	<your-certificate-folder>\private\device-02.key.pem

In the following steps, use your Windows command prompt.

In the Azure portal, select the Overview tab for your Device Provisioning Service.
Copy the ID Scope.

In your Windows command prompt, go to the directory of the provision_x509.py sample. The path shown is relative to the location where you cloned the SDK.

cd .\azure-iot-sdk-python\samples\async-hub-scenarios

This sample uses six environment variables to authenticate and provision an IoT device using DPS. These environment variables are:

Variable name	Description
`PROVISIONING_HOST`	The endpoint to use for connecting to your DPS instance. For this tutorial, use the global endpoint, `global.azure-devices-provisioning.net`.
`PROVISIONING_IDSCOPE`	The ID Scope for your DPS instance.
`DPS_X509_REGISTRATION_ID`	The registration ID for your device. It must match the subject common name in the device certificate.
`X509_CERT_FILE`	The path to your device full chain certificate file.
`X509_KEY_FILE`	The path to your device certificate private key file.
`PASS_PHRASE`	The pass phrase used to encrypt the private key file (if used). Not needed for this tutorial.

Add the environment variables for the global device endpoint and ID Scope. You copied the ID scope for your instance in step 2.
```
set PROVISIONING_HOST=global.azure-devices-provisioning.net
set PROVISIONING_IDSCOPE=<ID scope for your DPS resource>
```
Set the environment variable for the device registration ID. The registration ID for the IoT device must match subject common name on its device certificate. For this tutorial, device-01 is both the subject name and the registration ID for the device.
```
set DPS_X509_REGISTRATION_ID=device-01
```
Set the environment variables for the device full chain certificate and device private key files you generated previously. Replace <your-certificate-folder> with the path to the folder where you ran your OpenSSL commands.
```
set X509_CERT_FILE=<your-certificate-folder>\certs\device-01-full-chain.cert.pem
set X509_KEY_FILE=<your-certificate-folder>\private\device-01.key.pem
```
Review the code for provision_x509.py. If you're not using Python version 3.7 or later, make the code change mentioned here to replace asyncio.run(main()).

Run the sample. The sample connects to DPS, which will provision the device to an IoT hub. After the device is provisioned, the sample sends some test messages to the IoT hub.

python provision_x509.py

You should see output similar to the following:

The complete registration result is
device-01
contoso-hub-2.azure-devices.net
initialAssignment
null
Will send telemetry from the provisioned device
sending message #1
sending message #2
sending message #3
sending message #4
sending message #5
sending message #6
sending message #7
sending message #8
sending message #9
sending message #10
done sending message #1
done sending message #2
done sending message #3
done sending message #4
done sending message #5
done sending message #6
done sending message #7
done sending message #8
done sending message #9
done sending message #10

Update the environment variables for your second device (device-02) according to the table below and run the sample again.

Environment Variable	Value
DPS_X509_REGISTRATION_ID	`device-02`
X509_CERT_FILE	<your-certificate-folder>\certs\device-02-full-chain.cert.pem
X509_KEY_FILE	<your-certificate-folder>\private\device-02.key.pem

In the following steps, you'll use both your Windows command prompt and your Git Bash prompt.

In the Azure portal, select the Overview tab for your Device Provisioning Service.
Copy the ID Scope.
In your Windows command prompt, navigate to the sample project folder. The path shown is relative to the location where you cloned the SDK
```
cd .\azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-X509-sample
```
Enter the provisioning service and X.509 identity information in the sample code. This is used during provisioning, for attestation of the simulated device, prior to device registration.
1. Open the file .\src\main\java\samples\com\microsoft\azure\sdk\iot\ProvisioningX509Sample.java in your favorite editor.
2. Update the following values. For idScope, use the ID Scope that you copied previously. For global endpoint, use the Global device endpoint. This endpoint is the same for every DPS instance, global.azure-devices-provisioning.net.
```
private static final String idScope = "[Your ID scope here]";
private static final String globalEndpoint = "[Your Provisioning Service Global Endpoint here]";
```
3. The sample defaults to using HTTPS as the transport protocol. If you want to change the protocol, comment out the following line, and uncomment the line for the protocol you want to use.
```
private static final ProvisioningDeviceClientTransportProtocol PROVISIONING_DEVICE_CLIENT_TRANSPORT_PROTOCOL = ProvisioningDeviceClientTransportProtocol.HTTPS;
```
4. Update the value of the leafPublicPem constant string with the value of your device certificate, device-01.cert.pem.
  
  The syntax of certificate text must follow the pattern below with no extra spaces or characters.
```
private static final String leafPublicPem = "-----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 your Git Bash prompt, and press ENTER. This command will generate the syntax for the leafPublicPem string constant value and write it to the output.
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' ./certs/device-01.cert.pem
```
  Copy and paste the output certificate text for the constant value.
5. Update the string value of the leafPrivateKey constant with the unencrypted private key for your device certificate, unencrypted-device-key.pem.
  
  The syntax of the private key text must follow the pattern below with no extra spaces or characters.
```
private static final String leafPrivateKey = "-----BEGIN PRIVATE KEY-----\n" +
"MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n" +
    ...
"X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n" +
"-----END PRIVATE KEY-----";
```
  To generate the proper syntax, you can copy and paste the following command into your Git Bash prompt, and press ENTER. This command will generate the syntax for the leafPrivateKey string constant value and write it to the output.
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' ./private/device-01.key.pem
```
  Copy and paste the output private key text for the constant value.
6. Add a rootPublicPem constant string with the value of your root CA certificate, azure-iot-test-only.root.ca.cert.pem. You can add it just after the leafPrivateKey constant.
  
  The syntax of certificate text must follow the pattern below with no extra spaces or characters.
```
private static final String rootPublicPem = "-----BEGIN CERTIFICATE-----\n"
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
"-----END CERTIFICATE-----";        
```
  To generate the proper syntax, you can copy and paste the following command into your Git Bash prompt, and press ENTER. This command will generate the syntax for the rootPublicPem string constant value and write it to the output.
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' ./certs/azure-iot-test-only.root.ca.cert.pem
```
  Copy and paste the output certificate text for the constant value.
7. Add an intermediatePublicPem constant string with the value of your intermediate CA certificate, azure-iot-test-only.intermediate.cert.pem. You can add it just after the previous constant.
  
  The syntax of certificate text must follow the pattern below with no extra spaces or characters.
```
private static final String intermediatePublicPem = "-----BEGIN CERTIFICATE-----\n"
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
"-----END CERTIFICATE-----";        
```
  To generate the proper syntax, you can copy and paste the following command into your Git Bash prompt, and press ENTER. This command will generate the syntax for the intermediatePublicPem string constant value and write it to the output.
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' ./certs/azure-iot-test-only.intermediate.cert.pem
```
  Copy and paste the output certificate text for the constant value.
8. Find the following lines in the main method.
```
// For group enrollment uncomment this line
//signerCertificatePemList.add("<Your Signer/intermediate Certificate Here>");
```
  Add these two lines directly beneath them to add your intermediate and root CA certificates to the signing chain. Your signing chain should include the whole certificate chain up to and including a certificate that you've verified with DPS.
```
signerCertificatePemList.add(intermediatePublicPem);
signerCertificatePemList.add(rootPublicPem);
```
  Note
  
  The order that the signing certificates are added is important. The sample will fail if it's changed.
9. Save your changes.
Build the sample, and then go to the target folder.
```
mvn clean install
cd target
```

The build 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. Execute the .jar file. You may need to replace the version in the command below.

java -jar ./provisioning-x509-sample-1.8.1-with-deps.jar

The sample will connect to DPS, which will provision the device to an IoT hub. After the device is provisioned, the sample will send some test messages to the IoT hub.

Starting...
Beginning setup.
WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.
2022-10-21 10:41:20,476 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Initialized a ProvisioningDeviceClient instance using SDK version 2.0.2
2022-10-21 10:41:20,479 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Starting provisioning thread...
Waiting for Provisioning Service to register
2022-10-21 10:41:20,482 INFO (global.azure-devices-provisioning.net-4f8279ac-CxnPendingConnectionId-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Opening the connection to device provisioning service...
2022-10-21 10:41:20,652 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Connection to device provisioning service opened successfully, sending initial device registration message
2022-10-21 10:41:20,680 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-RegisterTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.RegisterTask] - Authenticating with device provisioning service using x509 certificates
2022-10-21 10:41:21,603 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Waiting for device provisioning service to provision this device...
2022-10-21 10:41:21,605 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Current provisioning status: ASSIGNING
2022-10-21 10:41:24,868 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Device provisioning service assigned the device successfully
IotHUb Uri : contoso-hub-2.azure-devices.net
Device ID : device-01
2022-10-21 10:41:30,514 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-10-21 10:41:30,526 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-10-21 10:41:30,533 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.1.2
2022-10-21 10:41:30,590 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2022-10-21 10:41:30,625 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2022-10-21 10:41:31,452 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2022-10-21 10:41:31,453 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/device-01/messages/devicebound/#
2022-10-21 10:41:31,523 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/device-01/messages/devicebound/# was acknowledged
2022-10-21 10:41:31,525 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2022-10-21 10:41:31,528 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2022-10-21 10:41:31,531 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2022-10-21 10:41:31,532 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2022-10-21 10:41:31,535 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details
2022-10-21 10:41:31,536 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2022-10-21 10:41:31,537 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Sending message from device to IoT Hub...
2022-10-21 10:41:31,539 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Message was queued to be sent later ( Message details: Correlation Id [0d143280-dbc7-405f-a61e-fcc7a1d80b87] Message Id [4d8d39c8-5a38-4299-8f07-3ae02cdc3218] )
Press any key to exit...
2022-10-21 10:41:31,540 DEBUG (contoso-hub-2.azure-devices.net-device-01-d7c67552-Cxn0bd73809-420e-46fe-91ee-942520b775db-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Sending message ( Message details: Correlation Id [0d143280-dbc7-405f-a61e-fcc7a1d80b87] Message Id [4d8d39c8-5a38-4299-8f07-3ae02cdc3218] )
2022-10-21 10:41:31,844 DEBUG (MQTT Call: device-01) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - IotHub message was acknowledged. Checking if there is record of sending this message ( Message details: Correlation Id [0d143280-dbc7-405f-a61e-fcc7a1d80b87] Message Id [4d8d39c8-5a38-4299-8f07-3ae02cdc3218] )
2022-10-21 10:41:31,846 DEBUG (contoso-hub-2.azure-devices.net-device-01-d7c67552-Cxn0bd73809-420e-46fe-91ee-942520b775db-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking the callback function for sent message, IoT Hub responded to message ( Message details: Correlation Id [0d143280-dbc7-405f-a61e-fcc7a1d80b87] Message Id [4d8d39c8-5a38-4299-8f07-3ae02cdc3218] ) with status OK
Message sent!

Update the constants for your second device (device-02) according to the table below, rebuild, and run the sample again.

Constant File to use

leafPublicPem ./certs/device-02.cert.pem

leafPrivateKey ./private/device-02.key.pem

Constant	File to use
`leafPublicPem`	./certs/device-02.cert.pem
`leafPrivateKey`	./private/device-02.key.pem

Confirm your device provisioning registration

Examine the registration records of the enrollment group to see the registration details for your devices:

In the Azure portal, go to your Device Provisioning Service instance.
In the Settings menu, select Manage enrollments.
Select Enrollment groups. The X.509 enrollment group entry that you created previously should appear in the list.
Select the enrollment entry. Then select Details next to the Registration status to see the devices that have been registered through the enrollment group. The IoT hub that each of your devices was assigned to, their device IDs, and the dates and times they were registered appear in the list.
You can select one of the devices to see further details for that device.

To verify the devices on your IoT hub:

In Azure portal, go to the IoT hub that your device was assigned to.
In the Device management menu, select Devices.
If your devices were provisioned successfully, their device IDs, device-01 and device-02, should appear in the list, with Status set as enabled. If you don't see your devices, select Refresh.

Clean up resources

When you're finished testing and exploring this device client sample, use the following steps to delete all resources created by this tutorial.

Close the device client sample output window on your machine.

Delete your enrollment group

From the left-hand menu in the Azure portal, select All resources.
Select your DPS instance.
In the Settings menu, select Manage enrollments.
Select the Enrollment groups tab.
Select the enrollment group you used for this tutorial.
On the Enrollment details page, select Details next to the Registration status. Then select the check box next to the Device Id column header to select all of the registration records for the enrollment group. Select Delete at the top of the page to delete the registration records.

Important

Deleting an enrollment group doesn't delete the registration records associated with it. These orphaned records will count against the registrations quota for the DPS instance. For this reason, it's a best practice to delete all registration records associated with an enrollment group before you delete the enrollment group itself.
Go back to the Manage enrollments page and make sure the Enrollment groups tab is selected.
Select the check box next to the group name of the enrollment group you used for this tutorial.
At the top of the page, select Delete.

Delete registered CA certificates from DPS

Select Certificates from the left-hand menu of your DPS instance. For each certificate you uploaded and verified in this tutorial, select the certificate and select Delete and confirm your choice to remove it.

Delete device registration(s) from IoT Hub

From the left-hand menu in the Azure portal, select All resources.
Select your IoT hub.
In the Explorers menu, select IoT devices.
Select the check box next to the device ID of the devices you registered in this tutorial. For example, device-01 and device-02.
At the top of the page, select Delete.

Next steps

In this tutorial, you provisioned multiple X.509 devices to your IoT hub using an enrollment group. Next, learn how to provision IoT devices across multiple hubs.

Use custom allocation policies

Tutorial: Provision multiple X.509 devices using enrollment groups

Prerequisites

Prepare your development environment

Create an X.509 certificate chain

Set up the X.509 OpenSSL environment

Create the root CA certificate

Create the intermediate CA certificate

Create the device certificates

Verify ownership of the root certificate

(Optional) Manual verification of root certificate

Update the certificate store on Windows-based devices

Create an enrollment group

Prepare and run the device provisioning code

Configure the provisioning device code

Configure the custom HSM stub code

Run the sample

Confirm your device provisioning registration

Clean up resources

Delete your enrollment group

Delete registered CA certificates from DPS

Delete device registration(s) from IoT Hub

Next steps

Feedback

Additional resources

Additional resources