共用方式為

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

  • 發行項

本文為您說明如何以程式設計方式建立使用中繼或根 CA X.509 憑證的註冊群組。 註冊群組是使用 Azure IoT 中樞 DPS 服務 SDK 和簡單應用程式來建立的。 註冊群組可針對共用憑證鏈結中通用簽署憑證的裝置，控制對於佈建服務的存取權。 若要深入瞭解，請參閱 搭配 DPS 使用 X.509 憑證。 如需使用以 X.509 憑證為基礎的公開金鑰基礎結構 (PKI) 搭配 Azure IoT 中樞和裝置佈建服務的詳細資訊，請參閱 X.509 CA 憑證安全性概觀。

必要條件

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

注意

雖然本文中的步驟在 Windows 和 Linux 電腦上都可運作，但本文將使用 Windows 開發電腦。

建立測試憑證

使用 X.509 憑證證明的註冊群組可以設定為使用根憑證或中繼憑證。 較常見的情況是設定註冊群組使用中繼憑證。 使用中繼憑證可提供更大的彈性，因為同一個根 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 憑證新增並驗證至裝置佈建服務：

  1. 登入 Azure 入口網站。

  2. 在左側功能表或入口網站頁面上，選取 [所有資源]。

  3. 選取您的裝置佈建服務。

  4. 在 [設定] 功能表中，選取 [憑證]。

  5. 在頂端功能表上，選取 [+ 新增]。

  6. 輸入根或中繼 CA 憑證的名稱，然後上傳 .pem 或 .cer 檔案。

  7. 選取 [設定在上傳時驗證憑證狀態​]。

    顯示將根 CA 憑證新增至 DPS 實例的螢幕快照。

  8. 選取 [儲存]。

取得佈建服務的連接字串

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

  1. 登入 Azure 入口網站。

  2. 在左側功能表或入口網站頁面上，選取 [所有資源]。

  3. 選取您的裝置佈建服務。

  4. 在 [設定] 功能表中，選取 [共用存取原則]。

  5. 選取您想要使用的存取原則。

  6. 在 [存取原則] 面板中，複製並儲存主要金鑰連接字串。

    顯示入口網站中布建服務 連接字串 位置的螢幕快照。

建立註冊群組範例

本節會為您說明如何建立 .NET Core 主控台應用程式，以將註冊群組新增至您的佈建服務。

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

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

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

  3. 若要新增 DPS 服務 SDK 的參考，請執行下列命令：

    dotnet add package Microsoft.Azure.Devices.Provisioning.Service

    此步驟會下載及安裝 Azure IoT DPS 服務用戶端 NuGet 套件及其相依性，並新增其參考。 此套件包含 .NET 服務 SDK 的二進位檔。

  4. 在編輯器中開啟 Program.cs 檔案。

  5. 將位於檔案頂端的命名空間陳述式取代為下行：

    namespace CreateEnrollmentGroup;

  6. 在檔案頂端的 namespace 陳述式上方新增下列 using 陳述式：

    using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using Microsoft.Azure.Devices.Provisioning.Service;

  7. 將下列欄位新增至 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 檔案上傳至佈建服務。

  8. 將下列方法新增至 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

    }
}

  9. 最後，將 Main 方法取代為下列幾行：

    static async Task Main(string[] args)
{
    await RunSample();
    Console.WriteLine("\nHit <Enter> to exit ...");
    Console.ReadLine();
}

  10. 儲存您的變更。

