Programowe tworzenie grupy rejestracji usługi Device Provisioning Service dla zaświadczania certyfikatów X.509

• Zainstaluj zestaw .NET 6.0 SDK na maszynie z systemem Windows. Aby sprawdzić wersję, możesz użyć następującego polecenia.

  dotnet --info
  

  Ważne

  Aby skompilować i uruchomić przykładowy kod w tym artykule, musisz użyć zestawu .NET 6.0 SDK. Przykład nie działa obecnie z nowszymi wersjami zestawu SDK.

• Zainstaluj Node.js w wersji 4.0 lub nowszej na maszynie.

• Java SE Development Kit 8. W tym artykule jest używany zestaw SDK usługi Azure IoT dla języka Java, który działa zarówno w systemach Windows, jak i Linux. W tym artykule jest używany system Windows.

• Maven 3.

W tej sekcji pokazano, jak utworzyć aplikację konsolową platformy .NET Core, która dodaje grupę rejestracji do usługi aprowizacji.

1. Otwórz wiersz polecenia systemu Windows i przejdź do folderu, w którym chcesz utworzyć aplikację.

2. Aby utworzyć projekt konsoli, uruchom następujące polecenie:

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

3. Aby dodać odwołanie do zestawu SDK usługi DPS, uruchom następujące polecenie:

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

   Ten krok pobiera, instaluje i dodaje odwołanie do pakietu NuGet klienta usługi Azure IoT DPS i jego zależności. Ten pakiet zawiera pliki binarne zestawu SDK usługi .NET.

4. Otwórz plik Program.cs w edytorze.

5. Zastąp instrukcję przestrzeni nazw w górnej części pliku następującym wierszem:

   namespace CreateEnrollmentGroup;
   

6. Dodaj następujące using instrukcje w górnej części pliku powyżej instrukcji namespace :

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

7. Dodaj następujące pola do Program klasy i wprowadź wskazane zmiany.

   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}";
   

   • Zastąp wartość symbolu ProvisioningServiceConnectionString zastępczego parametry połączenia usługi aprowizacji skopiowaną w poprzedniej sekcji.

   • Zastąp wartość symbolu X509RootCertPath zastępczego ścieżką do pliku pem lub .cer. Ten plik reprezentuje publiczną część certyfikatu X.509 głównego urzędu certyfikacji, który został wcześniej przekazany i zweryfikowany w usłudze aprowizacji, lub certyfikat pośredni, który został przekazany i zweryfikowany lub miał certyfikat w łańcuchu podpisywania przekazany i zweryfikowany.

   • Możesz opcjonalnie zmienić EnrollmentGroupId wartość. Ciąg może zawierać tylko małe litery i łączniki.

   Ważne

   W kodzie produkcyjnym pamiętaj o następujących kwestiach dotyczących zabezpieczeń:

   • Trwałe kodowanie parametrów połączenia administratora usługi aprowizacji jest niezgodne z najlepszymi rozwiązaniami dotyczącymi zabezpieczeń. Zamiast tego parametry połączenia powinny być przechowywane w sposób bezpieczny, np. w zabezpieczonym pliku konfiguracji lub rejestrze.
   • Pamiętaj, aby przekazać tylko publiczną część certyfikatu podpisywania. Nigdy nie przekazuj plików pfx (PKCS12) ani plików pem zawierających klucze prywatne do usługi aprowizacji.

8. Dodaj następującą metodę do Program klasy . Ten kod tworzy wpis, a następnie wywołuje EnrollmentGroup metodę ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync , aby dodać grupę rejestracji do usługi aprowizacji.

   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. Na koniec zastąp metodę Main następującymi wierszami:

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

10. Zapisz zmiany.

W tej sekcji pokazano, jak utworzyć skrypt Node.js, który dodaje grupę rejestracji do usługi aprowizacji.

1. Z poziomu okna polecenia w folderze roboczym uruchom następujące polecenie:

   npm install azure-iot-provisioning-service
   

   Ten krok pobiera, instaluje i dodaje odwołanie do pakietu klienta usługi Azure IoT DPS i jego zależności. Ten pakiet zawiera pliki binarne zestawu SDK usługi Node.js.

2. Za pomocą edytora tekstu utwórz plik create_enrollment_group.js w folderze roboczym. Dodaj następujący kod do pliku i zapisz go:

       '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. Otwórz wiersz polecenia systemu Windows.

2. Sklonuj repozytorium GitHub dla przykładowego kodu rejestracji urządzeń przy użyciu zestawu SDK usługi Java:

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

3. Z lokalizacji, w której pobrano repozytorium, przejdź do folderu przykładowego:

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

4. Otwórz plik /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java w wybranym edytorze.

5. Zastąp [Provisioning Connection String] wartość parametry połączenia skopiowaną w sekcji Pobierz parametry połączenia dla usługi aprowizacji.

