開始使用 IoT Hub（預覽版）中的 ADR 整合與 Microsoft 支援的 X.509 憑證管理

本文說明如何建立一個結合 Azure 裝置登錄（ADR）整合及 Microsoft 支援的 X.509 憑證管理的新物聯網中樞。

這很重要

Azure IoT Hub 搭配 ADR 整合和 Microsoft 支援的 X.509 憑證管理目前處於 公開預覽 階段，不建議用於生產工作負載。欲了解更多資訊，請參閱常見問題集：IoT Hub 有什麼新意？

先決條件

有效的 Azure 訂用帳戶。如果您沒有 Azure 訂閱，請建立免費帳戶。
如果你還沒安裝 Azure CLI，請依照步驟安裝 Azure CLI。
安裝 啟用預覽的 Azure IoT CLI 擴充功能 ，以存取 IoT Hub 的 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 releases 頁面下載 .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 執行角色指派需要一個特殊權限角色，例如擁有者或使用者存取管理員，且在適當的範圍內。

選擇部署方法

要使用憑證管理，你還必須設定物聯網中樞、ADR 以及裝置配置服務（DPS）。如果你願意，也可以選擇不啟用憑證管理，只設定帶有 ADR 的 IoT Hub。

要設定帶有 ADR 整合和憑證管理的物聯網中樞，可以使用 Azure CLI 或自動化設定流程的腳本。

部署方法	Description
在頁面頂端選擇 Azure CLI	使用 Azure CLI 建立新的 IoT Hub、DPS 實例和 ADR 命名空間，並設定所有必要的設定。
在頁面頂端選擇 PowerShell 腳本	使用 PowerShell 腳本（僅限 Windows）自動建立新的物聯網中樞、DPS 實例和 ADR 命名空間，並設定所有必要的設定。

概觀

使用 Azure CLI 指令建立一個具備 ADR 整合與憑證管理的物聯網中樞。

本文的設置流程包括以下步驟：

建立資源群組
設定必要的應用程式權限
建立使用者指派的管理型身分識別
建立一個由系統指派的管理身份的 ADR 命名空間
建立一個憑證 (根憑證) 和原則 (發行 CA)，範圍限定在該命名空間
建立一個帶有連結命名空間與管理身份的 IoT Hub（預覽版）
建立一個連結物聯網中樞與命名空間的 DPS
將你的憑證和政策（CA 憑證）同步到 ADR 命名空間
建立一個註冊群並連結你的策略以啟用憑證發放

這很重要

在預覽期間，可免費提供具備 ADR 整合及憑證管理功能之 IoT 中樞，且在 IoT 中樞上啟用該功能。裝置配置服務（DPS）是另外收費的，且不包含在預覽優惠中。有關 DPS 價格的詳細資訊，請參閱 Azure IoT Hub 價格。

準備您的環境

為了準備您的環境以使用 Azure 裝置登錄檔，請完成以下步驟：

開啟終端機視窗。
要登入你的 Azure 帳號，請執行 az login。
要列出你能存取的所有訂閱和租戶，請執行 az account list。
如果你有多個 Azure 訂閱，請在 IoT 裝置建立的位置執行以下命令，以設定你的作用中訂閱。
```
az account set --subscription "<your subscription name or ID>"
```
要顯示你的當前帳戶資料，請執行 az account show。從指令輸出複製以下兩個值，並儲存到安全位置。
- GUID id 。你用這個數值來提供你的訂閱ID。
- GUID tenantId 。你可以用這個值來更新租用戶識別碼的權限。

設定你的資源群組、權限和管理身份

要為您的物聯網解決方案建立資源群組、角色及權限，請完成以下步驟：

為你的環境建立一個資源小組。

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

在資源群組層級為物聯網中心指派一個貢獻者角色。這個 AppId 值是 IoT Hub 的主要 ID， 89d10474-74af-4874-99a7-c23c2f643083 所有 Hub 應用程式都是一樣的。
```
az role assignment create --assignee "89d10474-74af-4874-99a7-c23c2f643083" --role "Contributor" --scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>"
```

建立一個新的使用者指派管理識別（UAMI）。

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

擷取受控識別的資源識別碼。你需要資源 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 and --policy-name 標記來建立一個沒有管理身份的命名空間。

