Créer par programmation un groupe d’inscription du service Device Provisioning pour une attestation de certificat X.509

Cet article explique comment créer par programmation un groupe d’inscription qui utilise des certificats X.509 d’autorité de certification racine ou intermédiaire. Le groupe d’inscription est créé à l’aide du Kit de développement logiciel (SDK) de service Azure IoT Hub Device Provisioning (DPS) et d’un échantillon d’application. Un groupe d’inscription contrôle l’accès au service d’approvisionnement pour les appareils qui partagent un certificat de signature commun dans leur chaîne de certificats. Pour plus d’informations, consultez Contrôler l’accès aux appareils avec des certificats X.509. Pour plus d’informations sur l’utilisation d’une infrastructure de clé publique (PKI) basée sur le certificat X.509 avec Azure IoT Hub et le service Device Provisioning, consultez Vue d’ensemble d’un certificat d’autorité de certification X.509.

Prérequis

• Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

• Effectuez les étapes décrites dans Configurer le service IoT Hub Device Provisioning avec le portail Azure.

• Installez le kit SDK .NET 6.0 ou une version ultérieure sur votre machine Windows. Vous pouvez exécuter la commande suivante pour vérifier votre version.

  dotnet --info
  

• Installez Node.js v4.0 ou une version ultérieure sur votre machine.

• Java SE Development Kit 8. Cet article utilise le Kit de développement logiciel (SDK) Azure IoT pour Java, qui fonctionne à la fois sur Windows et sur Linux. Cet article utilise Windows.

• Maven 3.

• Installez la dernière version de Git. Vérifiez que Git est ajouté aux variables d’environnement accessibles à la fenêtre de commande. Consultez Outils clients Git de Software Freedom Conservancy pour accéder à la dernière version des outils git à installer, ce qui inclut Git Bash, l’application en ligne de commande que vous pouvez utiliser pour interagir avec votre dépôt Git local.

Remarque

Bien que les étapes de cet article fonctionnent à la fois sur des ordinateurs Windows et Linux, il utilise un ordinateur de développement Windows.

Créer des certificats de test

Des groupes d’inscription utilisant une attestation de certificat X.509 peuvent être configurés pour utiliser un certificat d’autorité de certification racine ou un certificat intermédiaire. Le cas le plus habituel consiste à configurer le groupe d’inscription avec un certificat intermédiaire. L’utilisation d’un certificat intermédiaire offre une plus grande flexibilité, car plusieurs certificats intermédiaires peuvent être générés ou révoqués par le même certificat d’autorité de certification racine.

Pour cet article, vous avez besoin d’un fichier de certificat d’autorité de certification racine, d’un fichier de certificat d’autorité de certification intermédiaire, ou des deux au format .pem ou .cer. Un fichier contient la partie publique du certificat X.509 de l’autorité de certification racine, et l’autre la partie publique du certificat X.509 de l’autorité de certification intermédiaire.

Si vous disposez déjà d’un fichier d’autorité de certification racine et/ou d’autorité de certification intermédiaire, vous pouvez aller à la section Ajouter et vérifier votre certificat d’autorité de certification racine ou intermédiaire.

Si vous n’avez pas de fichier d’autorité de certification racine et/ou intermédiaire, suivez les étapes décrites dans Créer une chaîne de certificats X.509 pour les créer. Vous pouvez arrêter après avoir effectué les étapes décrites dans Créer le certificat d’autorité de certification intermédiaire, car vous n’avez pas besoin de certificats d’appareil pour effectuer les étapes décrites dans cet article. Quand vous avez terminé, vous disposez de deux fichiers de certificat X.509 : ./certs/azure-iot-test-only.root.ca.cert.pem et ./certs/azure-iot-test-only.intermediate.cert.pem.

Ajouter et vérifier votre certificat d’autorité de certification racine ou intermédiaire

Les appareils approvisionnés via un groupe d’inscription à l’aide de certificats X.509 présentent la chaîne de certificats entière lorsqu’ils s’authentifient auprès du DPS. Pour que le DPS puisse valider la chaîne de certificats, le certificat racine ou intermédiaire configuré dans un groupe d’inscription doit être un certificat vérifié ou être associé à un certificat vérifié dans la chaîne d’approbation présentée par un appareil lors de son authentification auprès du service.

Pour cet article, en supposant que vous disposez à la fois d’un certificat d’autorité de certification racine et d’un certificat d’autorité de certification intermédiaire signé par l’autorité de certification racine :

• Si vous prévoyez de créer le groupe d’inscription avec le certificat d’autorité de certification racine, vous devez charger et vérifier celui-ci.