6. Zastąp PUBLIC_KEY_CERTIFICATE_STRING ciąg stały wartością pliku certyfikatu głównego lub pośredniego urzędu .pem certyfikacji. Ten plik reprezentuje publiczną część certyfikatu X.509 głównego urzędu certyfikacji, który został wcześniej przekazany i zweryfikowany w usłudze aprowizacji, lub certyfikat pośredni, który został przekazany i zweryfikowany lub miał certyfikat w łańcuchu podpisywania przekazany i zweryfikowany.

   Składnia tekstu certyfikatu musi być zgodna z tym wzorcem bez dodatkowych spacji ani znaków:

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

   Ręczne aktualizowanie tej wartości ciągu może być podatne na błąd. Aby wygenerować właściwą składnię, możesz skopiować i wkleić następujące polecenie do wiersza polecenia powłoki Git Bash , zastąpić your-cert.pem lokalizacją pliku certyfikatu i nacisnąć ENTER. To polecenie generuje składnię stałej PUBLIC_KEY_CERTIFICATE_STRING wartości ciągu i zapisuje ją w danych wyjściowych.

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

   Skopiuj i wklej tekst wyjściowego certyfikatu dla stałej wartości.

   Ważne

   W kodzie produkcyjnym pamiętaj o następujących kwestiach dotyczących zabezpieczeń:

   • Trwałe kodowanie parametrów połączenia administratora usługi aprowizacji jest niezgodne z najlepszymi rozwiązaniami dotyczącymi zabezpieczeń. Zamiast tego parametry połączenia powinny być przechowywane w sposób bezpieczny, np. w zabezpieczonym pliku konfiguracji lub rejestrze.
   • Pamiętaj, aby przekazać tylko publiczną część certyfikatu podpisywania. Nigdy nie przekazuj plików pfx (PKCS12) ani plików pem zawierających klucze prywatne do usługi aprowizacji.

7. Przykład umożliwia ustawienie centrum IoT w grupie rejestracji w celu aprowizacji urządzenia. To centrum IoT musi być takie, które zostało wcześniej połączone z usługą aprowizacji. W tym artykule możemy wybrać usługę DPS z połączonych centrów zgodnie z domyślnymi zasadami alokacji, równomiernie ważonymi rozkładami. Oznacz następującą instrukcję w pliku jako komentarz:

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

8. Przykładowy kod tworzy, aktualizuje, wykonuje zapytania i usuwa grupę rejestracji dla urządzeń X.509. Aby zweryfikować pomyślne utworzenie grupy rejestracji w witrynie Azure Portal, oznacz jako komentarz następujące wiersze kodu na końcu pliku:

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

9. Zapisz plik ServiceEnrollmentGroupSample.java.

1. Uruchom przykład:

   dotnet run
   

2. Po pomyślnym utworzeniu w oknie polecenia zostaną wyświetlone właściwości nowej grupy rejestracji.

1. Uruchom następujące polecenie w wierszu polecenia. Uwzględnij cudzysłowy wokół argumentów polecenia i zastąp <connection string> ciąg parametrami połączenia skopiowanymi w poprzedniej sekcji oraz <certificate .pem file> ścieżką do pliku certyfikatu .pem . Ten plik reprezentuje publiczną część certyfikatu X.509 głównego urzędu certyfikacji, który został wcześniej przekazany i zweryfikowany w usłudze aprowizacji, lub certyfikat pośredni, który został przekazany i zweryfikowany lub miał certyfikat w łańcuchu podpisywania przekazany i zweryfikowany.

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

2. Po pomyślnym utworzeniu w oknie polecenia zostaną wyświetlone właściwości nowej grupy rejestracji.

1. W folderze azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample w wierszu polecenia uruchom następujące polecenie, aby skompilować przykład:

   mvn install -DskipTests
   

   To polecenie pobiera pakiet Maven klienta usługi Azure IoT DPS na maszynę i kompiluje przykład. Ten pakiet zawiera pliki binarne zestawu SDK usługi Java.

2. Przejdź do folderu docelowego i uruchom przykład. Kompilacja w poprzednim kroku zwraca .jar plik w folderze docelowym o następującym formacie pliku: provisioning-x509-sample-{version}-with-deps.jarna przykład: provisioning-x509-sample-1.8.1-with-deps.jar. Może być konieczne zastąpienie wersji w poniższym poleceniu.

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

3. Po pomyślnym utworzeniu w oknie polecenia zostaną wyświetlone właściwości nowej grupy rejestracji.

Zestaw AZURE IoT C SDK zawiera skrypty, które mogą ułatwić tworzenie certyfikatów i zarządzanie nimi. Aby dowiedzieć się więcej, zobacz Zarządzanie certyfikatami testowego urzędu certyfikacji dla przykładów i samouczków.

Zestaw SDK usługi Azure IoT Node.js zawiera skrypty, które mogą ułatwić tworzenie certyfikatów i zarządzanie nimi. Aby dowiedzieć się więcej, zobacz Tools for the Azure IoT Device Provisioning Device SDK for Node.js (Narzędzia dla zestawu SDK usługi Azure IoT Device Provisioning Device Provisioning dla Node.js).

Możesz również użyć narzędzi dostępnych w zestawie SDK języka C usługi Azure IoT. Aby dowiedzieć się więcej, zobacz Zarządzanie certyfikatami testowego urzędu certyfikacji dla przykładów i samouczków.

Zestaw SDK języka Java usługi Azure IoT zawiera narzędzia testowe, które mogą pomóc w tworzeniu certyfikatów i zarządzaniu nimi. Aby dowiedzieć się więcej, zobacz Generator certyfikatów X509 przy użyciu emulatora DICE.