Programové vytvoření skupiny registrací služby Device Provisioning pro ověření certifikátu X.509

V tomto článku se dozvíte, jak programově vytvořit skupinu registrací ve službě Azure IoT Hub Device Provisioning Service (DPS), která používá zprostředkující nebo kořenové certifikáty CA X.509. Skupina registrací se vytvoří pomocí sady SDK služby Azure IoT a ukázkové aplikace. Skupina registrací řídí přístup ke službě zřizování pro zařízení, která ve svém řetězu certifikátů sdílejí společný podpisový certifikát. Další informace najdete v tématu Použití certifikátů X.509 s DPS. Další informace o používání infrastruktury veřejných klíčů (PKI) založené na certifikátech X.509 se službami Azure IoT Hub a Device Provisioning najdete v tématu Přehled zabezpečení pomocí certifikátu webu X.509.

Požadavky

• Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

• Proveďte kroky v části Nastavení služby IoT Hub Device Provisioning pomocí webu Azure Portal.

• Na počítač s Windows nainstalujte sadu .NET 6.0 SDK nebo novější nebo novější . Ke kontrole verze můžete použít následující příkaz.

  dotnet --info
  

• Nainstalujte na počítač Node.js verze 4.0 nebo novější nebo novější .

• Java SE Development Kit 8. Tento článek používá sadu Azure IoT SDK pro Javu, která funguje v systémech Windows i Linux. Tento článek používá Systém Windows.

• Maven 3.

• Nainstalujte nejnovější verzi Git. Ujistěte se, že je Git přidaný do proměnných prostředí, které jsou přístupné pro příkazové okno. Nejnovější verzi nástrojů pro instalaci, včetně Git Bashu, aplikace příkazového řádku, kterou můžete použít k interakci s místním úložištěm Git, najdete v klientských nástrojích git Gitu společnosti Software Freedom Conservancy.

Poznámka:

I když kroky v tomto článku fungují na počítačích s Windows i Linuxem, tento článek používá vývojový počítač s Windows.

Vytvoření testovacích certifikátů

Skupiny registrací, které používají ověření certifikátu X.509, je možné nakonfigurovat tak, aby používaly certifikát kořenové certifikační autority nebo zprostředkující certifikát. Obvyklým případem je konfigurace skupiny registrací pomocí zprostředkujícího certifikátu. Použití zprostředkujícího certifikátu poskytuje větší flexibilitu, protože stejný kořenový certifikát certifikační autority může vygenerovat nebo odvolat více zprostředkujících certifikátů.

Pro účely tohoto článku potřebujete buď kořenový soubor certifikátu certifikační autority, soubor certifikátu zprostředkující certifikační autority, nebo obojí ve formátu .pem nebo .cer . Jeden soubor obsahuje veřejnou část kořenového certifikátu CA X.509 a druhý obsahuje veřejnou část certifikátu X.509 zprostředkující certifikační autority X.509.

Pokud už máte kořenový soubor certifikační autority nebo zprostředkující certifikační autoritu, můžete pokračovat v přidávání a ověřování kořenového nebo zprostředkujícího certifikátu certifikační autority.

Pokud nemáte kořenový soubor certifikační autority nebo zprostředkující certifikační autoritu, postupujte podle pokynů v tématu Vytvoření řetězu certifikátů X.509 a vytvořte je. Po dokončení kroků v části Vytvoření certifikátu zprostředkující certifikační autority můžete zastavit, protože k dokončení kroků v tomto článku nepotřebujete certifikáty zařízení. Po dokončení máte dva soubory certifikátů X.509: ./certs/azure-iot-test-only.root.ca.cert.pem a ./certs/azure-iot-test-only.intermediate.cert.pem.

Přidání a ověření kořenového nebo zprostředkujícího certifikátu certifikační autority

Zařízení, která zřizují prostřednictvím skupiny registrací pomocí certifikátů X.509, prezentují při ověřování pomocí DPS celý řetěz certifikátů. Aby služba DPS mohla ověřit řetěz certifikátů, musí být kořenový nebo zprostředkující certifikát nakonfigurovaný ve skupině registrací ověřeným certifikátem nebo musí být součástí ověřeného certifikátu v řetězu certifikátů, které zařízení prezentuje při ověřování ve službě.

V tomto článku za předpokladu, že máte certifikát kořenové certifikační autority i certifikát zprostředkující certifikační autority podepsaný kořenovou certifikační autoritou:

