在 Windows 上使用 X.509 证书创建和预配 IoT Edge 设备

适用于： IoT Edge 1.1

重要

IoT Edge 1.1 终止支持日期为 2022 年 12 月 13 日。 请查看 Microsoft 产品生命周期，了解此产品、服务、技术或 API 的受支持情况。 有关更新到最新版本的 IoT Edge 的详细信息，请参阅 更新 IoT Edge。

本文提供了有关注册和预配 Windows IoT Edge 设备的端到端说明。

注意

从 Azure IoT Edge 1.2 版开始，将不再支持带有 Windows 容器的 Azure IoT Edge。

请考虑使用新方法在 Windows 设备上运行 IoT Edge：Azure IoT Edge for Linux on Windows。

若要使用 Azure IoT Edge for Linux on Windows，可按照等效操作指南中的步骤操作。

连接到 IoT 中心的每个设备都有一个设备 ID，用于跟踪云到设备或设备到云的通信。 可以使用设备连接信息来配置设备，这些信息包括 IoT 中心主机名、设备 ID 以及设备用于向 IoT 中心进行身份验证的信息。

本文中的步骤演示了一个名为“手动预配”的过程。在手动预配过程中，你可以将单个设备连接到其 IoT 中心。 对于手动预配，可以通过两种方式来验证 IoT Edge 设备：

• 对称密钥：你在 IoT 中心创建新设备标识时，服务将创建两个密钥。 将其中一个密钥置于设备上，并在进行身份验证时将该密钥提供给 IoT 中心。

  此身份验证方法更容易上手，但不够安全。

• X.509 自签名：创建两个 X.509 标识证书并将其置于设备上。 在 IoT 中心创建新的设备标识时，需要提供两个证书的指纹。 设备在向 IoT 中心进行身份验证时会提供一个证书，IoT 中心会验证该证书是否与其指纹匹配。

  此身份验证方法更加安全，建议用于生产方案。

本文介绍如何使用 X.509 证书作为身份验证方法。 如果要使用对称密钥，请参阅在 Windows 上使用对称密钥创建和预配 IoT Edge 设备。

注意

如果要设置多个设备，并且不想手动预配每个设备，请参阅以下文章之一来了解 IoT Edge 如何与 IoT 中心设备预配服务配合工作：

• 使用 X.509 证书大规模创建和预配 IoT Edge 设备
• 使用 TPM 大规模创建和预配 IoT Edge 设备
• 使用对称密钥大规模创建和预配 IoT Edge 设备

先决条件

本文介绍如何注册 IoT Edge 设备并在设备上安装 IoT Edge。 这些任务具有不同的先决条件和用于完成这些任务的实用程序。 在继续操作之前，请确保已满足所有先决条件。

设备管理工具

你可以使用 Azure 门户、Visual Studio Code 或 Azure CLI 来完成注册设备的步骤。 每个实用工具都有自己的先决条件：

Portal

Azure 订阅中的免费或标准 IoT 中心。

Visual Studio Code

• Azure 订阅中的免费或标准 IoT 中心
• Visual Studio Code
• Azure IoT 中心扩展
• 适用于 Visual Studio Code 的 Azure IoT Edge

Azure CLI

• Azure 订阅中的免费或标准 IoT 中心

• 环境中的 Azure CLI

  Azure CLI 版本必须至少是 2.0.70 或更新版本。 请使用 az --version 验证版本。 此版本支持 az 扩展命令，并引入了 Knack 命令框架。

设备要求

一台 Windows 设备。

带有 Windows 容器的 IoT Edge 需要 Windows 版本 1809/内部版本 17763，这是最新的 Windows 长期支持版本。 若要查看受支持的 SKU 列表，请参阅受支持的系统列表。

生成设备标识证书

使用 X.509 证书进行手动预配需要 IoT Edge 1.0.10 或更高版本。

使用 X.509 证书预配 IoT Edge 设备时，你将使用所谓的“设备标识证书”。 此证书仅用于预配 IoT Edge 设备，以及通过 Azure IoT 中心对设备进行身份验证。 它是不能对其他证书进行签名的叶证书。 设备标识证书不同于 IoT Edge 设备提供给模块或下游设备进行验证的证书颁发机构 (CA) 证书。

对于 X.509 证书身份验证，每个设备的身份验证信息采用从设备标识证书获取的指纹的形式提供。 在注册设备时，会向 IoT 中心提供这些指纹，以便服务在连接时能够识别设备。

若要详细了解如何在 IoT Edge 设备中使用 CA 证书，请参阅了解 Azure IoT Edge 如何使用证书。

若要使用 X.509 进行手动预配，需要以下文件：

• 两个设备标识证书，它们需要具有 .cer 或 .pem 格式的匹配私钥证书。

  其中一组证书/密钥文件提供给 IoT Edge 运行时。 创建设备标识证书时，请将证书公用名 (CN) 设置为你希望该设备在 IoT 中心具有的设备 ID。

