以程式設計方式建立 X.509 憑證證明的裝置布建服務註冊群組

發行項
01/19/2024

本文說明如何以程序設計方式建立使用中繼或根 CA X.509 憑證的註冊群組。註冊群組是使用 Azure IoT 中樞 DPS 服務 SDK 和範例應用程式所建立。註冊群組可控制共用其憑證鏈結中通用簽署憑證之裝置的布建服務存取權。若要深入瞭解，請參閱使用 X.509 憑證控制裝置存取。如需搭配 Azure IoT 中樞和裝置布建服務使用 X.509 憑證型公鑰基礎結構（PKI）的詳細資訊，請參閱 X.509 CA 憑證安全性概觀。

必要條件

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
使用 Azure 入口網站完成設定 IoT 中樞裝置布建服務中的步驟。

在 Windows 電腦上安裝 .NET 6.0 SDK 或更新版本。您可以使用下列命令來檢查您的版本。
```
dotnet --info
```

在您的電腦上安裝 Node.js v4.0 或更新版本。

Java SE 開發套件 8。本文使用適用於 Java 的 Azure IoT SDK，適用於 Windows 和 Linux。本文使用 Windows。
Maven 3.

安裝最新版本的 Git。請確定 Git 已新增至命令視窗可存取的環境變數。請參閱 Software Freedom Conservancy 的 Git 用戶端工具，以取得要安裝之最新版 git 的工具，其中包括 Git Bash，您可以用來與本機 Git 存放庫互動的命令行應用程式。

注意

雖然本文中的步驟適用於 Windows 和 Linux 計算機，但本文會使用 Windows 開發電腦。

建立測試憑證

使用 X.509 憑證證明的註冊群組可以設定為使用根 CA 憑證或中繼憑證。較常見的情況是使用中繼憑證來設定註冊群組。使用中繼憑證可提供更大的彈性，因為相同的根 CA 憑證可以產生或撤銷多個中繼憑證。

在本文中，您需要根 CA 憑證檔案、中繼 CA 憑證檔案，或是 .pem 或 .cer 格式。一個檔案包含根 CA X.509 憑證的公用部分，另一個檔案包含中繼 CA X.509 憑證的公用部分。

如果您已經有根 CA 檔案和/或中繼 CA 檔案，您可以繼續新增並驗證您的根或中繼 CA 憑證。

如果您沒有根 CA 檔案和/或中繼 CA 檔案，請遵循建立 X.509 憑證鏈結中的步驟來建立它們。當您完成建立中繼 CA 憑證中的步驟之後，您可以停止，因為您不需要裝置憑證即可完成本文中的步驟。完成後，您有兩個 X.509 憑證檔案： ./certs/azure-iot-test-only.root.ca.cert.pem 和 ./certs/azure-iot-test-only.intermediate.cert.pem。

新增並驗證您的根或中繼 CA 憑證

使用 X.509 憑證透過註冊群組布建的裝置，會在使用 DPS 進行驗證時呈現整個憑證鏈結。若要讓 DPS 能夠驗證憑證鏈結，註冊群組中設定的跟證書或中繼憑證必須是已驗證的憑證，或必須在裝置向服務進行驗證時，匯總到憑證鏈結中已驗證的憑證。

在本文中，假設您有根 CA 憑證和根 CA 簽署的中繼 CA 憑證：

如果您打算使用根 CA 憑證建立註冊群組，您必須上傳並驗證根 CA 憑證。
如果您打算使用中繼 CA 憑證建立註冊群組，您可以上傳並驗證根 CA 憑證或中繼 CA 憑證。（如果您在憑證鏈結中有多個中繼 CA 憑證，您也可以上傳並驗證位於根 CA 憑證與建立註冊群組的中繼憑證之間的任何中繼憑證。

若要將根或中繼 CA 憑證新增並驗證至裝置布建服務：

登入 Azure 入口網站。
在左側功能表或入口網站頁面上，選取 [ 所有資源]。
選取您的裝置布建服務。
在 [設定] 功能表中，選取 [憑證]。
在頂端功能表上，選取 [+ 新增]：。
輸入根或中繼 CA 憑證的名稱，然後上傳 .pem 或 .cer 檔案。
選取 [ 設定憑證狀態] 以在上傳時驗證。
選取 [儲存]。

取得布建服務的連接字串

針對本文中的範例，您需要布建服務的連接字串。使用下列步驟來擷取它。

登入 Azure 入口網站。
在左側功能表或入口網站頁面上，選取 [ 所有資源]。
選取您的裝置布建服務。
在 [設定] 功能表中，選取 [共用存取原則]。
選取您想要使用的存取原則。
在 [存取原則] 面板中，複製並儲存主鍵連接字串。

建立註冊群組範例