• Pokud plánujete vytvořit skupinu registrací s kořenovým certifikátem certifikační autority, musíte nahrát a ověřit kořenový certifikát certifikační autority.

• Pokud plánujete vytvořit skupinu registrací s certifikátem zprostředkující certifikační autority, můžete nahrát a ověřit certifikát kořenové certifikační autority nebo certifikát zprostředkující certifikační autority. (Pokud máte v řetězu certifikátů více zprostředkujících certifikátů certifikační autority, můžete případně nahrát a ověřit všechny zprostředkující certifikáty, které se nacházejí mezi kořenovým certifikátem certifikační autority a zprostředkujícím certifikátem, se kterým vytvoříte skupinu registrací.)

Přidání a ověření kořenového nebo zprostředkujícího certifikátu certifikační autority do služby Device Provisioning:

1. Přihlaste se k portálu Azure.

2. V nabídce vlevo nebo na stránce portálu vyberte Všechny prostředky.

3. Vyberte službu Device Provisioning.

4. V nabídce Nastavení vyberte Certifikáty.

5. V horní nabídce vyberte + Přidat:.

6. Zadejte název kořenového nebo zprostředkujícího certifikátu certifikační autority a nahrajte soubor .pem nebo .cer .

7. Vyberte Nastavit stav certifikátu pro ověření při nahrání.

   

8. Zvolte Uložit.

Získání připojovacího řetězce pro službu zřizování

Pro ukázku v tomto článku potřebujete připojovací řetězec pro vaši službu zřizování. Pomocí následujícího postupu ho načtěte.

1. Přihlaste se k portálu Azure.

2. V nabídce vlevo nebo na stránce portálu vyberte Všechny prostředky.

3. Vyberte službu Device Provisioning.

4. V nabídce Nastavení vyberte Zásady sdíleného přístupu.

5. Vyberte zásadu přístupu, kterou chcete použít.

6. Na panelu Zásady přístupu zkopírujte a uložte primární klíč připojovací řetězec.

   

Vytvoření ukázky skupiny registrací

V této části se dozvíte, jak vytvořit konzolovou aplikaci .NET Core, která do služby zřizování přidá skupinu registrací.

1. Otevřete příkazový řádek windows a přejděte do složky, do které chcete vytvořit aplikaci.

2. Pokud chcete vytvořit projekt konzoly, spusťte následující příkaz:

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

3. Pokud chcete přidat odkaz na sadu SDK služby DPS, spusťte následující příkaz:

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

   Tento krok stáhne, nainstaluje a přidá odkaz na balíček NuGet klienta služby Azure IoT DPS a jeho závislosti. Tento balíček obsahuje binární soubory pro sadu SDK služby .NET.

4. Otevřete soubor Program.cs v editoru.

5. Nahraďte příkaz oboru názvů v horní části souboru následujícím řádkem:

   namespace CreateEnrollmentGroup;
   

6. Na začátek souboru nad namespace příkaz přidejte následující using příkazy:

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

7. Přidejte do Program třídy následující pole a proveďte uvedené změny.

   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 Nahraďte zástupnou hodnotu připojovací řetězec služby zřizování, kterou jste zkopírovali v předchozí části.

   • X509RootCertPath Nahraďte zástupnou hodnotu cestou k souboru .pem nebo .cer. Tento soubor představuje veřejnou část certifikátu X.509 kořenové certifikační autority X.509, který byl dříve nahraný a ověřený ve vaší službě zřizování, nebo zprostředkující certifikát, který byl nahraný a ověřený nebo měl certifikát v podpisovém řetězu nahraný a ověřený.

   • Volitelně můžete hodnotu změnit EnrollmentGroupId . Řetězec může obsahovat pouze malá písmena a pomlčky.

   Důležité

   V případě produkčního kódu mějte na paměti následující aspekty zabezpečení:

   • Uložení připojovacího řetězce pro správce služby zřizování v kódu je v rozporu s osvědčenými postupy zabezpečení. Místo toho by se měl připojovací řetězec uchovávat zabezpečeným způsobem, například v zabezpečeném konfiguračním souboru nebo v registru.
   • Nezapomeňte nahrát pouze veřejnou část podpisového certifikátu. Nikdy nenahrávejte soubory .pfx (PKCS12) ani .pem obsahující privátní klíče ke službě zřizování.

8. Do třídy přidejte následující metodu Program . Tento kód vytvoří EnrollmentGroup položku a potom zavolá metodu ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync pro přidání skupiny registrací do služby zřizování.

   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. Nakonec nahraďte metodu Main následujícími řádky:

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

