Programmgesteuertes Erstellen einer Device Provisioning Service-Registrierungsgruppe für den X.509-Zertifikatnachweis

• Installieren Sie .NET 6.0 SDK auf Ihrem Windows-basierten Computer. Sie können den folgenden Befehl ausführen, um Ihre Version zu überprüfen:

  dotnet --info
  

  Wichtig

  Sie müssen das .NET 6.0 SDK verwenden, um den Beispielcode in diesem Artikel zu erstellen und auszuführen. Das Beispiel funktioniert derzeit nicht mit späteren Versionen des SDK.

• Installieren Sie Node.js v4.0 oder höher auf Ihrem Computer.

• Java SE Development Kit 8 In diesem Artikel wird das Azure IoT SDK für Javaverwendet, das sowohl unter Windows als auch unter Linux funktioniert. In diesem Artikel wird Windows verwendet.

• Maven 3.

Dieser Abschnitt zeigt, wie Sie eine .NET Core-Konsolenanwendung erstellen, die Ihrem Bereitstellungsdienst eine Registrierungsgruppe hinzufügt.

1. Öffnen Sie eine Windows-Eingabeaufforderung, und navigieren Sie zu dem Ordner, in dem Sie Ihre App erstellen möchten.

2. Führen Sie den folgenden Befehl zum Erstellen eines Konsolenprojekts aus:

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

3. Führen Sie den folgenden Befehl aus, um einen Verweis auf das DPS-Dienst-SDK hinzuzufügen:

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

   In diesem Schritt wird das NuGet-Paket „Azure IoT-DPS-Dienstclient“ heruntergeladen und installiert sowie ein Verweis auf das Paket und dessen Abhängigkeiten hinzugefügt. Dieses Paket enthält die Binärdateien für das .NET-Dienst-SDK.

4. Öffnen Sie die Datei Program.cs in einem Editor.

5. Ersetzen Sie die Namespace-Anweisung am Anfang der Datei durch Folgendes:

   namespace CreateEnrollmentGroup;
   

6. Fügen Sie am Anfang der Datei using der -Anweisung die folgenden namespace-Anweisungen hinzu:

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

7. Fügen Sie der Klasse Program die folgenden Felder hinzu, und nehmen Sie die angegebenen Änderungen vor.

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

   • Ersetzen Sie den Platzhalterwert ProvisioningServiceConnectionString durch die Verbindungszeichenfolge des Bereitstellungsdiensts, die Sie im vorherigen Abschnitt kopiert haben.

   • Ersetzen Sie den Platzhalterwert X509RootCertPath durch den Pfad zu einer PEM- oder CER-Datei. Diese Datei stellt den öffentlichen Teil eines X.509-Zertifikats der Stammzertifizierungsstelle, das zuvor hochgeladen und mit Ihrem Bereitstellungsdienst überprüft wurde, oder ein Zwischenzertifikat dar, das selbst hochgeladen und überprüft wurde oder aber dafür sorgte, dass ein Zertifikat in seiner Signaturkette hochgeladen und überprüft wurde.

   • Sie können optional auch den Wert EnrollmentGroupId ändern. Die Zeichenfolge darf nur Kleinbuchstaben und Bindestriche enthalten.

   Wichtig

   Beachten Sie bei Produktionscode die folgenden Sicherheitshinweise:

   • Die Hartcodierung der Verbindungszeichenfolge für den Bereitstellungsdienstadministrator verstößt gegen die bewährten Methoden für die Sicherheit. Stattdessen sollte die Verbindungszeichenfolge sicher gespeichert werden, etwa in einer sicheren Konfigurationsdatei oder in der Registrierung.
   • Achten Sie darauf, dass nur der öffentliche Teil des Signaturzertifikats hochgeladen wird. Laden Sie nie PFX-Dateien (PKCS12) oder PEM-Dateien mit privaten Schlüsseln in den Bereitstellungsdienst hoch.