本節說明如何建立 .NET Core 控制台應用程式，以將註冊群組新增至布建服務。

開啟 Windows 命令提示字元，並流覽至您要在其中建立應用程式的資料夾。

若要建立主控台專案，請執行下列命令：

dotnet new console --framework net6.0 --use-program-main

若要新增 DPS 服務 SDK 的參考，請執行下列命令：
```
dotnet add package Microsoft.Azure.Devices.Provisioning.Service 
```
此步驟會下載、安裝及新增 Azure IoT DPS 服務用戶端 NuGet 套件及其相依性的參考。此套件包含 .NET 服務 SDK 的二進位檔。
在編輯器中開啟 Program.cs 檔案。
將檔案頂端的 namespace 語句取代為下列這一行：
```
namespace CreateEnrollmentGroup;
```

在語句上方namespace的檔案頂端新增下列 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 類別。此程式代碼會建立專案 EnrollmentGroup ，然後呼叫 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();
}

儲存您的變更。

本節說明如何建立將註冊群組新增至布建服務的Node.js腳本。

從工作資料夾中的指令視窗中，執行：
```
npm install azure-iot-provisioning-service
```
此步驟會下載、安裝及新增 Azure IoT DPS 服務用戶端套件及其相依性的參考。此套件包含Node.js服務 SDK 的二進位檔。