10. Uložte provedené změny.

V této části se dozvíte, jak vytvořit Node.js skript, který do služby zřizování přidá skupinu registrací.

Tip

Pro zjednodušení tato ukázka používá ověřování SAS pro připojení k rozhraní API služby DPS. Bezpečnějším přístupem je použití přihlašovacích údajů tokenu Azure. Příklad této metody ověřování najdete v ukázce create_tpm_enrollment_with_token_credentials.js v sadě Node.js SDK.

1. Z příkazového okna ve vaší pracovní složce spusťte:

   npm install azure-iot-provisioning-service
   

   Tento krok stáhne, nainstaluje a přidá odkaz na balíček klienta služby Azure IoT DPS a jeho závislosti. Tento balíček obsahuje binární soubory pro sadu SDK služby Node.js.

2. Pomocí textového editoru ve své pracovní složce vytvořte soubor create_enrollment_group.js. Přidejte do souboru následující kód a uložte ho:

       '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. Otevřete příkazový řádek Windows.

2. Naklonujte úložiště GitHub pro vzorový kód registrace zařízení pomocí sady Java Service SDK:

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

3. Z umístění, kam jste úložiště stáhli, přejděte do ukázkové složky:

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

4. Otevřete soubor /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java v editoru podle vašeho výběru.

5. Nahraďte [Provisioning Connection String] připojovací řetězec, které jste zkopírovali v části Získat připojovací řetězec pro vaši službu zřizování.

6. PUBLIC_KEY_CERTIFICATE_STRING Nahraďte konstantní řetězec hodnotou kořenového souboru certifikátu nebo zprostředkující .pem certifikační autority. Tento soubor představuje veřejnou část certifikátu X.509 kořenové certifikační autority X.509, který byl dříve nahraný a ověřený ve vaší službě zřizování, nebo zprostředkující certifikát, který byl nahraný a ověřený nebo měl certifikát v podpisovém řetězu nahraný a ověřený.

   Syntaxe textu certifikátu musí odpovídat tomuto vzoru bez nadbytečných mezer nebo znaků:

   private static final String PUBLIC_KEY_CERTIFICATE_STRING = 
           "-----BEGIN CERTIFICATE-----\n" +
           "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
               ...
           "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
           "-----END CERTIFICATE-----";
   

   Ruční aktualizace této řetězcové hodnoty může být náchylná k chybě. Pokud chcete vygenerovat správnou syntaxi, můžete do příkazového řádku Git Bash zkopírovat a vložit následující příkaz, nahradit your-cert.pem umístěním souboru certifikátu a stisknout enter. Tento příkaz vygeneruje syntaxi řetězcové PUBLIC_KEY_CERTIFICATE_STRING konstantní hodnoty a zapíše ji do výstupu.

   sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' your-cert.pem
   

   Zkopírujte a vložte text výstupního certifikátu pro konstantní hodnotu.

   Důležité

   V případě produkčního kódu mějte na paměti následující aspekty zabezpečení:

   • Uložení připojovacího řetězce pro správce služby zřizování v kódu je v rozporu s osvědčenými postupy zabezpečení. Místo toho by se měl připojovací řetězec uchovávat zabezpečeným způsobem, například v zabezpečeném konfiguračním souboru nebo v registru.
   • Nezapomeňte nahrát pouze veřejnou část podpisového certifikátu. Nikdy nenahrávejte soubory .pfx (PKCS12) ani .pem obsahující privátní klíče ke službě zřizování.

7. Ukázka umožňuje nastavit centrum IoT ve skupině registrací pro zřízení zařízení. Musí se jednat o centrum IoT, které bylo dříve propojeno se službou zřizování. Pro účely tohoto článku necháme SLUŽBU DPS vybrat z propojených center podle výchozích zásad přidělování, rovnoměrně vážené distribuce. Zakomentujte v souboru následující příkaz:

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

8. Ukázkový kód vytvoří, aktualizuje, dotazuje a odstraní skupinu registrací pro zařízení X.509. Pokud chcete ověřit úspěšné vytvoření skupiny registrací na webu Azure Portal, zakomentujte následující řádky kódu na konci souboru:

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

9. Uložte soubor ServiceEnrollmentGroupSample.java.

Spuštění ukázky skupiny registrací

1. Spusťte ukázku:

   dotnet run
   

2. Po úspěšném vytvoření se v příkazovém okně zobrazí vlastnosti nové skupiny registrací.

