快速入门:使用 Python 将 X.509 设备注册到设备预配服务Quickstart: Enroll X.509 devices to the Device Provisioning Service using Python

在本快速入门中,你将使用 Python 以编程方式创建使用中间或根 CA X.509 证书的注册组。In this quickstart, you 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. 该注册组是使用 Python 预配服务 SDK 和一个示例 Python 应用程序创建的。The enrollment group is created using the Python Provisioning Service SDK and a sample Python application.

先决条件Prerequisites

重要

本文仅适用于已弃用的 V1 Python SDK。This article only applies to the deprecated V1 Python SDK. V2 中尚不提供用于 IoT 中心设备预配服务的设备和服务客户端。Device and service clients for the IoT Hub Device Provisioning Service are not yet available in V2. 该团队目前正在努力使 V2 具有功能奇偶一致性。The team is currently hard at work to bring V2 to feature parity.

准备测试证书Prepare test certificates

对于本快速入门,必须具有一个包含中间或根 CA X.509 证书的公共部分的 .pem 或.cer 文件。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.

若要详细了解如何将基于 X.509 证书的公钥基础结构 (PKI) 与 Azure IoT 中心和设备预配服务配合使用,请参阅 X.509 CA 证书安全概述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.

Azure IoT C SDK 包含的测试工具可以帮助你创建 X.509 证书链、从该链上传根证书或中间证书,以及通过服务执行所有权证明操作,对证书进行验证。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. 根据设计,使用 SDK 工具创建的证书只能用于开发测试Certificates created with the SDK tooling are designed to use for development testing only. 这些证书不得在生产环境中使用These certificates must not be used in production. 它们包含硬编码的密码(“1234”),在 30 天后过期。They contain hard-coded passwords ("1234") that expire after 30 days. 若要了解如何获取适用于生产用途的证书,请参阅 Azure IoT 中心文档中的如何获取 X.509 CA 证书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. 找到最新版 Azure IoT C SDK 的标记名称。Find the tag name for the latest release of the Azure IoT C SDK.

  2. 打开命令提示符或 Git Bash shell,并切换到计算机上的某个工作文件夹。Open a command prompt or Git Bash shell, and change to a working folder on your machine. 运行以下命令,克隆最新版 Azure IoT C SDK GitHub 存储库。Run the following commands to clone the latest release of the Azure IoT C SDK GitHub repository. 使用在上一步找到的标记作为 -b 参数的值:Use the tag you found in the previous step as the value for the -b parameter:

    git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
    cd azure-iot-sdk-c
    git submodule update --init
    

    应该预料到此操作需要几分钟才能完成。You should expect this operation to take several minutes to complete.

    测试工具位于你克隆的存储库的 azure-iot-sdk-c/tools/CACertificates 中。The test tooling is located in the azure-iot-sdk-c/tools/CACertificates of the repository you cloned.

  3. 根据管理示例和教程的测试 CA 证书中的步骤进行操作。Follow the steps in Managing test CA certificates for samples and tutorials.

修改 Python 示例代码Modify the Python sample code

此部分演示如何向示例代码添加 X.509 设备的预配详细信息。This section shows how to add the provisioning details of your X.509 device to the sample code.

  1. 使用文本编辑器,新建一个 EnrollmentGroup.py 文件。Using a text editor, create a new EnrollmentGroup.py file.

  2. EnrollmentGroup.py 文件的开头添加以下 import 语句和变量:Add the following import statements and variables at the start of the EnrollmentGroup.py file. 然后,将 dpsConnectionString 替换为你的连接字符串,该字符串位于 Azure 门户设备预配服务的“共享访问策略” 下。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. 最后,创建唯一的 registrationid,确保其只包含小写字母数字和连字符。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. 保存并关闭 EnrollmentGroup.py 文件。Save and close the EnrollmentGroup.py file.

运行示例组注册Run the sample group enrollment

Azure IoT 设备预配服务支持两类注册:The Azure IoT Device Provisioning Service supports two types of enrollments:

使用 Python 预配服务 SDK 创建个人注册是正在进行的一项工作。Creating Individual enrollments using the Python Provisioning Service SDK is still a work in progress. 若要了解详细信息,请参阅使用 X.509 证书控制设备对预配服务的访问To learn more, see Controlling device access to the provisioning service with X.509 certificates.

  1. 打开命令提示符,并运行以下命令来安装 azure-iot-provisioning-device-clientOpen 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. 在 Azure 门户中导航到预配服务。Navigate to your provisioning service in the Azure portal. 单击“管理注册”。 Click Manage enrollments. 请注意,X.509 设备组显示在“注册组”选项卡下,带有此前创建的名称 registrationidNotice that your group of X.509 devices appears under the Enrollment Groups tab, with the name registrationid created earlier.

    验证是否已在门户中成功注册 X.509

清理资源Clean up resources

如果打算学习 Java 服务示例,请勿清理本快速入门中创建的资源。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. 关闭计算机上的 Java 示例输出窗口。Close the Java sample output window on your machine.
  2. 关闭计算机上的“X509 证书生成器” 窗口。Close the X509 Cert Generator window on your machine.
  3. 在 Azure 门户中导航到设备预配服务,选择“管理注册”,然后选择“注册组”选项卡 。选中通过本快速入门注册的 X.509 设备的“组名称”旁边的复选框,然后按窗格顶部的“删除”按钮 。Navigate to your Device Provisioning service in the Azure portal, select Manage enrollments, and then select the Enrollment Groups tab. Select the check box next to the GROUP NAME for the X.509 devices you enrolled using this quickstart, and press the Delete button at the top of the pane.

后续步骤Next steps

在本快速入门中,你将模拟的 X.509 设备组注册到了设备预配服务。In this quickstart, you enrolled a simulated group of X.509 devices to your Device Provisioning service. 若要深入了解设备预配,请继续学习本教程有关如何在 Azure 门户中进行设备预配服务设置的内容。To learn about device provisioning in depth, continue to the tutorial for the Device Provisioning Service setup in the Azure portal.