通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

IoT 中心中的 ADR 集成和Microsoft支持的 X.509 证书管理入门（预览版）

本文介绍如何使用 Azure 设备注册表（ADR） 集成和 Microsoft支持的 X.509 证书管理创建新的 IoT 中心。

重要

具有 ADR 集成和Microsoft支持的 X.509 证书管理的 Azure IoT 中心以 公共预览版 提供，不建议用于生产工作负荷。 有关详细信息，请参阅常见问题解答：IoT 中心有哪些新增功能？

先决条件

  • 有效的 Azure 订阅。 如果没有 Azure 订阅，可以创建一个免费帐户。

  • 如果未安装 Azure CLI，请按照以下步骤 安装 Azure CLI。

  • 安装 启用了预览功能的 Azure IoT CLI 扩展 ，以便访问 IoT 中心的 ADR 集成和证书管理功能：

    1. 检查现有的 Azure CLI 扩展安装。

      az extension list

    2. 删除任何现有的“azure iot”安装。

      az extension remove --name azure-iot

    3. 从索引安装启用了预览功能的 azure-iot 扩展，

      az extension add --name azure-iot --allow-preview

      或从 GitHub 发布页下载 .whl 文件以手动安装扩展。

      az extension add --upgrade --source https://github.com/Azure/azure-iot-cli-extension/releases/download/v0.30.0b1/azure_iot-0.30.0b1-py3-none-any.whl

    4. 安装后，验证 azure-iot 扩展版本是否大于 0.30.0b1。

      az extension list

  • 确保你有权在目标范围内执行角色分配。 在 Azure 中执行角色分配需要 特权角色，例如适当范围内的所有者或用户访问管理员。

选择部署方法

若要使用证书管理，还必须设置 IoT 中心、ADR 和设备预配服务（DPS）。 如果愿意，可以选择不启用证书管理和仅使用 ADR 配置 IoT 中心。

若要使用 ADR 集成和证书管理设置 IoT 中心，可以使用 Azure CLI 或自动执行设置过程的脚本。

部署方法 Description
选择页面顶部的 Azure CLI 使用 Azure CLI 创建新的 IoT 中心、DPS 实例和 ADR 命名空间，并配置所有必要的设置。
选择页面顶部的 PowerShell 脚本 使用 PowerShell 脚本（仅限 Windows）自动创建新的 IoT 中心、DPS 实例和 ADR 命名空间，并配置所有必要的设置。

概述

使用 Azure CLI 命令创建具有 ADR 集成和证书管理的 IoT 中心。

本文中的设置过程包括以下步骤：

  1. 创建资源组
  2. 配置必要的应用特权
  3. 创建用户分配的托管标识
  4. 使用系统分配的托管标识创建 ADR 命名空间
  5. 创建作用域限定于该命名空间的凭据（根 CA）和策略（发证 CA）
  6. 使用链接命名空间和托管标识创建 IoT 中心（预览版）
  7. 使用链接的 IoT 中心和命名空间创建 DPS
  8. 将凭据和策略（CA 证书）同步到 ADR 命名空间
  9. 创建注册组并链接到策略设置以启用证书预配

重要

在预览期间，IoT 中心及在 IoT 中心上启用的 ADR 集成和证书管理功能将免费提供。 设备预配服务（DPS）单独计费，并且不包括在预览版产品/服务中。 有关 DPS 定价的详细信息，请参阅 Azure IoT 中心定价。

准备好你的环境

若要准备环境以使用 Azure 设备注册表，请完成以下步骤：

  1. 打开终端窗口。

  2. 若要登录到 Azure 帐户，请运行 az login。

  3. 若要列出你有权访问的所有订阅和租户，请运行 az account list。

  4. 如果您有权访问多个 Azure 订阅，请通过运行以下命令来设置您的活动订阅，以便在其中创建 IoT 设备。

    az account set --subscription "<your subscription name or ID>"

  5. 若要显示当前帐户详细信息，请运行 az account show。 从命令的输出中复制以下两个值，并将其保存到安全位置。

    • id GUID。 使用此值用于提供订阅 ID。
    • tenantId GUID。 使用此值通过租户 ID 更新权限。

配置资源组、权限和托管标识

