Creare un gruppo di registrazione del servizio Device Provisioning a livello di codice per l'attestazione del certificato X.509

• Installare .NET 6.0 SDK o versione successiva o successiva nel computer basato su Windows. Per controllare la versione, è possibile usare il comando seguente.

  dotnet --info
  

• Installare Node.js versione 4.0 o successiva nel computer.

• Java SE Development Kit 8. Questo articolo usa Azure IoT SDK per Java, che funziona sia in Windows che in Linux. Questo articolo usa Windows.

• Maven 3.

Questa sezione illustra come creare un'applicazione console .NET Core che aggiunge un gruppo di registrazione al servizio di provisioning.

1. Aprire un prompt dei comandi di Windows e passare a una cartella in cui si vuole creare l'app.

2. Per creare un progetto console, eseguire il comando seguente:

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

3. Per aggiungere un riferimento all'SDK del servizio DPS, eseguire il comando seguente:

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

   Questo passaggio scarica, installa e aggiunge un riferimento al pacchetto NuGet del client del servizio Device Provisioning IoT di Azure e alle relative dipendenze. Questo pacchetto include i file binari per .NET Service SDK.

4. Aprire Program.cs file in un editor.

5. Sostituire l'istruzione dello spazio dei nomi all'inizio del file con la riga seguente:

   namespace CreateEnrollmentGroup;
   

6. Aggiungere le istruzioni seguenti using all'inizio del file sopra l'istruzione namespace :

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

7. Aggiungere i campi seguenti alla Program classe e apportare le modifiche indicate.

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

   • Sostituire il ProvisioningServiceConnectionString valore segnaposto con il stringa di connessione del servizio di provisioning copiato nella sezione precedente.

   • Sostituire il valore segnaposto di X509RootCertPath con il percorso di un file con estensione pem o cer. Questo file rappresenta la parte pubblica di un certificato X.509 ca radice caricato e verificato in precedenza con il servizio di provisioning oppure un certificato intermedio che è stato caricato e verificato oppure che nella catena di firma è stato caricato e verificato un certificato.

   • Facoltativamente, è possibile modificare il valore di EnrollmentGroupId. La stringa può contenere solo caratteri minuscoli e trattini.

   Importante

   Nel codice di produzione occorre tenere presenti le considerazioni seguenti sulla sicurezza:

   • L'impostazione della stringa di connessione come hardcoded per l'amministratore del servizio di provisioning non è conforme alle procedure consigliate per la sicurezza. La stringa di connessione deve essere tuttavia conservata in modo sicuro, ad esempio in un file di configurazione sicuro o nel Registro di sistema.
   • Assicurarsi di caricare solo la parte pubblica del certificato di firma. Non caricare mai nel servizio di provisioning i file PFX (PKCS12) o PEM contenenti le chiavi private.

8. Aggiungere il seguente metodo alla classe Program. Questo codice crea una EnrollmentGroup voce e quindi chiama il ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync metodo per aggiungere il gruppo di registrazione al servizio di provisioning.

   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. Sostituire infine il metodo Main con le righe seguenti:

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

10. Salva le modifiche.

Questa sezione illustra come creare uno script Node.js che aggiunge un gruppo di registrazione al servizio di provisioning.

1. In una finestra di comando della cartella di lavoro eseguire:

   npm install azure-iot-provisioning-service
   

   Questo passaggio scarica, installa e aggiunge un riferimento al pacchetto client del servizio Dps IoT di Azure e alle relative dipendenze. Questo pacchetto include i file binari per l'SDK del servizio Node.js.

2. Con un editor di testo creare un file create_enrollment_group.js nella cartella di lavoro. Aggiungere il codice seguente al file e salvare:

       '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. Aprire un prompt dei comandi di Windows.

2. Clonare il repository GitHub per l'esempio di codice di registrazione del dispositivo usando Java Service SDK:

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

3. Dal percorso in cui è stato scaricato il repository, passare alla cartella di esempio:

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

4. Aprire il file /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java in un editor di propria scelta.

5. Sostituire [Provisioning Connection String] con il stringa di connessione copiato in Ottenere il stringa di connessione per il servizio di provisioning.

