Skip to content

Latest commit

 

History

History
146 lines (95 loc) · 9.06 KB

quick-enroll-device-x509-python.md

File metadata and controls

146 lines (95 loc) · 9.06 KB
title description author ms.author ms.date ms.topic ms.service services manager ms.devlang ms.custom
This quickstart shows you how to enroll X.509 devices to the Azure Device Provisioning Service using Python | Microsoft Docs
This quickstart uses group enrollments. In this quickstart, you will enroll X.509 devices to the Azure IoT Hub Device Provisioning Service using Python
wesmc7777
wesmc
01/25/2018
quickstart
iot-dps
iot-dps
timlt
python
mvc

Quickstart: Enroll X.509 devices to the Device Provisioning Service using Python

[!INCLUDE iot-dps-selector-quick-enroll-device-x509]

Devices are enrolled to a provisioning service instance by creating an Enrollment group, or an Individual enrollment. This quickstart shows how to use Python to programmatically create an Enrollment group that uses intermediate or root CA X.509 certificates. An enrollment group controls access to the provisioning service for devices that share a common signing certificate in their certificate chain. The enrollment group is created using the Python Provisioning Service SDK and a sample Python application. Creating Individual enrollments using the Python Provisioning Service SDK is still a work in progress. To learn more, see Controlling device access to the provisioning service with X.509 certificates. For more information about using X.509 certificate-based Public Key Infrastructure (PKI) with Azure IoT Hub and Device Provisioning Service, see X.509 CA certificate security overview.

This quickstart expects you have already created an IoT hub and Device Provisioning Service instance. If you have not already created these resources, complete the Set up IoT Hub Device Provisioning Service with the Azure portal quickstart before proceeding with this article.

Although the steps in this article work on both Windows and Linux machines, this article is developed for a Windows development machine.

[!INCLUDE quickstarts-free-trial-note]

Prerequisites

Prepare test certificates

For this quickstart, you must have a .pem or a .cer file that contains the public portion of an intermediate or root CA X.509 certificate. This certificate must be uploaded to your provisioning service, and verified by the service.

The Azure IoT C SDK contains test tooling that can help you create an X.509 certificate chain, upload a root or intermediate certificate from that chain, and perform proof-of-possession with the service to verify the certificate. Certificates created with the SDK tooling are designed to use for development testing only. These certificates must not be used in production. They contain hard-coded passwords ("1234") that expire after 30 days. To learn about obtaining certificates suitable for production use, see How to get an X.509 CA certificate in the Azure IoT Hub documentation.

To use this test tooling to generate certificates, perform the following steps:

  1. Open a command prompt or Git Bash shell, and change to a working folder on your machine. Execute the following command to clone the Azure IoT C SDK GitHub repository:
git clone https://github.com/Azure/azure-iot-sdk-c.git --recursive

The size of this repository is currently around 220 MB. You should expect this operation to take several minutes to complete.

The test tooling is located in the azure-iot-sdk-c/tools/CACertificates of the repository you cloned.

  1. Follow the steps in Managing test CA certificates for samples and tutorials.

Modify the Python sample code

This section shows how to add the provisioning details of your X.509 device to the sample code.

  1. Using a text editor, create a new EnrollmentGroup.py file.

  2. Add the following import statements and variables at the start of the EnrollmentGroup.py file. Then replace dpsConnectionString with your connection string found under Shared access policies in your Device Provisioning Service on the Azure portal. Replace the certificate placeholder with the certificate created previously in Prepare test certificates. Finally, create a unique registrationid and be sure that it only consists of lower-case alphanumerics and hyphens.

    from provisioningserviceclient import ProvisioningServiceClient
from provisioningserviceclient.models import EnrollmentGroup, AttestationMechanism

CONNECTION_STRING = "{dpsConnectionString}"

SIGNING_CERT = """-----BEGIN CERTIFICATE-----
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-----END CERTIFICATE-----"""

GROUP_ID = "{registrationid}"

  3. Add the following function and function call to implement the group enrollment creation:

    def main():
    print ( "Initiating enrollment group creation..." )

    psc = ProvisioningServiceClient.create_from_connection_string(CONNECTION_STRING)
    att = AttestationMechanism.create_with_x509_signing_certs(SIGNING_CERT)
    eg = EnrollmentGroup.create(GROUP_ID, att)

    eg = psc.create_or_update(eg)

    print ( "Enrollment group created." )

if __name__ == '__main__':
    main()

  4. Save and close the EnrollmentGroup.py file.

Run the sample group enrollment

  1. Open a command prompt, and run the following command to install the azure-iot-provisioning-device-client.

    pip install azure-iothub-provisioningserviceclient

  2. In the command prompt, and run the script.

    python EnrollmentGroup.py

  3. Observe the output for the successful enrollment.

  4. 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 the name registrationid created earlier.

    Verify successful X.509 enrollment in portal

Clean up resources

If you plan to explore the Java service 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 Java sample output window on your machine.
  2. Close the X509 Cert Generator window on your machine.
  3. Navigate to your Device Provisioning service in the Azure portal, click Manage enrollments, and then select the Enrollment Groups tab. Select the GROUP NAME for the X.509 devices you enrolled using this Quickstart, and click the Delete button at the top of the blade.

Next steps

In this Quickstart, you enrolled a simulated group of X.509 devices to your Device Provisioning service. To learn about device provisioning in depth, continue to the tutorial for the Device Provisioning Service setup in the Azure portal.

[!div class="nextstepaction"] Azure IoT Hub Device Provisioning Service tutorials