若要为 IoT 解决方案创建资源组、角色和权限，请完成以下步骤：

  1. 为环境创建资源组。

    az group create --name <RESOURCE_GROUP_NAME> --location <REGION>

  2. 将参与者角色分配给资源组级别的 IoT 中心。 该值 AppId 是 IoT 中心的主要 ID， 89d10474-74af-4874-99a7-c23c2f643083 对于所有中心应用都是相同的。

    az role assignment create --assignee "89d10474-74af-4874-99a7-c23c2f643083" --role "Contributor" --scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>"

  3. 创建新的用户分配的托管标识 (UAMI)。

    az identity create --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME> --location <REGION>

  4. 检索托管标识的资源 ID。 需要资源 ID 来分配角色、配置访问策略或将标识链接到其他资源。

    UAMI_RESOURCE_ID=$(az identity show --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME> --query id -o tsv)

创建新的 ADR 命名空间

在本部分中，你将使用系统分配的托管标识创建新的 ADR 命名空间。 此过程自动生成命名空间的根 CA 凭据和颁发 CA 策略。 有关在配置过程中如何使用凭据和策略对设备叶证书进行签署的详细信息，请参阅 证书管理。

注释

凭据是可选的。 还可以通过省略--enable-credential-policy--policy-name标志来创建没有托管标识的命名空间。

  1. 创建新的 ADR 命名空间。 命名空间 name 中只能包含小写字母和连字符（'-'），但不能在开头或结尾。 例如，名称“msft-namespace”有效。
    该 --enable-credential-policy 命令为此命名空间创建凭据（根 CA）和默认策略（颁发 CA）。 可以使用 --policy-name 命令配置此策略的名称。 默认情况下，策略可以颁发有效期为 30 天的证书。

    az iot adr ns create --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --location <REGION> --enable-credential-policy true --policy-name <POLICY_NAME>

    小窍门

    可以选择通过添加 --cert-subject 和 --cert-validity-days 参数创建自定义策略。 有关详细信息，请参阅 创建自定义策略。

    注释

    使用系统分配的托管标识创建 ADR 命名空间可能需要长达 5 分钟。

  2. 验证是否创建了具有系统分配的托管标识或主体 ID 的命名空间。

    az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  3. 验证是否已创建已命名的凭据和策略。

    az iot adr ns credential show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot adr ns policy show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --name <POLICY_NAME>

    注释

    如果未分配策略名称，则会使用名称“default”创建策略。

分配 UAMI 角色以访问 ADR 命名空间

在本部分中，你将 Azure 设备注册表参与者 角色分配给托管标识，并将其限定为命名空间。 此自定义角色允许完全访问 ADR 命名空间中的 IoT 设备。

  1. 检索用户分配的托管标识的主体 ID。 需要该 ID 才能将角色分配给标识。

    UAMI_PRINCIPAL_ID=$(az identity show --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP> --query principalId -o tsv)

  2. 检索 ADR 命名空间的资源标识符。 此 ID 用于界定角色分配的范围。

    NAMESPACE_RESOURCE_ID=$(az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP> --query id -o tsv)

  3. 将 Azure 设备注册表贡献者 角色分配给托管标识。 此角色向受管理标识授予必要的权限，并限制在特定命名空间内。

    az role assignment create --assignee $UAMI_PRINCIPAL_ID --role "a5c3590a-3a1a-4cd4-9648-ea0a32b15137" --scope $NAMESPACE_RESOURCE_ID

使用 ADR 集成创建 IoT 中心

  1. 创建一个新的 IoT 中心，该中心链接到 ADR 命名空间，并使用前面创建的 UAMI。

    az iot hub create --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --location <HUB_LOCATION> --sku GEN2 --mi-user-assigned $UAMI_RESOURCE_ID --ns-resource-id $NAMESPACE_RESOURCE_ID --ns-identity-id $UAMI_RESOURCE_ID

    重要

    由于 IoT 中心将作为 DNS 终结点公开可发现，因此请务必避免在命名它时输入任何敏感信息或个人身份信息。

  2. 验证 IoT 中心是否配置了正确的标识和 ADR 属性。

    az iot hub show --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --query identity --output json