8. Füge der Program-Klasse die folgende Methode hinzu. Dieser Code erstellt einen EnrollmentGroup-Eintrag und ruft dann die Methode ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync auf, um die Registrierungsgruppe dem Bereitstellungsdienst hinzuzufügen.

   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. Ersetzen Sie schließlich die Methode Main durch die folgenden Zeilen:

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

10. Speichern Sie die Änderungen.

Dieser Abschnitt zeigt, wie Sie ein Node.js-Skript erstellen, das Ihrem Bereitstellungsdienst eine Registrierungsgruppe hinzufügt.

1. Führen Sie in einem Befehlsfenster in Ihrem Arbeitsordner Folgendes aus:

   npm install azure-iot-provisioning-service
   

   In diesem Schritt wird das Paket „Azure IoT-DPS-Dienstclient“ heruntergeladen und installiert sowie ein Verweis auf das Paket und dessen Abhängigkeiten hinzugefügt. Dieses Paket enthält die Binärdateien für das Node.js-Dienst-SDK.

2. Erstellen Sie mit einem Text-Editor in Ihrem Arbeitsordner die Datei create_enrollment_group.js. Fügen Sie der Datei den folgenden Code hinzu, und speichern Sie sie:

       '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. Öffnen Sie eine Windows-Eingabeaufforderung.

2. Klonen Sie das GitHub-Repository für das Codebeispiel zur Geräteregistrierung, indem Sie das Java Service SDK verwenden:

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

3. Wechseln Sie von dem Speicherort, an den Sie das Repository heruntergeladen haben, zum Beispielordner:

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

4. Öffnen Sie die Datei /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java in einem Editor Ihrer Wahl.

5. Ersetzen Sie [Provisioning Connection String] durch die Verbindungszeichenfolge, die Sie unter Abrufen der Verbindungszeichenfolge für Ihren Bereitstellungsdienst kopiert haben.

6. Ersetzen Sie die Konstantenzeichenfolge PUBLIC_KEY_CERTIFICATE_STRING durch den Wert Ihrer .pem-Zertifikatdatei der Stamm- oder Zwischenzertifizierungsstelle. Diese Datei stellt den öffentlichen Teil eines X.509-Zertifikats der Stammzertifizierungsstelle, das zuvor hochgeladen und mit Ihrem Bereitstellungsdienst überprüft wurde, oder ein Zwischenzertifikat dar, das selbst hochgeladen und überprüft wurde oder aber dafür sorgte, dass ein Zertifikat in seiner Signaturkette hochgeladen und überprüft wurde.

   Die Syntax des Zertifikattexts muss diesem Muster (ohne zusätzliche Leerstellen oder Zeichen) entsprechen:

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

   Das manuelle Aktualisieren dieses Zeichenfolgenwerts kann fehleranfällig sein. Zum Generieren der richtigen Syntax können Sie den folgenden Befehl kopieren und in eine Git Bash-Eingabeaufforderung einfügen, dann your-cert.pem durch den Speicherort Ihrer Zertifikatdatei ersetzen und die EINGABETASTE drücken. Dieser Befehl generiert die Syntax für den Wert der Zeichenfolgenkonstante PUBLIC_KEY_CERTIFICATE_STRING und schreibt sie in die Ausgabe.

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

   Kopieren Sie den ausgegebenen Zertifikattext für den konstanten Wert, und fügen Sie ihn ein.

   Wichtig

   Beachten Sie bei Produktionscode die folgenden Sicherheitshinweise:

   • Die Hartcodierung der Verbindungszeichenfolge für den Bereitstellungsdienstadministrator verstößt gegen die bewährten Methoden für die Sicherheit. Stattdessen sollte die Verbindungszeichenfolge sicher gespeichert werden, etwa in einer sicheren Konfigurationsdatei oder in der Registrierung.
   • Achten Sie darauf, dass nur der öffentliche Teil des Signaturzertifikats hochgeladen wird. Laden Sie nie PFX-Dateien (PKCS12) oder PEM-Dateien mit privaten Schlüsseln in den Bereitstellungsdienst hoch.

