快速入门：使用 C# 将 X.509 设备注册到设备预配服务

项目
06/02/2023

本快速入门展示了如何使用 C# 以编程方式创建使用中间或根 CA X.509 证书的注册组。该注册组是使用用于 .NET 的 Azure IoT SDK 和一个示例 C# .NET Core 应用程序创建的。注册组可以控制对设备的预配服务的访问，此类设备在其证书链中共享常用签名证书。若要了解详细信息，请参阅使用 X.509 证书控制设备对预配服务的访问。若要详细了解如何将基于 X.509 证书的公钥基础结构 (PKI) 与 Azure IoT 中心和设备预配服务配合使用，请参阅 X.509 CA 证书安全概述。

本快速入门假设你已创建了 IoT 中心和设备预配服务实例。如果尚未创建这些资源，请先完成使用 Azure 门户设置 IoT 中心设备预配服务快速入门，然后再继续学习本文。

本文使用 Windows 开发计算机，不过，本文中的步骤在 Windows 和 Linux 计算机上均适用。

如果没有 Azure 订阅，可在开始前创建一个试用帐户。

必备条件

安装 Visual Studio 2019。
安装 .NET Core SDK。
安装 Git。

准备测试证书

对于本快速入门，必须具有一个包含中间或根 CA X.509 证书的公共部分的 .pem 或.cer 文件。此证书必须上传到预配服务，并由该服务进行验证。

Azure IoT C SDK 包含的测试工具可以帮助你创建 X.509 证书链、从该链上传根证书或中间证书，以及通过服务执行所有权证明操作，对证书进行验证。

注意

使用 SDK 工具创建的证书只能用于开发测试。请不要在生产环境中使用这些证书。它们包含硬编码的密码（例如 1234），在 30 天后过期。若要了解如何获取适用于生产用途的证书，请参阅 Azure IoT 中心文档中的如何获取 X.509 CA 证书。

若要使用此测试工具来生成证书，请执行以下步骤：