• 从两个设备标识证书获取的指纹。

  SHA-1 哈希的指纹值为 40 个十六进制字符，SHA-256 哈希的指纹值为 64 个十六进制字符。 在注册设备时，两个指纹都将提供给 IoT 中心。

如果没有可用的证书，可以创建演示证书以测试 IoT Edge 设备功能。 按照该文章中的说明设置证书创建脚本、创建根 CA 证书，然后创建两个 IoT Edge 设备标识证书。

从证书中检索指纹的一种方法是使用以下 openssl 命令：

openssl x509 -in <certificate filename>.pem -text -fingerprint

注册设备

根据你的偏好，你可以使用 Azure 门户、Visual Studio Code 或 Azure CLI 来注册设备。

Portal

在 Azure 门户你的 IoT 中心内，IoT Edge 设备的创建和管理独立于不支持 Edge 的 IoT 设备。

1. 登录 Azure 门户，导航到 IoT 中心。

2. 在左侧窗格中，从菜单中选择“设备”，然后选择“添加设备”。

3. 在“创建设备”页面上，提供以下信息：

   • 创建描述性设备 ID。 记下此设备 ID，因为稍后会用到它。
   • 选中“IoT Edge 设备”复选框。
   • 选择“X.509 自签名”作为身份验证类型。
   • 提供主要和辅助标识证书指纹。 SHA-1 哈希的指纹值为 40 个十六进制字符，SHA-256 哈希的指纹值为 64 个十六进制字符。

4. 选择“保存”。

Visual Studio Code

目前，适用于 Visual Studio Code 的 Azure IoT 扩展不支持使用 X.509 证书进行设备注册。

Azure CLI

使用 az iot hub device-identity create 命令在 IoT 中心创建新设备标识。 例如：

az iot hub device-identity create --device-id device_id_here --hub-name hub_name_here --edge-enabled --auth-method x509_thumbprint --primary-thumbprint primary_SHA_thumbprint_here --secondary-thumbprint secdonary_SHA_thumbprint_here

此命令包含多个参数：

• --device-id 或 -d：提供对 IoT 中心唯一的描述性名称。 记下此设备 ID，因为在下一部分会用到它。
• hub-name 或 -n：提供 IoT 中心的名称。
• --edge-enabled 或 --ee：声明该设备是 IoT Edge 设备。
• --auth-method 或 --am：声明设备将要使用的授权类型。 在本例中，我们将使用 X.509 证书指纹。
• --primary-thumbprint 或 --ptp：提供一个 X.509 证书指纹用作主密钥。
• --secondary-thumbprint 或 --stp：提供一个 X.509 证书指纹用作辅助密钥。

在 IoT 中心完成设备注册后，需检索用于安装和预配 IoT Edge 运行时的信息。

查看已注册设备并检索预配信息

使用 X.509 证书进行身份验证的设备需要其 IoT 中心名称、设备名称及证书文件才能完成 IoT Edge 运行时的安装和预配。

门户

连接到 IoT 中心并已启用 Edge 的设备将在“设备”页上列出。 可以按“Iot Edge 设备”类型筛选列表。

Visual Studio Code

虽然不支持通过 Visual Studio Code 使用 X.509 证书进行设备注册，但你仍可以根据需要查看 IoT Edge 设备。

Visual Studio Code 资源管理器的“Azure IoT 中心”部分中列出了连接到 IoT 中心的所有设备 。 IoT Edge 设备和非 Edge 设备可通过不同的图标加以区别。事实上， $edgeAgent 和 $edgeHub 模块会部署到每个 IoT Edge 设备。

Azure CLI

使用 az iot hub device-identity list 命令在 IoT 中心查看所有设备。 例如：

az iot hub device-identity list --hub-name hub_name_here

注册为 IoT Edge 设备的任何设备的 capabilities.iotEdge 属性都会设置为 true。

安装 IoT Edge

在本节中，你将准备 IoT Edge 的 Windows VM 或物理设备。 然后安装 IoT Edge。

Azure IoT Edge 依赖于 OCI 兼容的容器运行时。 Moby 是一种基于 Moby 的引擎，包含在安装脚本中，这意味着无需执行其他步骤来安装引擎。

要安装 IoT Edge 运行时：

1. 以管理员身份运行 PowerShell。

   使用 PowerShell 的 AMD64 会话，不要使用 PowerShell(x86)。 如果不确定你使用的是哪种会话类型，请运行以下命令：

   (Get-Process -Id $PID).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
   

2. 运行 Deploy-IoTEdge 命令，它将执行以下任务：

   • 检查 Windows 计算机的版本是否受支持
   • 启用容器功能
   • 下载 moby 引擎和 IoT Edge 运行时

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Deploy-IoTEdge
   

3. 如果出现提示，请重启设备。

在设备上安装 IoT Edge 时，可使用附加参数来修改过程，包括：

