Delen via

Programmatisch een Device Provisioning Service-inschrijvingsgroep maken voor X.509-certificaatverklaring

  • Artikel

In dit artikel leest u hoe u programmatisch een inschrijvingsgroep maakt in Azure IoT Hub Device Provisioning Service (DPS) die gebruikmaakt van tussenliggende of basis-CA X.509-certificaten. De inschrijvingsgroep wordt gemaakt met behulp van de Azure IoT-service-SDK en een voorbeeldtoepassing. Een registratiegroep beheert de toegang tot de inrichtingsservice voor apparaten die een gemeenschappelijk handtekeningcertificaat in hun certificaatketen delen. Zie X.509-certificaten gebruiken met DPS voor meer informatie. Zie Overzicht van beveiliging op basis van X.509-CA-certificaten voor meer informatie over het gebruik vanop X.509-certificaten gebaseerde Public Key Infrastructure (PKI) met Azure IoT Hub en Device Provisioning Service.

Vereisten

  • Installeer de meest recente versie van Git. Zorg ervoor dat Git is toegevoegd aan de omgevingsvariabelen die toegankelijk zijn voor het opdrachtvenster. Zie de Git-clienthulpprogramma's van Software Freedom Conservancy voor de nieuwste versie van git hulpprogramma's die u kunt installeren, waaronder Git Bash, de opdrachtregel-app die u kunt gebruiken om te communiceren met uw lokale Git-opslagplaats.

Notitie

Hoewel de stappen in dit artikel zowel op Windows- als op Linux-computers werken, gebruiken we in dit artikel een Windows-ontwikkelcomputer.

Testcertificaten maken

Inschrijvingsgroepen die gebruikmaken van X.509-certificaatverklaring kunnen worden geconfigureerd voor het gebruik van een basis-CA-certificaat of een tussenliggend certificaat. Hoe gebruikelijker is het configureren van de inschrijvingsgroep met een tussenliggend certificaat. Het gebruik van een tussenliggend certificaat biedt meer flexibiliteit omdat meerdere tussenliggende certificaten kunnen worden gegenereerd of ingetrokken door hetzelfde basis-CA-certificaat.

Voor dit artikel hebt u een basis-CA-certificaatbestand, een tussenliggend CA-certificaatbestand of beide in PEM - of .cer-indeling nodig. Eén bestand bevat het openbare gedeelte van het basis-CA X.509-certificaat en het andere bevat het openbare gedeelte van het tussenliggende CA X.509-certificaat.

Als u al een basis-CA-bestand en/of een tussenliggend CA-bestand hebt, kunt u doorgaan met het toevoegen en verifiëren van uw basis- of tussenliggende CA-certificaat.

Als u geen basis-CA-bestand en/of een tussenliggend CA-bestand hebt, volgt u de stappen in Een X.509-certificaatketen maken om deze te maken. U kunt stoppen nadat u de stappen in Het tussenliggende CA-certificaat maken hebt voltooid, omdat u geen apparaatcertificaten nodig hebt om de stappen in dit artikel uit te voeren. Wanneer u klaar bent, hebt u twee X.509-certificaatbestanden: ./certs/azure-iot-test-only.root.ca.cert.pem en ./certs/azure-iot-test-only.intermediate.cert.pem.

Uw basis- of tussenliggende CA-certificaat toevoegen en verifiëren

Apparaten die worden ingericht via een inschrijvingsgroep met X.509-certificaten, presenteren de volledige certificaatketen wanneer ze worden geverifieerd met DPS. Als DPS de certificaatketen kan valideren, moet het basis- of tussencertificaat dat is geconfigureerd in een inschrijvingsgroep, een geverifieerd certificaat zijn of moeten ze samenvouwen tot een geverifieerd certificaat in de certificaatketen dat een apparaat presenteert wanneer het wordt geverifieerd met de service.

In dit artikel wordt ervan uitgegaan dat u zowel een basis-CA-certificaat als een tussenliggend CA-certificaat hebt ondertekend door de basis-CA:

  • Als u van plan bent om de inschrijvingsgroep te maken met het basis-CA-certificaat, moet u het basis-CA-certificaat uploaden en verifiëren.

  • Als u van plan bent om de inschrijvingsgroep te maken met het tussenliggende CA-certificaat, kunt u het basis-CA-certificaat of het tussenliggende CA-certificaat uploaden en verifiëren. (Als u meerdere tussenliggende CA-certificaten in de certificaatketen hebt, kunt u ook een tussenliggend certificaat uploaden en verifiëren dat zich bevindt tussen het basis-CA-certificaat en het tussenliggende certificaat waarmee u de inschrijvingsgroep maakt.)