使用文本編輯器，在工作資料夾中建立 create_enrollment_group.js 檔案。將下列程式代碼新增至檔案並儲存：

    'use strict';
    var fs = require('fs');

    var provisioningServiceClient = require('azure-iot-provisioning-service').ProvisioningServiceClient;

    var serviceClient = provisioningServiceClient.fromConnectionString(process.argv[2]);

    var enrollment = {
      enrollmentGroupId: 'first',
      attestation: {
        type: 'x509',
        x509: {
          signingCertificates: {
            primary: {
              certificate: fs.readFileSync(process.argv[3], 'utf-8').toString()
            }
          }
        }
      },
      provisioningStatus: 'disabled'
    };

    serviceClient.createOrUpdateEnrollmentGroup(enrollment, function(err, enrollmentResponse) {
      if (err) {
        console.log('error creating the group enrollment: ' + err);
      } else {
        console.log("enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2));
        enrollmentResponse.provisioningStatus = 'enabled';
        serviceClient.createOrUpdateEnrollmentGroup(enrollmentResponse, function(err, enrollmentResponse) {
          if (err) {
            console.log('error updating the group enrollment: ' + err);
          } else {
            console.log("updated enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2));
          }
        });
      }
    });

開啟 Windows 命令提示字元。
使用 Java 服務 SDK 複製裝置註冊程式代碼範例的 GitHub 存放庫：
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```

從您下載存放庫的位置，移至範例資料夾：

cd azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample

在 您選擇的編輯器中開啟 /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java 檔案。
將取代[Provisioning Connection String]為您在取得布建服務的連接字串中複製的連接字串。
以 PUBLIC_KEY_CERTIFICATE_STRING 根或中繼 CA 憑證 .pem 檔案的值取代常數位符串。此檔案代表先前透過布建服務上傳和驗證的根 CA X.509 憑證的公用部分，或已上傳和驗證其簽署鏈結中已上傳和驗證的中繼憑證。

憑證文字的語法必須遵循下列模式，且沒有額外的空格或字元。
```
private static final String PUBLIC_KEY_CERTIFICATE_STRING = 
        "-----BEGIN CERTIFICATE-----\n" +
        "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
            ...
        "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
        "-----END CERTIFICATE-----";
```
手動更新此字串值可能會容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 提示字元中，以憑證檔案的位置取代 your-cert.pem ，然後按 ENTER。此命令會產生字串常數值的 PUBLIC_KEY_CERTIFICATE_STRING 語法，並將它寫入輸出。
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' your-cert.pem
```
複製並貼上常數值的輸出憑證文字。
重要

在生產程序代碼中，請注意下列安全性考慮：
- 針對布建服務管理員的連接字串進行硬式編碼，是針對安全性最佳做法。相反地，連接字串應以安全的方式保留，例如在安全組態檔或登錄中。
- 請務必只上傳簽署憑證的公用部分。請勿將包含私鑰的 .pfx （PKCS12）或 .pem 檔案上傳至布建服務。
此範例可讓您在註冊群組中設定IoT中樞來布建裝置。這必須是先前已連結至布建服務的IoT中樞。在本文中，我們讓 DPS 根據預設配置原則，從鏈接中樞選擇，平均加權分配。將檔案中的下列語句批注化：
```
enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);                // Optional parameter.
```

範例程式代碼會建立、更新、查詢及刪除 X.509 裝置的註冊群組。若要確認在 Azure 入口網站中成功建立註冊群組，請將下列程式代碼行批注化到檔案結尾附近：

// ************************************** Delete info of enrollmentGroup ***************************************
System.out.println("\nDelete the enrollmentGroup...");
provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);

儲存 ServiceEnrollmentGroupSample.java 檔案。

執行註冊群組範例

執行範例：
```
dotnet run
```
成功建立時，命令視窗會顯示新註冊群組的屬性。

在命令提示字元中執行下列命令。包含命令自變數的引號，並以您在上一節中複製的連接字串取代，並以<certificate .pem file>憑證.pem檔案的路徑取代 <connection string> 。此檔案代表先前透過布建服務上傳和驗證的根 CA X.509 憑證的公用部分，或已上傳和驗證其簽署鏈結中已上傳和驗證的中繼憑證。
```
node create_enrollment_group.js "<connection string>" "<certificate .pem file>"
```
成功建立時，命令視窗會顯示新註冊群組的屬性。

從命令提示字元中的 azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample 資料夾中，執行下列命令來建置範例：
```
mvn install -DskipTests
```
此命令會將 Azure IoT DPS 服務用戶端 Maven 套件下載到您的電腦，並建置範例。此套件包含 Java 服務 SDK 的二進位檔。
切換至目標資料夾並執行範例。上一個步驟中的組建會輸出目標資料夾中具有下列檔格式的.jar檔案：;例如：provisioning-x509-sample-{version}-with-deps.jarprovisioning-x509-sample-1.8.1-with-deps.jar。 您可能需要取代下列命令中的版本。
```
cd target
java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar
```
成功建立時，命令視窗會顯示新註冊群組的屬性。

若要確認註冊群組已建立：

在 Azure 入口網站中，流覽至您的裝置布建服務實例。
在 [設定] 功能表中，選取 [管理註冊]。
選取 [ 註冊群組] 索引標籤 。您應該會看到新的註冊專案，其對應至您在範例中使用的註冊群組標識碼。

顯示入口網站中新建立註冊群組的螢幕快照。

清除資源

如果您打算探索 Azure IoT 中樞裝置布建服務教學課程，請勿清除本文中建立的資源。否則，請使用下列步驟來刪除本文所建立的所有資源。

關閉電腦上的範例輸出視窗。
從 Azure 入口網站的左側功能表中，選取 [所有資源]。
選取您的裝置布建服務。
在左側功能表的 [設定] 下，選取 [管理註冊]。
選取 [ 註冊群組] 索引標籤 。
選取您在本文中建立之註冊群組組名旁的複選框。
在頁面頂端，選取 [刪除]。
從 Azure 入口網站中的裝置布建服務，選取左側功能表上設定下的 [憑證]。
選取您為此文章上傳的憑證。
在 [憑證詳細數據] 頂端，選取 [刪除]。

憑證工具

Azure IoT C SDK 具有可協助您建立和管理憑證的腳本。若要深入瞭解，請參閱管理範例和教學課程的測試 CA 憑證。

Azure IoT Node.js SDK 具有可協助您建立和管理憑證的腳本。若要深入瞭解，請參閱 Azure IoT 裝置布建裝置 SDK for Node.js的工具。

您也可以使用 Azure IoT C SDK 中可用的工具。若要深入瞭解，請參閱管理範例和教學課程的測試 CA 憑證。

Azure IoT Java SDK 包含可協助您建立和管理憑證的測試工具。若要深入瞭解，請參閱使用 DICE 模擬器的 X509 憑證產生器。

下一步

在本文中，您已使用 Azure IoT 中樞裝置布建服務，建立 X.509 中繼或根 CA 憑證的註冊群組。若要進一步探索，請參閱下列連結：

如需 X.509 憑證證明與 DPS 的詳細資訊，請參閱 X.509 憑證證明。
如需使用 X.509 憑證透過註冊群組布建裝置的端對端範例，請參閱使用註冊群組布建多個 X.509 裝置教學課程。
若要瞭解如何使用 Azure 入口網站管理個別註冊和註冊群組，請參閱如何使用 Azure 入口網站管理裝置註冊。

Share via

以程式設計方式建立 X.509 憑證證明的裝置布建服務註冊群組

必要條件

建立測試憑證

新增並驗證您的根或中繼 CA 憑證

取得布建服務的連接字串

建立註冊群組範例

執行註冊群組範例

清除資源

憑證工具

下一步

其他資源

Share via

以程式設計方式建立 X.509 憑證證明的裝置布建服務註冊群組

必要條件

建立測試憑證

新增並驗證您的根或中繼 CA 憑證

取得布建服務的 連接字串

建立註冊群組範例

執行註冊群組範例

清除資源

憑證工具

下一步

其他資源

取得布建服務的連接字串