本節將說明如何建立 .Node.js 指令碼，以將註冊群組新增至您的佈建服務。

  1. 從工作資料夾中的命令視窗中，執行：

    npm install azure-iot-provisioning-service

    此步驟會下載及安裝 Azure IoT DPS 服務用戶端套件及其相依性，並新增其參考。 此套件包含 Node.js 服務 SDK 的二進位檔。

  2. 使用文字編輯器，在工作資料夾中建立 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));
          }
        });
      }
    });

  1. 開啟 Windows 命令提示字元。

  2. 使用 Java 服務 SDK 來複製裝置註冊程式碼範例的 GitHub 存放庫：

    git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive

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

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

  4. 在您選擇的編輯器中開啟檔案 /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java。

  5. 將 [Provisioning Connection String] 取代為您在取得佈建服務的連接字串中複製的連接字串。

  6. 將 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 檔案上傳至佈建服務。

  7. 此範例可讓您在註冊群組中設定 IoT 中樞，以將裝置佈建到該處。 這必須是先前已連結至佈建服務的 IoT 中樞。 在本文中，我們會讓 DPS 根據預設配置原則 (平均加權分佈) 從連結的中樞中選擇。 將檔案中的下列陳述式註解化：

    enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);                // Optional parameter.

  8. 範例程式碼會建立、更新、查詢和刪除 X.509 裝置的註冊群組。 若要驗證 Azure 入口網站中的註冊群組是否成功建立，請註解化檔案結尾附近的下列行：

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

  9. 儲存 ServiceEnrollmentGroupSample.java 檔案。

執行註冊群組範例

  1. 執行範例：

    dotnet run

  2. 成功建立時，命令視窗會顯示新註冊群組的屬性。

  1. 在命令提示字元中，執行下列命令。 在命令引數周圍包含引號，並且將 <connection string> 取代為您在上一個區段中複製的連接字串，以及將 <certificate .pem file> 取代為您的憑證 .pem 檔案的路徑。 此檔案代表根 CA X.509 憑證的公用部分，該憑證先前已透過您的佈建服務上傳和驗證，或本身已上傳並驗證的中繼憑證，或在其上傳及驗證的簽署鏈結中有憑證。

    node create_enrollment_group.js "<connection string>" "<certificate .pem file>"

  2. 成功建立時，命令視窗會顯示新註冊群組的屬性。

  1. 從命令提示字元中的 azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample 資料夾中，執行下列命令以建置範例：

    mvn install -DskipTests

    此命令會將 Azure IoT DPS 服務用戶端 Maven 套件下載到您的機器，並建置範例。 此套件包含 Java 服務 SDK 的二進位檔。

  2. 切換至 target 資料夾並執行範例。 上一個步驟中的組建會以下列檔案格式輸出 target 資料夾中的 .jar 檔案：provisioning-x509-sample-{version}-with-deps.jar；例如：provisioning-x509-sample-1.8.1-with-deps.jar。 您可能需要取代下列命令中的版本。

    cd target
java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar

  3. 成功建立時，命令視窗會顯示新註冊群組的屬性。

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

  1. 在 Azure 入口網站中，瀏覽至您的裝置佈建服務執行個體。

  2. 在 [設定] 功能表中，選取 [管理註冊]。

  3. 選取 [註冊群組] 索引標籤。您應會看到與您在此範例中使用的註冊群組識別碼相對應的新註冊項目。

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

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

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

清除資源

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

  1. 在您的電腦上關閉範例輸出視窗。

  2. 從 Azure 入口網站中的左側功能表，選取 [所有資源]。

  3. 選取您的裝置佈建服務。

  4. 在左側功能表的 [設定] 底下，選取 [管理註冊]。

  5. 選取 [註冊群組] 索引標籤。

  6. 選取您在本文中所建立的註冊群組的群組名稱旁的核取方塊。

  7. 在頁面頂端，選取 [刪除]。

  8. 從 Azure 入口網站中的裝置佈建服務中，選取左側功能表上 [設定] 底下的 [憑證]。

  9. 選取您針對本文上傳的憑證。

  10. 在 [憑證詳細資料] 頂端，選取 [刪除]。

憑證工具

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

Azure IoT Node.js SDK 具有可協助您建立和管理憑證的指令碼。 若要深入了解，請參閱適用於 Node.js 的 Azure IoT 裝置佈建裝置 SDK 的工具。

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

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

下一步

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