快速入门:使用 C# 将 X.509 设备注册到设备预配服务
本快速入门展示了如何使用 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。
选择该条目即可验证证书指纹以及该条目的其他属性。
如果你打算学习 C# 服务示例,请勿清理本快速入门中创建的资源。 否则,请使用以下步骤删除本快速入门创建的所有资源。
关闭计算机上的 C# 示例输出窗口。
在 Azure 门户中导航到设备预配服务,依次选择“管理注册”、“注册组”。 选择使用本快速入门创建的注册项的“注册 ID”,然后按“删除” 。
在 Azure 门户上的设备预配服务中选择“证书”,选择为本快速入门上传的证书,然后按“证书详细信息”顶部的“删除” 。
在本快速入门中,你已使用 Azure IoT 中心设备预配服务为 X.509 中间或根 CA 证书创建了一个注册组。 若要深入了解设备预配,请继续学习本教程有关如何在 Azure 门户中进行设备预配服务设置的内容。