7. Im Beispiel können Sie einen IoT-Hub in der Registrierungsgruppe festlegen, um dafür das Gerät bereitzustellen. Dieser IoT-Hub muss einer sein, der zuvor mit dem Bereitstellungsdienst verknüpft war. Für diesen Artikel kann DPS aus den verknüpften Hubs entsprechend der Standardzuordnungsrichtlinie in gleichmäßig gewichteter Verteilung auswählen. Kommentieren Sie in der Datei die folgende Anweisung aus:

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

8. Der Beispielcode erstellt und aktualisiert eine Registrierungsgruppe für X.509-Geräte, fragt sie ab und löscht sie. Um die erfolgreiche Erstellung der Registrierungsgruppe im Azure-Portal zu überprüfen, kommentieren Sie die folgenden Codezeilen nahe am Ende der Datei aus:

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

9. Speichern Sie die Datei ServiceEnrollmentGroupSample.java.

1. Führen Sie das Beispiel aus:

   dotnet run
   

2. Bei erfolgreicher Erstellung werden im Befehlsfenster die Eigenschaften der neuen Registrierungsgruppe angezeigt.

1. Führen Sie in Ihrer Eingabeaufforderung den folgenden Befehl aus. Fügen Sie die Anführungszeichen um die Befehlsargumente ein, und ersetzen Sie <connection string> mit der im vorherigen Abschnitt kopierten Verbindungszeichenfolge und <certificate .pem file> mit dem Pfad zu Ihrer Zertifikatdatei .pem. Diese Datei stellt den öffentlichen Teil eines X.509-Zertifikats der Stammzertifizierungsstelle, das zuvor hochgeladen und mit Ihrem Bereitstellungsdienst überprüft wurde, oder ein Zwischenzertifikat dar, das selbst hochgeladen und überprüft wurde oder aber dafür sorgte, dass ein Zertifikat in seiner Signaturkette hochgeladen und überprüft wurde.

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

2. Bei erfolgreicher Erstellung werden im Befehlsfenster die Eigenschaften der neuen Registrierungsgruppe angezeigt.

1. Führen Sie in Ihrer Eingabeaufforderung aus dem Ordner azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample den folgenden Befehl zum Erstellen des Beispiels aus:

   mvn install -DskipTests
   

   Dieser Befehl lädt das Maven-Paket „Azure IoT DPS-Dienstclient“ auf Ihren Computer herunter und erstellt das Beispiel. Dieses Paket enthält die Binärdateien für das Java-Dienst-SDK.

2. Wechseln Sie zum Zielordner, und führen Sie das Beispiel aus. Beachten Sie, dass der Build im vorhergehenden Schritt die JAR-Datei im Zielordner mit dem folgenden Dateiformat ausgibt: provisioning-x509-sample-{version}-with-deps.jar; Beispiel: provisioning-x509-sample-1.8.1-with-deps.jar. Möglicherweise müssen Sie im folgenden Befehl die Version ersetzen.

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

3. Bei erfolgreicher Erstellung werden im Befehlsfenster die Eigenschaften der neuen Registrierungsgruppe angezeigt.

Das Azure IoT C SDK verfügt über Skripts, mit denen Sie Zertifikate erstellen und verwalten können. Weitere Informationen finden Sie unter Verwalten von Zertifikaten von Testzertifizierungsstellen für Beispiele und Tutorials.

Das Azure IoT Node.js SDK verfügt über Skripts, mit denen Sie Zertifikate erstellen und verwalten können. Weitere Informationen finden Sie unter Tools für das Azure IoT Device Provisioning-Geräte-SDK für Node.js.

Sie können auch Tools verwenden, die im Azure IoT C-SDK verfügbar sind. Weitere Informationen finden Sie unter Verwalten von Zertifikaten von Testzertifizierungsstellen für Beispiele und Tutorials.

Das Azure IoT Java SDK enthält Testtools, mit denen Sie Zertifikate erstellen und verwalten können. Weitere Informationen finden Sie unter X509-Zertifikatgenerator mithilfe des DICE-Emulators.