建立一個新的 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 and --cert-validity-days 參數來建立自訂政策。欲了解更多資訊，請參閱建立自訂政策。

備註

建立帶有系統指派管理身份的 ADR 命名空間可能需要長達 5 分鐘。

確認已建立系統指派的管理身份（主體 ID）命名空間。

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

確認已建立一個已命名的認證和原則。

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 Device Registry Contributor 角色指派給受管理的身份，並設定其命名空間範圍。此自訂角色允許在 ADR 命名空間內完整存取物聯網裝置。

取得「User-Assigned Managed Identity」的主要 ID。此 ID 用於為身份指派角色。

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

取得 ADR 命名空間的資源 ID。此 ID 被用作角色指派的範圍。

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

將 Azure 裝置登錄檔參與者角色指派給受控識別。此角色賦予受管理身份必要的權限，權限範圍涵蓋命名空間。
```
az role assignment create --assignee $UAMI_PRINCIPAL_ID --role "a5c3590a-3a1a-4cd4-9648-ea0a32b15137" --scope $NAMESPACE_RESOURCE_ID
```

建立一個帶有 ADR 整合的物聯網中樞

建立一個新的物聯網中樞，連結到 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 端點，在命名時請勿輸入任何敏感或個人識別資訊。

確認物聯網中樞的身份與 ADR 屬性是否正確設定。

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

指派 IoT Hub 角色以存取 ADR 命名空間

取得 ADR 命名空間管理身份的主要 ID。這個身份需要權限才能與物聯網中樞互動。

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

取得物聯網中樞的資源 ID。此 ID 用於角色分配的範圍。

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

將「貢獻者」角色指派給 ADR 身份。這讓 ADR 命名空間的託管身份貢獻者能存取物聯網中心。此角色允許廣泛的存取權限，包括管理資源，但不指派角色。
```
az role assignment create --assignee $ADR_PRINCIPAL_ID --role "Contributor" --scope $HUB_RESOURCE_ID
```
將「IoT 中樞登錄檔參與者」角色指派給 ADR 身分識別。這會賦予更具體的權限來管理物聯網中樞中的裝置身份。這對於 ADR 註冊並管理集線器中的裝置至關重要。
```
az role assignment create --assignee $ADR_PRINCIPAL_ID --role "IoT Hub Registry Contributor" --scope $HUB_RESOURCE_ID
```

建立一個帶有 ADR 整合的裝置配置服務實例

建立一個新的 DPS 實例，連結到前面章節建立的 ADR 命名空間。你的 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

確認 DPS 的身份和 ADR 屬性是否正確設定。

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

將你的物聯網中樞連結到裝置配置服務實例

把物聯網中樞連接到你的 DPS。

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

確認物聯網樞紐是否出現在 DPS 的連結樞紐清單中。

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

執行 ADR 憑證同步

將您的憑證和政策同步到物聯網中心。此步驟確保 IoT 中樞會註冊 CA 憑證，並信任任何由您所設定的策略發出的葉子憑證。

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

驗證中央中心 CA 憑證

驗證您的物聯網中樞是否已註冊其CA憑證。

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

在DPS建立註冊

若要配置使用 leaf 憑證的裝置，請在 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>

您的物聯網中樞具備 ADR 整合與憑證管理功能，現已設置並準備使用。

可選指令

以下指令幫助你管理 ADR 命名空間、停用裝置、建立自訂政策，以及在資源不再需要時刪除。

管理你的命名空間

列出你資源群組中的所有命名空間。

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

顯示特定命名空間的詳細資訊。

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

在你的命名空間中列出所有策略。

az iot adr ns policy list --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>

在你的命名空間中列出所有憑證。

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

禁用設備

列出你物聯網中樞中的所有裝置。

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

將裝置的狀態更新為 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

再執行一次裝置，確認它無法連接到物聯網集線。

建立自訂原則

用這個 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 命名空間，你必須先刪除與該命名空間連結的所有物聯網樞紐和 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 腳本，自動化設置 IoT Hub，並整合 Azure 裝置登錄。腳本執行所有必要步驟，建立所需資源並將其連結，包括：