6. Sostituire la PUBLIC_KEY_CERTIFICATE_STRING stringa costante con il valore del file di certificato .pem ca radice o intermedio. Questo file rappresenta la parte pubblica di un certificato X.509 ca radice caricato e verificato in precedenza con il servizio di provisioning oppure un certificato intermedio che è stato caricato e verificato oppure che nella catena di firma è stato caricato e verificato un certificato.

   La sintassi del testo del certificato deve seguire il modello seguente senza spazi o caratteri aggiuntivi.

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

   L'aggiornamento manuale di questo valore stringa può essere soggetto a errori. Per generare la sintassi corretta, è possibile copiare e incollare il comando seguente in un prompt di Git Bash , sostituire your-cert.pem con il percorso del file del certificato e premere INVIO. Questo comando genera la sintassi per il PUBLIC_KEY_CERTIFICATE_STRING valore costante stringa e la scrive nell'output.

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

   Copiare e incollare il testo del certificato di output per il valore costante.

   Importante

   Nel codice di produzione occorre tenere presenti le considerazioni seguenti sulla sicurezza:

   • L'impostazione della stringa di connessione come hardcoded per l'amministratore del servizio di provisioning non è conforme alle procedure consigliate per la sicurezza. La stringa di connessione deve essere tuttavia conservata in modo sicuro, ad esempio in un file di configurazione sicuro o nel Registro di sistema.
   • Assicurarsi di caricare solo la parte pubblica del certificato di firma. Non caricare mai nel servizio di provisioning i file PFX (PKCS12) o PEM contenenti le chiavi private.

7. L'esempio consente di impostare un hub IoT nel gruppo di registrazione in cui effettuare il provisioning del dispositivo. Deve trattarsi di un hub IoT collegato in precedenza al servizio di provisioning. Per questo articolo, è possibile scegliere dps tra gli hub collegati in base ai criteri di allocazione predefiniti, distribuzione ponderata in modo uniforme. Impostare come commento l'istruzione seguente nel file :

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

8. Il codice di esempio crea, aggiorna, esegue query ed elimina un gruppo di registrazioni per i dispositivi X.509. Per verificare la corretta creazione del gruppo di registrazione in portale di Azure, impostare come commento le righe di codice seguenti vicino alla fine del file:

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

9. Salvare il file ServiceEnrollmentGroupSample.java .

1. Eseguire l'esempio:

   dotnet run
   

2. Al termine della creazione, nella finestra di comando vengono visualizzate le proprietà del nuovo gruppo di registrazione.

1. Eseguire il comando seguente nel prompt dei comandi. Includere le virgolette relative agli argomenti del comando e sostituire <connection string> con stringa di connessione copiate nella sezione precedente e <certificate .pem file> con il percorso del file del certificato.pem. Questo file rappresenta la parte pubblica di un certificato X.509 ca radice caricato e verificato in precedenza con il servizio di provisioning oppure un certificato intermedio che è stato caricato e verificato oppure che nella catena di firma è stato caricato e verificato un certificato.

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

2. Al termine della creazione, nella finestra di comando vengono visualizzate le proprietà del nuovo gruppo di registrazione.

1. Dalla cartella azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample nel prompt dei comandi eseguire il comando seguente per compilare l'esempio:

   mvn install -DskipTests
   

   Questo comando scarica il pacchetto Maven del servizio Dps di Azure IoT nel computer e compila l'esempio. Questo pacchetto include i file binari per Java Service SDK.

2. Passare alla cartella di destinazione ed eseguire l'esempio. La compilazione nel passaggio precedente restituisce .jar file nella cartella di destinazione con il formato di file seguente: provisioning-x509-sample-{version}-with-deps.jar; ad esempio: provisioning-x509-sample-1.8.1-with-deps.jar. Potrebbe essere necessario sostituire la versione nel comando seguente.

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

3. Al termine della creazione, nella finestra di comando vengono visualizzate le proprietà del nuovo gruppo di registrazione.

Azure IoT C SDK include script che consentono di creare e gestire i certificati. Per altre informazioni, vedere Gestione dei certificati della CA di test per esempi ed esercitazioni.

Azure IoT Node.js SDK include script che consentono di creare e gestire i certificati. Per altre informazioni, vedere Strumenti per Azure IoT Device Provisioning Device SDK per Node.js.

È anche possibile usare gli strumenti disponibili in Azure IoT C SDK. Per altre informazioni, vedere Gestione dei certificati della CA di test per esempi ed esercitazioni.

Azure IoT Java SDK contiene strumenti di test che consentono di creare e gestire i certificati. Per altre informazioni, vedere Generatore di certificati X509 con l'emulatore DICE.