1. V příkazovém řádku spusťte následující příkaz. Do argumentů příkazu zahrňte uvozovky a nahraďte <connection string> připojovací řetězec, které jste zkopírovali v předchozí části, a <certificate .pem file> cestu k souboru certifikátu.pem. Tento soubor představuje veřejnou část certifikátu X.509 kořenové certifikační autority X.509, který byl dříve nahraný a ověřený ve vaší službě zřizování, nebo zprostředkující certifikát, který byl nahraný a ověřený nebo měl certifikát v podpisovém řetězu nahraný a ověřený.

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

2. Po úspěšném vytvoření se v příkazovém okně zobrazí vlastnosti nové skupiny registrací.

1. Ve složce azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample na příkazovém řádku spusťte následující příkaz, který ukázku sestaví:

   mvn install -DskipTests
   

   Tento příkaz stáhne balíček Maven klienta služby Azure IoT DPS do počítače a sestaví ukázku. Tento balíček obsahuje binární soubory sady SDK služby Java.

2. Přepněte do cílové složky a spusťte ukázku. Sestavení v předchozím kroku vypíše .jar soubor v cílové složce s následujícím formátem souboru: provisioning-x509-sample-{version}-with-deps.jarnapříklad : provisioning-x509-sample-1.8.1-with-deps.jar. Možná budete muset nahradit verzi v následujícím příkazu.

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

3. Po úspěšném vytvoření se v příkazovém okně zobrazí vlastnosti nové skupiny registrací.

Ověření vytvoření skupiny registrací:

1. Na webu Azure Portal přejděte k vaší instanci služby Device Provisioning.

2. V nabídce Nastavení vyberte Spravovat registrace.

3. Vyberte kartu Skupiny registrací. Měla by se zobrazit nová položka registrace odpovídající ID skupiny registrace, které jste použili v ukázce.

   

Vyčištění prostředků

Pokud chcete prozkoumat kurzy služby Azure IoT Hub Device Provisioning, nevyčisťujte prostředky vytvořené v tomto článku. V opačném případě pomocí následujícího postupu odstraňte všechny prostředky vytvořené tímto článkem.

1. Zavřete okno s ukázkovým výstupem v počítači.

2. V nabídce vlevo na webu Azure Portal vyberte Všechny prostředky.

3. Vyberte službu Device Provisioning.

4. V nabídce vlevo v části Nastavení vyberte Spravovat registrace.

5. Vyberte kartu Skupiny registrací.

6. Zaškrtněte políčko vedle názvu skupiny registrace, kterou jste vytvořili v tomto článku.

7. V horní části stránky vyberte Odstranit.

8. Ve službě Device Provisioning na webu Azure Portal v části Nastavení v nabídce vlevo vyberte Certifikáty.

9. Vyberte certifikát, který jste nahráli pro tento článek.

10. V horní části podrobností o certifikátu vyberte Odstranit.

Nástroje pro certifikáty

Sada Azure IoT C SDK obsahuje skripty, které vám pomůžou vytvářet a spravovat certifikáty. Další informace najdete v tématu Správa certifikátů testovací certifikační autority pro ukázky a kurzy.

Sada Azure IoT Node.js SDK obsahuje skripty, které vám pomůžou vytvářet a spravovat certifikáty. Další informace najdete v tématu Nástroje pro sadu SDK pro zařízení Azure IoT Device Provisioning pro Node.js.

Můžete také použít nástroje dostupné v sadě Azure IoT C SDK. Další informace najdete v tématu Správa certifikátů testovací certifikační autority pro ukázky a kurzy.

Sada Azure IoT Java SDK obsahuje testovací nástroje, které vám pomůžou vytvářet a spravovat certifikáty. Další informace najdete v tématu Generátor certifikátů X509 pomocí emulátoru DICE.

Další kroky

V tomto článku jste vytvořili skupinu registrací pro certifikát Zprostředkující nebo kořenové certifikační autority X.509 pomocí služby Azure IoT Hub Device Provisioning. Pokud chcete prozkoumat další informace, podívejte se na následující odkazy:

• Další informace o ověření certifikátu X.509 pomocí DPS najdete v tématu Ověření certifikátu X.509.

• Kompletní příklad zřizování zařízení prostřednictvím skupiny registrací pomocí certifikátů X.509 najdete v kurzu Zřízení více zařízení X.509 pomocí skupin registrací.

• Informace o správě jednotlivých registrací a skupin registrací pomocí webu Azure Portal najdete v tématu Správa registrací zařízení pomocí webu Azure Portal.