分配 IoT 中心角色以访问 ADR 命名空间

  1. 检索 ADR 命名空间的托管标识的主体标识符。 此标识需要权限才能与 IoT 中心交互。

    ADR_PRINCIPAL_ID=$(az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP> --query identity.principalId -o tsv)

  2. 检索 IoT 中心的资源 ID。 此 ID 用于界定角色分配的范围。

    HUB_RESOURCE_ID=$(az iot hub show --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --query id -o tsv)

  3. 将“参与者”角色分配给 ADR 标识。 这会授予 ADR 命名空间的托管标识参与者对 IoT 中心的访问权限。 此角色允许广泛访问，包括管理资源，但不允许分配角色。

    az role assignment create --assignee $ADR_PRINCIPAL_ID --role "Contributor" --scope $HUB_RESOURCE_ID

  4. 将“IoT 中心注册表参与者”角色分配给 ADR 标识。 这会授予管理 IoT 中心内设备标识的更具体权限。 这对于 ADR 在集线器内注册和管理设备至关重要。

    az role assignment create --assignee $ADR_PRINCIPAL_ID --role "IoT Hub Registry Contributor" --scope $HUB_RESOURCE_ID

使用 ADR 集成创建设备预配服务实例

  1. 创建链接到前面部分中创建的 ADR 命名空间的新 DPS 实例。 DPS 实例必须与 ADR 命名空间位于同一区域。

    az iot dps create --name <DPS_NAME> --resource-group <RESOURCE_GROUP> --location <LOCATION> --mi-user-assigned $UAMI_RESOURCE_ID --ns-resource-id $NAMESPACE_RESOURCE_ID --ns-identity-id $UAMI_RESOURCE_ID

  2. 验证 DPS 是否配置了正确的标识和 ADR 属性。

    az iot dps show --name <DPS_NAME> --resource-group <RESOURCE_GROUP> --query identity --output json

  1. 将 IoT 中心链接到 DPS。

    az iot dps linked-hub create --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP> --hub-name <HUB_NAME>

  2. 验证 IoT 中心是否显示在 DPS 的链接中心列表中。

    az iot dps linked-hub list --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP>

运行 ADR 凭据同步

将凭据和策略同步到 IoT 中心。 此步骤确保 IoT Hub 注册 CA 证书，并信任根据您配置的策略颁发的任何终端证书。

az iot adr ns credential sync --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP>

验证中心 CA 证书

验证 IoT 中心是否已注册其 CA 证书。

az iot hub certificate list --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP>

在 DPS 中创建注册

若要使用叶证书预配设备，请在 DPS 中创建注册组，并使用 --credential-policy 参数将其分配给相应的凭据策略。

以下命令默认使用对称密钥证明创建注册组：

注释

如果创建了名称与“default”不同的策略，请确保在参数后面 --credential-policy 使用该策略名称。

az iot dps enrollment-group create --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP> --enrollment-id <ENROLLMENT_ID> --credential-policy <POLICY_NAME>

您的 IoT 中心现已设置完毕，并支持 ADR 集成和证书管理，可以开始使用了。

可选命令

以下命令可帮助你管理 ADR 命名空间、禁用设备、创建自定义策略以及删除不再需要的资源。

管理命名空间

  1. 列出资源组中的所有命名空间。

    az iot adr ns list --resource-group <RESOURCE_GROUP_NAME>

  2. 显示特定命名空间的详细信息。

    az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  3. 列出命名空间中的所有策略。

    az iot adr ns policy list --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  4. 显示特定策略的详细信息。

    az iot adr ns policy show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --name <POLICY_NAME>

  5. 列出命名空间中的所有凭据。

    az iot adr ns credential list --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

禁用设备

  1. 列出 IoT 中心中的所有设备。

    az iot hub device-identity list --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME>

  2. 通过将设备状态更新为 disabled 来禁用设备。 请确保将 <MY_DEVICE_ID> 替换为要禁用的设备 ID。

    az iot hub device-identity update --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME> -d <MY_DEVICE_ID> --status disabled

  3. 再次运行设备并验证它是否无法连接到 IoT 中心。

创建自定义策略

使用 az iot adr ns policy create 命令创建自定义策略。 按照以下规则设置策略的名称、证书主体和有效期：

  • 策略 name 值在命名空间中必须是唯一的。 如果尝试创建具有已存在名称的策略，将收到错误消息。
  • 证书主体 cert-subject 值在命名空间中的所有策略中必须唯一。 如果尝试创建具有已存在的主题的策略，将收到错误消息。
  • 有效期 cert-validity-days 值必须介于 1 到 30 天之间。 如果尝试创建在此范围之外的有效期的策略，将收到错误消息。

以下示例创建名为“custom-policy”的策略，主题为“CN=TestDevice”，有效期为 30 天。