Ga als volgende te werk om uw basis- of tussen-CA-certificaat toe te voegen aan Device Provisioning Service:

  1. Meld u aan bij het Azure-portaal.

  2. Selecteer Alle resources in het linkermenu of op de portalpagina.

  3. Selecteer uw Device Provisioning Service.

  4. Selecteer Certificaten in het menu Instellingen.

  5. Selecteer + Toevoegen in het bovenste menu.

  6. Voer een naam in voor uw basis- of tussen-CA-certificaat en upload het PEM - of .cer-bestand .

  7. Selecteer Certificaatstatus instellen om te verifiëren bij uploaden.

    Schermopname van het toevoegen van het basis-CA-certificaat aan een DPS-exemplaar.

  8. Selecteer Opslaan.

De verbindingsreeks voor de inrichtingsservice ophalen

Voor het voorbeeld in dit artikel hebt u de verbindingsreeks voor uw inrichtingsservice nodig. Gebruik de volgende stappen om deze op te halen.

  1. Meld u aan bij het Azure-portaal.

  2. Selecteer Alle resources in het linkermenu of op de portalpagina.

  3. Selecteer uw Device Provisioning Service.

  4. Selecteer beleid voor gedeelde toegang in het menu Instellingen.

  5. Selecteer het toegangsbeleid dat u wilt gebruiken.

  6. Kopieer en sla in het deelvenster Toegangsbeleid de primaire sleutel op verbindingsreeks.

    Schermopname van de locatie van de inrichtingsservice verbindingsreeks in de portal.

Een voorbeeld van een registratiegroep maken

In deze sectie wordt beschreven hoe u een .NET Core-consoletoepassing maakt waarmee een inschrijvingsgroep wordt toegevoegd aan uw inrichtingsservice.

  1. Open een Windows-opdrachtprompt en navigeer naar een map waarin u uw app wilt maken.

  2. Voer de volgende opdracht uit om een consoleproject te maken:

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

  3. Voer de volgende opdracht uit om een verwijzing naar de DPS-service-SDK toe te voegen:

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

    Met deze stap downloadt, installeert en voegt u een verwijzing toe naar het NuGet-pakket van de Azure IoT DPS-serviceclient en de bijbehorende afhankelijkheden. Dit pakket bevat de binaire bestanden voor de .NET-service-SDK.

  4. Open Program.cs bestand in een editor.

  5. Vervang de naamruimteinstructie boven aan het bestand door de volgende regel:

    namespace CreateEnrollmentGroup;

  6. Voeg de volgende using instructies toe boven aan het bestand boven de namespace instructie:

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

  7. Voeg de volgende velden toe aan de Program klasse en breng de aangegeven wijzigingen aan.

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

    • Vervang de waarde van de ProvisioningServiceConnectionString tijdelijke aanduiding door de verbindingsreeks van de inrichtingsservice die u in de vorige sectie hebt gekopieerd.

    • Vervang de waarde van de tijdelijke plaatsaanduiding X509RootCertPath door het pad naar een PEM- of CER-bestand. Dit bestand vertegenwoordigt het openbare deel van een basis-CA X.509-certificaat dat eerder is geüpload en geverifieerd met uw inrichtingsservice, of een tussencertificaat dat is geüpload en geverifieerd of een certificaat in de ondertekeningsketen heeft geüpload en geverifieerd.

    • U kunt desgewenst de EnrollmentGroupId waarde wijzigen. De tekenreeks mag alleen kleine letters en afbreekstreepjes bevatten.

    Belangrijk

    Voor productiecode dient u op de hoogte te zijn van de volgende beveiligingsoverwegingen:

    • Hard-coding van de verbindingsreeks voor de inrichtingsservicebeheerder is in strijd met de aanbevolen beveiligingsprocedures. In plaats daarvan moet de verbindingsreeks op een veilige manier worden ondergebracht, zoals in een beveiligd configuratiebestand of in het register.
    • Upload alleen het openbare deel van het handtekeningcertificaat. Upload nooit .pfx- (PKCS12) of .pem-bestanden met persoonlijke sleutels naar de inrichtingsservice.

  8. Voeg de volgende methode toe aan de klasse Program. Met deze code wordt een EnrollmentGroup vermelding gemaakt en vervolgens de ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync methode aangeroepen om de inschrijvingsgroep toe te voegen aan de inrichtingsservice.

    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. Vervang tot slot de Main-methode door de volgende regels:

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

  10. Sla uw wijzigingen op.