• 定向流量，使其通过代理服务器
• 将安装程序指向本地目录进行脱机安装

有关这些附加参数的详细信息，请参阅用于带有 Windows 容器的 IoT Edge 的 PowerShell 脚本。

为设备预配其云标识

现在容器引擎和 IoT Edge 运行时已安装在设备上，你可以开始下一步操作，即，使用设备的云标识和身份验证信息来设置设备。

1. 在 IoT Edge 设备上，以管理员身份运行 PowerShell。

2. 使用 Initialize-IoTEdge 命令在计算机上配置 IoT Edge 运行时。

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Initialize-IoTEdge -ManualX509
   

   • 如果将 IoTEdgeSecurityDaemon.ps1 脚本下载到设备上以进行脱机安装或特定版本安装，请确保参考该脚本的本地副本。

     . <path>/IoTEdgeSecurityDaemon.ps1
     Initialize-IoTEdge -ManualX509
     

3. 系统出现提示时，请提供以下信息：

   • IotHubHostName：设备将连接到的 IoT 中心的主机名。 例如 {IoT_hub_name}.azure-devices.net。
   • DeviceId：注册设备时提供的 ID。
   • X509IdentityCertificate：设备上标识证书的绝对路径。 例如 C:\path\identity_certificate.pem。
   • X509IdentityPrivateKey：所提供标识证书私钥文件的绝对路径。 例如 C:\path\identity_key.pem。

手动预配设备时，可以使用其他参数来修改过程，包括：

• 定向流量，使其通过代理服务器
• 声明特定的 edgeAgent 容器映像，并提供凭据（如果该映像位于专用注册表中）

有关这些附加参数的详细信息，请参阅用于带有 Windows 容器的 IoT Edge 的 PowerShell 脚本。

---

验证成功的配置

验证是否已在 IoT Edge 设备上成功安装并配置运行时。

检查 IoT Edge 服务的状态。

Get-Service iotedge

检查服务日志。

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog

列出正在运行的模块。

iotedge list

脱机或特定版本安装（可选）

本部分中的步骤适用于标准安装步骤未涵盖的方案。 这可能包括：

• 脱机安装 IoT Edge
• 安装候选发布版本
• 安装非最新版本

在安装过程中，会下载三个文件：

• 一个 PowerShell 脚本，其中包含安装说明
• Microsoft Azure IoT Edge cab，其中包含 IoT Edge 安全守护程序 (iotedged)、Moby 容器引擎和 Moby CLI
• Visual C++ Redistributable Package（VC 运行时）安装程序

如果在安装过程中设备会脱机，或者要安装 IoT Edge 的特定版本，则可提前将这些文件下载到设备。 当安装时，请将安装脚本指向包含已下载文件的目录。 安装程序首先会检查该目录，然后仅下载未找到的组件。 如果所有文件都可脱机使用，则无需连接到 Internet 连接即可安装。

1. 有关最新的 IoT Edge 安装文件以及旧版本，请参阅 Azure IoT Edge 版本。

2. 找到要安装的版本，然后从发行说明的“资产”部分将以下文件下载到 IoT 设备上：

   • IoTEdgeSecurityDaemon.ps1
   • 1\.1 发布通道中的 Microsoft-Azure-IoTEdge-amd64.cab。

   请务必使用与所用 .cab 文件版本相同的 PowerShell 脚本，因为功能会进行更改以支持每个版本中的特性。

3. 如果下载的 .cab 文件在其上有体系结构后缀，则只需将该文件重命名为“Microsoft-Azure-IoTEdge.cab”即可 。

4. （可选）下载 Visual C++ Redistributable 的安装程序。 例如，PowerShell 脚本使用此版本：vc_redist.x64.exe。 将安装程序保存到 IoT 设备上 IoT Edge 文件所在的文件夹中。

5. 若要使用脱机组件进行安装，请使用点获取 PowerShell 脚本本地副本的来源。

6. 用 -OfflineInstallationPath 参数运行 Deploy-IoTEdge 命令。 提供文件目录的绝对路径。 例如，

   . path_to_powershell_module_here\IoTEdgeSecurityDaemon.ps1
   Deploy-IoTEdge -OfflineInstallationPath path_to_file_directory_here
   

   部署命令会使用已提供的本地文件目录中的任何组件。 如果缺少 .cab 文件或 Visual C++ 安装程序，部署命令会尝试下载该文件或安装程序。

卸载 IoT Edge

若要从 Windows 设备中删除 IoT Edge 安装，请在 PowerShell 管理窗口中使用 Uninstall-IoTEdge 命令。 此命令会删除 IoT Edge 运行时，以及现有的配置和 Moby 引擎数据。

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; `
Uninstall-IoTEdge

有关卸载选项的详细信息，请使用命令 Get-Help Uninstall-IoTEdge -full。

后续步骤

转到部署 IoT Edge 模块，了解如何将模块部署到设备上。