az iot adr ns policy create --name "custom-policy" --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --cert-subject "CN=TestDevice" --cert-validity-days "30"

删除资源

若要删除 ADR 命名空间，必须先删除链接到命名空间的任何 IoT 中心和 DPS 实例。

az iot hub delete --name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot adr ns delete --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot dps delete --name <DPS_NAME> --resource-group <RESOURCE_GROUP_NAME> 
az identity delete --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME>

概述

使用提供的 PowerShell 脚本通过 Azure 设备注册表集成自动设置 IoT 中心。 该脚本执行创建所需资源并将它们链接在一起所需的所有步骤，包括：

  1. 创建资源组
  2. 配置必要的应用特权
  3. 创建用户分配的托管标识
  4. 使用系统分配的托管标识创建 ADR 命名空间
  5. 创建作用域限定于该命名空间的凭据（根 CA）和策略（发证 CA）
  6. 使用链接命名空间和托管标识创建 IoT 中心（预览版）
  7. 使用链接的 IoT 中心和命名空间创建 DPS
  8. 将凭据和策略（CA 证书）同步到 ADR 命名空间
  9. 创建注册组并链接到策略设置以启用证书预配

重要

在预览期间，IoT 中心及在 IoT 中心上启用的 ADR 集成和证书管理功能将免费提供。 设备预配服务（DPS）单独计费，并且不包括在预览版产品/服务中。 有关 DPS 定价的详细信息，请参阅 Azure IoT 中心定价。

准备好你的环境

  1. 下载 PowerShell 7 for Windows。
  2. 导航到 GitHub 存储库 并下载 包含 脚本文件的 iothub-adr-certs-setup-preview.ps1Scripts 文件夹。

自定义脚本变量

在文本编辑器中打开脚本文件，并修改以下变量以匹配所需的配置。

  • TenantId：租户 ID。 可以通过在终端中运行 az account show 来查找此值。
  • SubscriptionId：订阅 ID。 可以通过在终端中运行 az account show 来查找此值。
  • ResourceGroup：资源组的名称。
  • Location：要在其中创建资源的 Azure 区域。 请查看 “支持区域 ”部分中预览功能的可用位置。
  • NamespaceName：命名空间名称只能包含名称中间的小写字母和连字符（'-），但不能包含在开头或结尾。 例如，“msft-namespace”是一个有效名称。
  • HubName：中心名称只能包含小写字母和数字。
  • DpsName：设备预配服务实例的名称。
  • UserIdentity：资源的用户分配的托管标识。
  • WorkingFolder：脚本所在的本地文件夹。

重要

由于 IoT 中心将作为 DNS 终结点公开可发现，因此请务必避免在命名它时输入任何敏感信息或个人身份信息。

以交互方式运行脚本

  1. 打开脚本，以 管理员身份在 PowerShell 7+ 中运行。 导航到包含脚本的文件夹并运行 .\iothub-adr-certs-setup-preview.ps1。

  2. 如果遇到执行策略问题，请尝试运行 powershell -ExecutionPolicy Bypass -File .\iothub-adr-certs-setup-preview.ps1。

  3. 按照引导提示操作。

    • 按 Enter 以继续执行步骤
    • 按 s 或 S 跳过步骤
    • 按 Ctrl + C 中止

注释

创建 ADR 命名空间、IoT 中心、DPS 和其他资源可能需要最多 5 分钟。

监视执行并验证资源

  1. 当遇到警告时，脚本将继续执行，仅当命令返回非零退出代码时停止。 监视控制台中的红色 错误消息 ，指示需要注意的问题。

  2. 脚本完成后，通过访问 Azure 门户上的新资源组来验证资源的创建。 应会看到已创建以下资源：

    • IoT 中心实例
    • 设备预配服务 （DPS） 实例
    • Azure 设备注册表 （ADR） 命名空间
    • 用户分配托管标识（UAMI）

后续步骤

此时，具有 ADR 集成和证书管理的 IoT 中心已设置并可供使用。 现在，可以使用设备预配服务（DPS）实例开始将 IoT 设备加入中心，并使用设置的策略和注册安全地管理 IoT 设备。

新增功能：在指定的一些 DPS 设备 SDK 中支持证书管理。 现在，您可以使用 Microsoft 支持的 X.509 证书管理，通过以下 SDK 示例载入设备：

  • Last updated on