找到最新版 Azure IoT C SDK 的标记名称。
打开命令提示符或 Git Bash shell，并切换到计算机上的某个工作文件夹。运行以下命令，克隆最新版 Azure IoT C SDK GitHub 存储库。使用在上一步找到的标记作为 -b 参数的值：
```
git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
应该预料到此操作需要几分钟才能完成。

测试工具位于你克隆的存储库的 azure-iot-sdk-c/tools/CACertificates 中。
根据管理示例和教程的测试 CA 证书中的步骤进行操作。

除了使用 C SDK 中的工具之外，“用于 .NET 的 Azure IoT SDK”中的组证书验证示例演示了如何使用现有的 X.509 中间或根 CA 证书采用 C# 执行所有权证明操作。

获取适用于预配服务的连接字符串

对于本快速入门中的示例，需要适用于预配服务的连接字符串。

登录到 Azure 门户，选择“所有资源”，然后选择你的设备预配服务。
选择“共享访问策略”，然后选择需要用来打开其属性的访问策略。在“访问策略”中，复制并保存主密钥连接字符串。

创建注册组示例

本部分介绍如何创建一个 .NET Core 控制台应用，用于将注册组添加到预配服务。进行一些修改后，还可以按这些步骤创建 Windows IoT Core 控制台应用，以便添加注册组。若要详细了解如何使用 IoT Core 进行开发，请参阅 Windows IoT Core developer documentation（Windows IoT Core 开发人员文档）。

打开 Visual Studio 并选择“创建新项目” 。在“创建新项目”中，为 C# 项目模板选择“控制台应用(.NET Core)”，然后选择“下一步”。
将项目命名为 CreateEnrollmentGroup，然后按“创建” 。
解决方案在 Visual Studio 中打开时，在“解决方案资源管理器”窗格中，右键单击“CreateEnrollmentGroup”项目，然后选择“管理 NuGet 包” 。
在“NuGet 包管理器”中选择“浏览”，搜索并选择“Microsoft.Azure.Devices.Provisioning.Service”，然后按“安装” 。

此步骤会下载、安装 Azure IoT 预配服务客户端 SDK NuGet 包及其依赖项并添加对它的引用。

在 Program.cs 顶部的其他 using 语句之后添加以下 using 语句：

using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using Microsoft.Azure.Devices.Provisioning.Service;

将以下字段添加到 Program 类，并按所列内容进行更改。
```
private static string ProvisioningConnectionString = "{ProvisioningServiceConnectionString}";
private static string EnrollmentGroupId = "enrollmentgrouptest";
private static string X509RootCertPath = @"{Path to a .cer or .pem file for a verified root CA or intermediate CA X.509 certificate}";
```
- 将 ProvisioningServiceConnectionString 占位符值替换为需要为其创建注册的预配服务的连接字符串。
- 将 X509RootCertPath 占位符值替换为 .pem 或 .cer 文件的路径。此文件代表中间或根 CA X.509 证书的公用部分，而该证书此前已通过预配服务上传和验证。
- 可以选择性地更改 EnrollmentGroupId 值。字符串只能包含小写字符和连字符。
重要

在生产代码中，请注意以下安全注意事项：
- 为预配服务管理员硬编码连接字符串不符合安全最佳做法。与硬编码相反，连接字符串应采用安全方式进行存储，例如存储在安全配置文件或注册表中。
- 确保只上传签名证书的公用部分。不要将包含私钥的 .pfx (PKCS12) 或 .pem 文件上传到预配服务。

将以下方法添加到 Program 类。此代码创建一个注册组条目，然后调用 ProvisioningServiceClient 中的 CreateOrUpdateEnrollmentGroupAsync 方法，将注册组添加到预配服务。

public static async Task RunSample()
{
    Console.WriteLine("Starting sample...");

    using (ProvisioningServiceClient provisioningServiceClient =
            ProvisioningServiceClient.CreateFromConnectionString(ProvisioningConnectionString))
    {
        #region Create a new enrollmentGroup config
        Console.WriteLine("\nCreating a new enrollmentGroup...");
        var certificate = new X509Certificate2(X509RootCertPath);
        Attestation attestation = X509Attestation.CreateFromRootCertificates(certificate);
        EnrollmentGroup enrollmentGroup =
                new EnrollmentGroup(
                        EnrollmentGroupId,
                        attestation)
                {
                    ProvisioningStatus = ProvisioningStatus.Enabled
                };
        Console.WriteLine(enrollmentGroup);
        #endregion

        #region Create the enrollmentGroup
        Console.WriteLine("\nAdding new enrollmentGroup...");
        EnrollmentGroup enrollmentGroupResult =
            await provisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync(enrollmentGroup).ConfigureAwait(false);
        Console.WriteLine("\nEnrollmentGroup created with success.");
        Console.WriteLine(enrollmentGroupResult);
        #endregion

    }
}

最后，将 Main 方法替换为以下行：

 static async Task Main(string[] args)
 {
     await RunSample();
     Console.WriteLine("\nHit <Enter> to exit ...");
     Console.ReadLine();
 }

生成解决方案。

运行注册组示例

运行 Visual Studio 中的示例，创建注册组。系统将显示命令提示符窗口并开始显示确认消息。成功创建后，命令提示符窗口会显示新注册组的属性。

可以验证注册组是否已创建。转到设备预配服务的摘要，依次选择“管理注册”、“注册组”。此时会看到一个新的注册条目，对应于示例中使用的注册 ID。

Enrollment properties in the portal

选择该条目即可验证证书指纹以及该条目的其他属性。

清理资源

如果你打算学习 C# 服务示例，请勿清理本快速入门中创建的资源。否则，请使用以下步骤删除本快速入门创建的所有资源。

关闭计算机上的 C# 示例输出窗口。
在 Azure 门户中导航到设备预配服务，依次选择“管理注册”、“注册组”。选择使用本快速入门创建的注册项的“注册 ID”，然后按“删除” 。
在 Azure 门户上的设备预配服务中选择“证书”，选择为本快速入门上传的证书，然后按“证书详细信息”顶部的“删除” 。

后续步骤

在本快速入门中，你已使用 Azure IoT 中心设备预配服务为 X.509 中间或根 CA 证书创建了一个注册组。若要深入了解设备预配，请继续学习本教程有关如何在 Azure 门户中进行设备预配服务设置的内容。