In deze sectie wordt beschreven hoe u een Node.js-script maakt waarmee een inschrijvingsgroep wordt toegevoegd aan uw inrichtingsservice.

Tip

Ter vereenvoudiging gebruikt dit voorbeeld SAS-verificatie om verbinding te maken met de DPS-service-API. Een veiligere benadering is het gebruik van Azure-tokenreferenties. Zie het create_tpm_enrollment_with_token_credentials.js voorbeeld in de Node.js SDK voor een voorbeeld van die verificatiemethode.

  1. Voer vanuit een opdrachtvenster in de werkmap het volgende uit:

    npm install azure-iot-provisioning-service

    Met deze stap downloadt, installeert en voegt u een verwijzing toe naar het Azure IoT DPS-serviceclientpakket en de bijbehorende afhankelijkheden. Dit pakket bevat de binaire bestanden voor de Node.js service-SDK.

  2. Maak met behulp van een teksteditor het bestand create_enrollment_group.js in de werkmap. Voeg de volgende code toe aan het bestand en sla het op:

        '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. Open een Windows-opdrachtprompt.

  2. Kloon de GitHub-opslagplaats voor het codevoorbeeld van de apparaatinschrijving met behulp van de Java service-SDK:

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

  3. Ga vanaf de locatie waar u de opslagplaats hebt gedownload naar de voorbeeldmap:

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

  4. Open het bestand /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java in een editor van uw keuze.

  5. Vervang [Provisioning Connection String] door de verbindingsreeks die u hebt gekopieerd in Get the verbindingsreeks for your provisioning service.

  6. Vervang de PUBLIC_KEY_CERTIFICATE_STRING constante tekenreeks door de waarde van het basis- of tussenliggende CA-certificaatbestand .pem . Dit bestand vertegenwoordigt het openbare deel van een basis-CA X.509-certificaat dat eerder is geüpload en geverifieerd met uw inrichtingsservice, of een tussencertificaat dat is geüpload en geverifieerd of een certificaat in de ondertekeningsketen heeft geüpload en geverifieerd.

    De syntaxis van certificaattekst moet dit patroon volgen zonder extra spaties of tekens:

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

    Het handmatig bijwerken van deze tekenreekswaarde kan gevoelig zijn voor fouten. Als u de juiste syntaxis wilt genereren, kunt u de volgende opdracht kopiëren en plakken in een Git Bash-prompt, vervangen door your-cert.pem de locatie van het certificaatbestand en op Enter drukken. Met deze opdracht wordt de syntaxis voor de PUBLIC_KEY_CERTIFICATE_STRING constante tekenreekswaarde gegenereerd en naar de uitvoer geschreven.

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

    Kopieer en plak de tekst van het uitvoercertificaat voor de constante waarde.

    Belangrijk

    Voor productiecode dient u op de hoogte te zijn van de volgende beveiligingsoverwegingen:

    • Hard-coding van de verbindingsreeks voor de inrichtingsservicebeheerder is in strijd met de aanbevolen beveiligingsprocedures. In plaats daarvan moet de verbindingsreeks op een veilige manier worden ondergebracht, zoals in een beveiligd configuratiebestand of in het register.
    • Upload alleen het openbare deel van het handtekeningcertificaat. Upload nooit .pfx- (PKCS12) of .pem-bestanden met persoonlijke sleutels naar de inrichtingsservice.

  7. Met het voorbeeld kunt u een IoT-hub instellen in de inschrijvingsgroep om het apparaat in te richten. Dit moet een IoT-hub zijn die eerder is gekoppeld aan de inrichtingsservice. Voor dit artikel laten we DPS kiezen uit de gekoppelde hubs volgens het standaardtoewijzingsbeleid, gelijkmatig gewogen distributie. Markeer de volgende instructie in het bestand als commentaar:

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

  8. Met de voorbeeldcode worden een inschrijvingsgroep voor X.509-apparaten gemaakt, bijgewerkt, opgevraagd en verwijderd. Als u wilt controleren of de registratiegroep is gemaakt in Azure Portal, moet u de volgende regels code aan het einde van het bestand commentaar geven:

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

  9. Sla het ServiceEnrollmentGroupSample.java bestand op.