• Si vous prévoyez de créer le groupe d’inscription avec le certificat d’autorité de certification intermédiaire, vous pouvez charger et vérifier tant le certificat d’autorité de certification racine que le certificat d’autorité de certification intermédiaire (si vous avez plusieurs certificats d’autorité de certification intermédiaires dans la chaîne de certificats, vous pouvez également charger et vérifier tout certificat intermédiaire se trouvant entre le certificat d’autorité de certification racine et le certificat intermédiaire avec lequel vous créez le groupe d’inscription).

Pour ajouter et vérifier votre certificat d’autorité de certification racine ou intermédiaire sur le service Device Provisioning :

1. Connectez-vous au portail Azure.

2. Dans le menu de gauche ou dans la page du portail, sélectionnez Toutes les ressources.

3. Sélectionnez votre service Device Provisioning.

4. Dans le menu Paramètres, sélectionnez Certificats.

5. Dans le menu du haut, sélectionnez + Ajouter.

6. Entrez un nom pour votre certificat d’autorité de certification racine ou intermédiaire, puis chargez le fichier .pem ou .cer .

7. Sélectionnez Définir l’état du certificat sur Vérifié lors du chargement.

   

8. Sélectionnez Enregistrer.

Obtenir la chaîne de connexion de votre service d’approvisionnement

Pour l’exemple de cet article, vous avez besoin de la chaîne de connexion pour votre service de provisionnement. Utilisez les étapes suivantes pour la récupérer.

1. Connectez-vous au portail Azure.

2. Dans le menu de gauche ou dans la page du portail, sélectionnez Toutes les ressources.

3. Sélectionnez votre service Device Provisioning.

4. Dans le menu Paramètres, sélectionnez Stratégies d’accès partagées.

5. Sélectionnez la stratégie d’accès que vous souhaitez utiliser.

6. Dans le panneau Stratégie d’accès, copiez et enregistrez la chaîne de connexion de la clé primaire.

   

Créer un exemple de groupe d’inscription

Cette section vous montre comment créer une application console .NET Core qui ajoute un groupe d’inscriptions à votre service de provisionnement.

1. Ouvrez une invite de commandes Windows et naviguez jusqu’au dossier dans lequel vous souhaitez créer votre application.

2. Pour créer un projet de console, exécutez la commande suivante :

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

3. Pour ajouter une référence au kit de développement logiciel (SDK) du service DPS, exécutez la commande suivante :

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

   Cette étape lance le téléchargement et l’installation et ajoute une référence au package NuGet client du service Azure IoT DPS et ses dépendances. Ce package inclut les fichiers binaires du kit de développement logiciel (SDK) du service .NET.

4. Ouvrez le fichier Program.cs dans un éditeur.

5. Remplacez l’instruction de l’espace de noms en haut du fichier par la ligne suivante :

   namespace CreateEnrollmentGroup;
   

6. Ajoutez les instructions using suivantes au début du fichier au-dessus de l’instruction namespace.

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

7. Ajoutez les champs suivants à la classe Program et apportez les modifications indiquées.

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

   • Remplacez la valeur de l’espace réservé ProvisioningServiceConnectionString par la chaîne de connexion du service de provisionnement que vous avez copiée dans la section précédente.

   • Remplacez la valeur de l’espace réservé X509RootCertPath par le chemin d’un fichier .pem ou .cer. Ce fichier représente la partie publique d’un certificat X.509 d’autorité de certification racine précédemment chargé et vérifié avec votre service d’approvisionnement, ou un certificat intermédiaire qui a lui-même été chargé et vérifié ou qui avait dans sa chaîne de signature un certificat chargé et vérifié.

   • Si vous le souhaitez, vous pouvez changer la valeur de EnrollmentGroupId. La chaîne peut contenir uniquement des minuscules et des traits d’union.

   Important

   Dans le code de production, gardez à l’esprit les considérations de sécurité suivantes :

   • Le fait de coder de manière irréversible la chaîne de connexion pour l’administrateur de service d’approvisionnement est contraire aux meilleures pratiques de sécurité. Au lieu de cela, la chaîne de connexion doit conservée de manière sécurisée, par exemple dans un fichier de configuration sécurisé ou dans le registre.
   • Veillez à télécharger uniquement la partie publique du certificat de signature. Ne téléchargez jamais les fichiers .pfx (PKCS12) ou .pem contenant des clés privées vers le service d’approvisionnement.

8. Ajoutez la méthode suivante à la classe Program. Ce code crée une entrée EnrollmentGroup, puis appelle la méthode ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync pour ajouter le groupe d’inscription au service d’approvisionnement.

   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. Enfin, remplacez la méthode Main par les lignes suivantes :

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

10. Enregistrez vos modifications.

Cette section vous montre comment créer un script Node.js qui ajoute un groupe d’inscriptions à votre service de provisionnement.

1. À partir d’une fenêtre de commande dans votre dossier de travail, exécutez :

   npm install azure-iot-provisioning-service
   

   Cette étape lance le téléchargement et l’installation et ajoute une référence au package client du service Azure IoT DPS et ses dépendances. Ce package inclut les fichiers binaires du kit de développement logiciel (SDK) du service Node.js.

2. À l’aide d’un éditeur de texte, créez un fichier create_enrollment_group.js dans votre dossier de travail. Ajoutez le code suivant au fichier et enregistrez-le :

       '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. Ouvrez une invite de commandes Windows.

2. Clonez le dépôt GitHub pour l’exemple de code d’inscription d’appareil à l’aide du kit Java Service SDK :

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

3. À partir de l’emplacement où vous avez téléchargé le référentiel, accédez à l’échantillon de dossier :

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

4. Ouvrez le fichier /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java dans l’éditeur de votre choix.

5. Remplacez [Provisioning Connection String] par la chaîne de connexion que vous avez copiée dans Obtenir la chaîne de connexion de votre service de provisionnement.

6. Remplacez la chaîne constante PUBLIC_KEY_CERTIFICATE_STRING par la valeur de votre fichier .pem de certificat d’autorité de certification racine ou intermédiaire. Ce fichier représente la partie publique d’un certificat X.509 d’autorité de certification racine précédemment chargé et vérifié avec votre service d’approvisionnement, ou un certificat intermédiaire qui a lui-même été chargé et vérifié ou qui avait dans sa chaîne de signature un certificat chargé et vérifié.

   La syntaxe du texte du certificat doit suivre le modèle ci-dessous, sans espace ni caractère supplémentaire.

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

   La mise à jour manuelle de cette valeur de chaîne peut être sujette à des erreurs. Pour générer la syntaxe appropriée, vous pouvez copier et coller la commande suivante dans votre invite Git Bash, remplacer your-cert.pem par l’emplacement de votre fichier de certificat, puis appuyer sur Entrée. Cette commande génère la syntaxe de la valeur de constante de chaîne PUBLIC_KEY_CERTIFICATE_STRING et l’écrit dans la sortie.

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

   Copiez et collez le texte du certificat de sortie pour la valeur de constante.

   Important

   Dans le code de production, gardez à l’esprit les considérations de sécurité suivantes :

   • Le fait de coder de manière irréversible la chaîne de connexion pour l’administrateur de service d’approvisionnement est contraire aux meilleures pratiques de sécurité. Au lieu de cela, la chaîne de connexion doit conservée de manière sécurisée, par exemple dans un fichier de configuration sécurisé ou dans le registre.
   • Veillez à télécharger uniquement la partie publique du certificat de signature. Ne téléchargez jamais les fichiers .pfx (PKCS12) ou .pem contenant des clés privées vers le service d’approvisionnement.

7. Cet exemple vous permet de définir dans le groupe d’inscription un hub IoT auquel approvisionner l’appareil. Le hub IoT doit avoir été précédemment lié au service d’approvisionnement. Pour cet article, nous laissons DPS choisir parmi les hubs liés en fonction de la stratégie d’allocation par défaut, la distribution uniformément pondérée. Dans le fichier, commentez l’instruction suivante :

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

8. L’exemple de code crée, met à jour, interroge et supprime un groupe d’inscription pour des appareils X.509. Pour vérifier que la création du groupe d’inscription dans le portail Azure a réussi, commentez les lignes de code suivantes vers la fin du fichier :

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

9. Enregistrez le fichier ServiceEnrollmentGroupSample.java.

Exécuter l’exemple de groupe d’inscription

1. Exécutez l’exemple :

   dotnet run
   

2. Une fois la création réussie, la fenêtre de commande affiche les propriétés du nouveau groupe d’inscriptions.

1. Dans l’invite de commandes, exécutez la commande suivante. Mettez les arguments de commande entre guillemets, et remplacez <connection string> par la chaîne de connexion que vous avez copiée dans la section précédente, et <certificate .pem file> par le chemin de votre fichier .pem de certificat. Ce fichier représente la partie publique d’un certificat X.509 d’autorité de certification racine précédemment chargé et vérifié avec votre service d’approvisionnement, ou un certificat intermédiaire qui a lui-même été chargé et vérifié ou qui avait dans sa chaîne de signature un certificat chargé et vérifié.

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

2. Une fois la création réussie, la fenêtre de commande affiche les propriétés du nouveau groupe d’inscriptions.

1. À partir du dossier azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample, dans votre invite de commandes, exécutez la commande suivante pour générer l’exemple :

   mvn install -DskipTests
   

   Cette commande télécharge le package Maven client du service Azure IoT DPS sur votre machine et génère l’exemple. Ce package inclut les fichiers binaires du kit Java Service SDK.

2. Basculez vers le dossier cible et exécutez l’exemple. La build de l’étape précédente produit un fichier .jar dans le dossier cible avec le format de fichier suivant : provisioning-x509-sample-{version}-with-deps.jar ; par exemple : provisioning-x509-sample-1.8.1-with-deps.jar. Vous devrez peut-être remplacer la version dans la commande ci-dessous.

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

3. Une fois la création réussie, la fenêtre de commande affiche les propriétés du nouveau groupe d’inscriptions.

Pour vérifier que le groupe d’inscription a bien été créé :

1. Dans le portail Azure, accédez à l’instance de Device Provisioning Service.

2. Dans le menu Paramètres, sélectionnez Gérer les inscriptions.

3. Sélectionnez l’onglet Groupes d’inscriptions. Vous devriez voir une nouvelle entrée d’inscription correspondant à l’ID de groupe d’inscription que vous avez utilisé dans l’exemple.

Nettoyer les ressources

Si vous envisagez d’explorer les tutoriels relatifs au service Azure IoT Hub Device Provisioning, ne nettoyez pas les ressources créées dans cet article. Sinon, utilisez les étapes suivantes pour supprimer toutes les ressources créées par cet article.

1. Fermez la fenêtre de sortie de l’exemple sur votre ordinateur.

2. Dans le menu de gauche du portail Azure, sélectionnez Toutes les ressources.

3. Sélectionnez votre service Device Provisioning.

4. Dans le menu de gauche, sous Paramètres, sélectionnez Gérer les inscriptions.

5. Sélectionnez l’onglet Groupes d’inscriptions.

6. Cochez la case en regard du nom de groupe du groupe d’inscription que vous avez créé dans cet article.

7. En haut de la page, sélectionnez Supprimer.

8. À partir de votre service Device Provisioning dans le portail Azure, dans le menu à gauche, sous Paramètres, sélectionnez Certificats.

9. Sélectionnez le certificat que vous avez chargé pour cet article.

10. En haut du volet Détails du certificat, sélectionnez Supprimer.

Outils de certificat

Le Kit de développement logiciel (SDK) C Azure IoT a des scripts qui peuvent vous aider à créer et gérer les certificats. Pour plus d’informations, consultez Gestion de certificats d’autorité de certification de test pour des exemples et tutoriels.

Le Kit de développement logiciel (SDK) Node.js Azure IoT a des scripts qui peuvent vous aider à créer et gérer les certificats. Pour plus d’informations, consultez Outils pour le kit de développement logiciel (SDK) d’appareil Azure IoT Device Provisioning pour Node.js.

Vous pouvez également utiliser les outils disponibles dans le Kit de développement logiciel (SDK) Azure IoT C. Pour plus d’informations, consultez Gestion de certificats d’autorité de certification de test pour des exemples et tutoriels.

Le Kit de développement logiciel (SDK) Java Azure IoT contient des outils de test qui peuvent vous aider à créer et à gérer les certificats. Pour plus d’informations, consultez Générateur de certificats X509 utilisant un émulateur DICE.

Étapes suivantes

Dans le cadre de cet article, vous avez créé un groupe d’inscription pour un certificat X.509 d’autorité de certification racine ou intermédiaire en utilisant le service Azure IoT Hub Device Provisioning. Pour en savoir plus, consultez les liens suivants :

• Pour plus d’informations sur l’attestation de certificat X.509 avec le DPS, consultez Attestation de certificat X.509.

• Pour obtenir un exemple de bout en bout d’approvisionnement d’appareils via un groupe d’inscription en utilisant des certificats X.509, consultez le tutoriel Approvisionner plusieurs appareils X.509 à l’aide de groupes d’inscriptions.

• Pour en savoir plus sur la gestion des inscriptions individuelles et des groupes d’inscriptions à l’aide du portail Azure, consultez Guide pratique pour gérer les inscriptions d’appareils avec le portail Azure.