建立資源群組
設定必要的應用程式權限
建立使用者指派的管理型身分識別
建立一個由系統指派的管理身份的 ADR 命名空間
建立一個憑證 (根憑證) 和原則 (發行 CA)，範圍限定在該命名空間
建立一個帶有連結命名空間與管理身份的 IoT Hub（預覽版）
建立一個連結物聯網中樞與命名空間的 DPS
將你的憑證和政策（CA 憑證）同步到 ADR 命名空間
建立一個註冊群並連結你的策略以啟用憑證發放

這很重要

準備您的環境

下載 PowerShell 7 for Windows。
前往 GitHub 倉庫下載 Scripts 資料夾，裡面有腳本檔。 iothub-adr-certs-setup-preview.ps1

自訂腳本變數

在文字編輯器中打開腳本檔，並修改以下變數以符合你想要的設定。

TenantId：你的房客證。你可以透過在終端機中執行 az account show 來找到這個值。
SubscriptionId：你的訂閱帳號。你可以透過在終端機中執行 az account show 來找到這個值。
ResourceGroup：資源群組的名稱。
Location：你想建立資源的 Azure 區域。請查看「支援區域」部分中的可用位置以獲取預覽功能。
NamespaceName：您的命名空間名稱中，僅可包含小寫字母和連字號（「-」），但不包含在名稱的開頭或結尾。例如，「msft-namespace」是一個有效的名稱。
HubName：你的集線器名稱只能包含小寫字母和數字。
DpsName：你的裝置配置服務實例名稱。
UserIdentity：您資源的使用者指派的受控識別。
WorkingFolder：你的腳本所在的本地資料夾。

這很重要

由於 IoT 中樞可作為可公開探索的 DNS 端點，在命名時請勿輸入任何敏感或個人識別資訊。

互動式執行腳本

打開腳本，以管理員身份在 PowerShell 7+ 中執行。請前往包含腳本的資料夾並執行 .\iothub-adr-certs-setup-preview.ps1。
如果你遇到執行政策的問題，試著執行 powershell -ExecutionPolicy Bypass -File .\iothub-adr-certs-setup-preview.ps1。
遵循引導提示：
- 按 Enter 鍵即可繼續下一步
- 按 s OR S 跳過步驟
- 按Ctrl + C中止

備註

建立 ADR 命名空間、物聯網中樞、DPS 及其他資源，各自可能需要最多 5 分鐘。

監控執行並驗證資源

當遇到警告時，腳本會繼續執行，只有當指令回傳非零的退出碼時才會停止。監控主控台是否有紅色錯誤訊息，表示有需要處理的問題。
腳本完成後，請造訪 Azure 入口網站的新資源群組，驗證資源的建立。你應該會看到以下資源的建立：
- 物聯網 Hub 實例
- 裝置配置服務（DPS）實例
- Azure Device Registry （ADR） namespace
- 使用者指定的管理身份（UAMI）

後續步驟

此時，您的物聯網中樞（具備 ADR 整合與憑證管理）已設置並準備使用。你現在可以開始透過裝置配置服務（DPS）實例，將物聯網裝置導入樞紐，並利用你設定的政策和註冊，安全地管理物聯網裝置。

新增：憑證管理已支援特定 DPS 裝置 SDK 使用。你現在可以使用以下 SDK 範例，使用 Microsoft 支援的 X.509 憑證管理來安裝裝置：

嵌入式 C：
- 裸金屬：取樣
- 免費RTOS：範例
C：範例
Python：範例

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-20

共用方式為

開始使用 IoT Hub（預覽版）中的 ADR 整合與 Microsoft 支援的 X.509 憑證管理

先決條件

選擇部署方法

概觀

準備您的環境

設定你的資源群組、權限和管理身份

建立新的 ADR 命名空間

指派 UAMI 角色以存取 ADR 命名空間

建立一個帶有 ADR 整合的物聯網中樞

指派 IoT Hub 角色以存取 ADR 命名空間

建立一個帶有 ADR 整合的裝置配置服務實例

將你的物聯網中樞連結到裝置配置服務實例

執行 ADR 憑證同步

驗證中央中心 CA 憑證

在DPS建立註冊

可選指令

管理你的命名空間

禁用設備

建立自訂原則

刪除資源

概觀

準備您的環境

自訂腳本變數

互動式執行腳本

監控執行並驗證資源

後續步驟

意見反應

其他資源