Het voorbeeld van de registratiegroep uitvoeren

  1. Voer het voorbeeld uit:

    dotnet run

  2. Wanneer het maken is voltooid, worden in het opdrachtvenster de eigenschappen van de nieuwe inschrijvingsgroep weergegeven.

  1. Voer de volgende opdracht uit in de opdrachtprompt. Neem de aanhalingstekens rond de opdrachtargumenten op en vervang deze door <connection string> verbindingsreeks die u in de vorige sectie hebt gekopieerd en <certificate .pem file> door het pad naar het certificaatbestand.pem. Dit bestand vertegenwoordigt het openbare deel van een basis-CA X.509-certificaat dat eerder is geüpload en geverifieerd met uw inrichtingsservice, of een tussencertificaat dat is geüpload en geverifieerd of een certificaat in de ondertekeningsketen heeft geüpload en geverifieerd.

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

  2. Wanneer het maken is voltooid, worden in het opdrachtvenster de eigenschappen van de nieuwe inschrijvingsgroep weergegeven.

  1. Voer vanuit de map azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample in uw opdrachtprompt de volgende opdracht uit om het voorbeeld te bouwen:

    mvn install -DskipTests

    Met deze opdracht downloadt u het Maven-pakket van de Azure IoT DPS-serviceclient naar uw computer en bouwt u het voorbeeld. Dit pakket bevat de binaire bestanden voor de Java-service-SDK.

  2. Ga naar de doelmap en voer het voorbeeld uit. De build in de vorige stap voert .jar bestand uit in de doelmap met de volgende bestandsindeling: provisioning-x509-sample-{version}-with-deps.jar; bijvoorbeeld: provisioning-x509-sample-1.8.1-with-deps.jar. Mogelijk moet u de versie in de volgende opdracht vervangen.

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

  3. Wanneer het maken is voltooid, worden in het opdrachtvenster de eigenschappen van de nieuwe inschrijvingsgroep weergegeven.

Ga als volgt te werk om te controleren of de inschrijvingsgroep is gemaakt:

  1. Navigeer in Azure Portal naar uw Device Provisioning Service-exemplaar.

  2. Selecteer Inschrijvingen beheren in het menu Instellingen.

  3. Selecteer het tabblad Inschrijvingsgroepen . U ziet nu een nieuwe inschrijvingsvermelding die overeenkomt met de id van de inschrijvingsgroep die u in het voorbeeld hebt gebruikt.

    Schermopname van de zojuist gemaakte inschrijvingsgroep in de portal.

Resources opschonen

Als u van plan bent om de zelfstudies over Azure IoT Hub Device Provisioning Service te verkennen, moet u de resources die in dit artikel zijn gemaakt, niet opschonen. Gebruik anders de volgende stappen om alle resources te verwijderen die in dit artikel zijn gemaakt.

  1. Sluit het voorbeelduitvoervenster op uw computer.

  2. Selecteer Alle resources in het linkermenu in Azure Portal.

  3. Selecteer uw Device Provisioning Service.

  4. Selecteer Inschrijvingen beheren in het linkermenu onder Instellingen.

  5. Selecteer het tabblad Inschrijvingsgroepen .

  6. Schakel het selectievakje in naast de groepsnaam van de inschrijvingsgroep die u in dit artikel hebt gemaakt.

  7. Selecteer Verwijderen bovenaan de pagina.

  8. Selecteer certificaten onder Instellingen in het menu aan de linkerkant van Device Provisioning Service in Azure Portal.

  9. Selecteer het certificaat dat u voor dit artikel hebt geüpload.

  10. Selecteer Verwijderen boven aan certificaatdetails.

Hulpprogramma's voor certificaten

De Azure IoT C SDK bevat scripts waarmee u certificaten kunt maken en beheren. Zie Test-CA-certificaten beheren voor voorbeelden en zelfstudies voor meer informatie.

De Azure IoT Node.js SDK bevat scripts waarmee u certificaten kunt maken en beheren. Zie Hulpprogramma's voor de Azure IoT Device Provisioning Device SDK voor Node.js voor meer informatie.

U kunt ook hulpprogramma's gebruiken die beschikbaar zijn in de Azure IoT C SDK. Zie Test-CA-certificaten beheren voor voorbeelden en zelfstudies voor meer informatie.

De Azure IoT Java SDK bevat testhulpprogramma's waarmee u certificaten kunt maken en beheren. Zie X509-certificaatgenerator met behulp van de DICE-emulator voor meer informatie.

Volgende stappen

In dit artikel hebt u een inschrijvingsgroep gemaakt voor een X.509-tussen- of basis-CA-certificaat met behulp van de Azure IoT Hub Device Provisioning Service. Bekijk de volgende koppelingen voor meer informatie: