Skapa programmatiskt en registreringsgrupp för enhetsetableringstjänsten för X.509-certifikatattestering

  • Artikel

Den här artikeln visar hur du programmatiskt skapar en registreringsgrupp som använder mellanliggande eller rotcertifikatutfärdare X.509-certifikat. Registreringsgruppen skapas med hjälp av Azure IoT Hub DPS Service SDK och ett exempelprogram. En registreringsgrupp kontrollerar åtkomst till etableringstjänsten för enheter som delar ett gemensamt signeringscertifikat i certifikatkedjan. Läs mer i informationen om att kontrollera enhetsåtkomst till etableringstjänsten med X.509-certifikat. Mer information om att använda X.509-certifikatbaserad Public Key Infrastructure (PKI) med Azure IoT Hub och enhetsetableringstjänst finns i Översikt över certifikatsäkerhet med X.509 CA.

Förutsättningar

  • Installera den senaste versionen av Git. Kontrollera att Git har lagts till i de miljövariabler som är tillgängliga för kommandofönstret. Se Software Freedom Conservancys Git-klientverktyg för den senaste versionen av git verktyg som ska installeras, vilket inkluderar Git Bash, kommandoradsappen som du kan använda för att interagera med din lokala Git-lagringsplats.

Kommentar

Även om stegen i den här artikeln fungerar på både Windows- och Linux-datorer använder den här artikeln en Windows-utvecklingsdator.

Skapa testcertifikat

Registreringsgrupper som använder X.509-certifikatattestering kan konfigureras för att använda ett rotcertifikatutfärdarcertifikat eller ett mellanliggande certifikat. Det vanligare är att konfigurera registreringsgruppen med ett mellanliggande certifikat. Att använda ett mellanliggande certifikat ger större flexibilitet eftersom flera mellanliggande certifikat kan genereras eller återkallas av samma rotcertifikatutfärdarcertifikat.

I den här artikeln behöver du antingen en rotcertifikatutfärdarcertifikatfil, en mellanliggande CA-certifikatfil eller båda i .pem - eller .cer-format . En fil innehåller den offentliga delen av rotcertifikatutfärdarcertifikatet X.509 och den andra innehåller den offentliga delen av det mellanliggande CA X.509-certifikatet.

Om du redan har en rot-CA-fil och/eller en mellanliggande CA-fil kan du fortsätta att lägga till och verifiera ditt rotcertifikat eller mellanliggande CA-certifikat.

Om du inte har någon rot-CA-fil och/eller en mellanliggande CA-fil följer du stegen i Skapa en X.509-certifikatkedja för att skapa dem. Du kan stoppa när du har slutfört stegen i Skapa mellanliggande CA-certifikat eftersom du inte behöver enhetscertifikat för att slutföra stegen i den här artikeln. När du är klar har du två X.509-certifikatfiler: ./certs/azure-iot-test-only.root.ca.cert.pem och ./certs/azure-iot-test-only.intermediate.cert.pem.

Lägga till och verifiera ditt rotcertifikat eller mellanliggande CA-certifikat

Enheter som etablerar via en registreringsgrupp med X.509-certifikat visar hela certifikatkedjan när de autentiserar med DPS. För att DPS ska kunna verifiera certifikatkedjan måste det rotcertifikat eller mellanliggande certifikat som konfigurerats i en registreringsgrupp antingen vara ett verifierat certifikat eller så måste det rullas upp till ett verifierat certifikat i certifikatkedjan som en enhet presenterar när det autentiserar med tjänsten.

För den här artikeln förutsätter vi att du har både ett rotcertifikatutfärdarcertifikat och ett mellanliggande CA-certifikat signerat av rotcertifikatutfärdare:

  • Om du planerar att skapa registreringsgruppen med rotcertifikatutfärdarcertifikatet måste du ladda upp och verifiera rotcertifikatutfärdarcertifikatet.

  • Om du planerar att skapa registreringsgruppen med det mellanliggande CA-certifikatet kan du ladda upp och verifiera antingen rotcertifikatutfärdarcertifikatet eller det mellanliggande CA-certifikatet. (Om du har flera mellanliggande CA-certifikat i certifikatkedjan kan du också ladda upp och verifiera eventuella mellanliggande certifikat som finns mellan rotcertifikatutfärdarcertifikatutfärdarcertifikatet och det mellanliggande certifikat som du skapar registreringsgruppen med.)

Så här lägger du till och verifierar ditt rotcertifikat eller mellanliggande CA-certifikat i Device Provisioning Service:

  1. Logga in på Azure-portalen.

  2. På den vänstra menyn eller på portalsidan väljer du Alla resurser.

  3. Välj enhetsetableringstjänsten.

  4. I menyn Inställningar väljer du Certifikat.

  5. På den översta menyn väljer du + Lägg till:.

  6. Ange ett namn för rotcertifikatutfärdarcertifikatet eller mellanliggande CERTIFIKATutfärdarcertifikat och ladda upp .pem - eller .cer-filen .

  7. Välj Ange certifikatstatus till verifierad vid uppladdning.

    Screenshot that shows adding the root CA certificate to a DPS instance.

  8. Välj Spara.

Hämta anslutningssträngen för etableringstjänsten

För exemplet i den här artikeln behöver du anslutningssträng för etableringstjänsten. Använd följande steg för att hämta den.

  1. Logga in på Azure-portalen.

  2. På den vänstra menyn eller på portalsidan väljer du Alla resurser.

  3. Välj enhetsetableringstjänsten.

  4. I menyn Inställningar väljer du Principer för delad åtkomst.

  5. Välj den åtkomstprincip som du vill använda.

  6. I panelen Åtkomstprincip kopierar och sparar du den primära nyckeln anslutningssträng.

    Screenshot that shows the location of the provisioning service connection string in the portal.

Skapa exemplet för registrering av grupp

Det här avsnittet visar hur du skapar ett .NET Core-konsolprogram som lägger till en registreringsgrupp i etableringstjänsten.

  1. Öppna en Windows-kommandotolk och gå till en mapp där du vill skapa din app.

  2. Kör följande kommando för att skapa ett konsolprojekt:

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

  3. Om du vill lägga till en referens till DPS-tjänstens SDK kör du följande kommando:

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

    Det här steget laddar ned, installerar och lägger till en referens till Azure IoT DPS-tjänstklientens NuGet-paket och dess beroenden. Det här paketet innehåller binärfilerna för .NET Service SDK.

  4. Öppna Program.cs fil i ett redigeringsprogram.

  5. Ersätt namespace-instruktionen överst i filen med följande rad:

    namespace CreateEnrollmentGroup;

  6. Lägg till följande using instruktioner överst i filen ovanför -instruktionen namespace :

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

  7. Lägg till följande fält i Program klassen och gör de angivna ändringarna.

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

    • ProvisioningServiceConnectionString Ersätt platshållarvärdet med anslutningssträng för etableringstjänsten som du kopierade i föregående avsnitt.

    • X509RootCertPath Ersätt platshållarvärdet med sökvägen till en .pem- eller .cer-fil. Den här filen representerar den offentliga delen av ett rotcertifikatutfärdare X.509-certifikat som tidigare har laddats upp och verifierats med etableringstjänsten, eller ett mellanliggande certifikat som själv har laddats upp och verifierats eller som har ett certifikat i signeringskedjan uppladdat och verifierats.

    • Du kan också ändra värdet EnrollmentGroupId . Strängen får bara innehålla gemener och bindestreck.

    Viktigt!

    I produktionskoden ska du vara medveten om följande säkerhetsöverväganden:

    • Hårdkodning av anslutningssträngen för etableringstjänstadministratören går emot bästa säkerhetsmetoder. Istället ska anslutningssträngen lagras på ett säkert sätt, som i en säker konfigurationsfil eller i registret.
    • Glöm inte att överföra den offentliga delen av signeringscertifikatet. Ladda aldrig upp .pfx- (PKCS12) eller .pem-filer som innehåller privata nycklar till etableringstjänsten.

  8. Lägg till följande metod i Program klassen. Den här koden skapar en EnrollmentGroup post och anropar ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync sedan metoden för att lägga till registreringsgruppen i etableringstjänsten.

    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. Ersätt slutligen Main metoden med följande rader:

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

  10. Spara dina ändringar.

Det här avsnittet visar hur du skapar ett Node.js skript som lägger till en registreringsgrupp i etableringstjänsten.

  1. Från ett kommandofönster i arbetsmappen kör du:

    npm install azure-iot-provisioning-service

    Det här steget laddar ned, installerar och lägger till en referens till Azure IoT DPS-tjänstklientpaketet och dess beroenden. Det här paketet innehåller binärfilerna för Node.js service SDK.

  2. Med en textredigerare skapar du filen create_enrollment_group.js i arbetsmappen. Lägg till följande kod i filen och spara:

        '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. Öppna en Windows-kommandotolk.

  2. Klona GitHub-lagringsplatsen för kodexempel för enhetsregistrering med hjälp av Java Service SDK:

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

  3. Från den plats där du laddade ned lagringsplatsen går du till exempelmappen:

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

  4. Öppna filen /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java i valfri redigerare.

  5. Ersätt [Provisioning Connection String] med anslutningssträng som du kopierade i Hämta anslutningssträng för etableringstjänsten.

  6. Ersätt konstantsträngen PUBLIC_KEY_CERTIFICATE_STRING med värdet för rot- eller mellanliggande CA-certifikatfilen .pem . Den här filen representerar den offentliga delen av ett rotcertifikatutfärdare X.509-certifikat som tidigare har laddats upp och verifierats med etableringstjänsten, eller ett mellanliggande certifikat som själv har laddats upp och verifierats eller som har ett certifikat i signeringskedjan uppladdat och verifierats.

    Syntaxen för certifikattexten måste följa mönstret nedan utan extra blanksteg eller tecken.

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

    Att uppdatera det här strängvärdet manuellt kan vara felbenäget. Om du vill generera rätt syntax kan du kopiera och klistra in följande kommando i en Git Bash-prompt , ersätta your-cert.pem med platsen för certifikatfilen och trycka på RETUR. Det här kommandot genererar syntaxen för strängkonstantvärdet PUBLIC_KEY_CERTIFICATE_STRING och skriver det till utdata.

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

    Kopiera och klistra in utdatacertifikattexten för konstantvärdet.

    Viktigt!

    I produktionskoden ska du vara medveten om följande säkerhetsöverväganden:

    • Hårdkodning av anslutningssträngen för etableringstjänstadministratören går emot bästa säkerhetsmetoder. Istället ska anslutningssträngen lagras på ett säkert sätt, som i en säker konfigurationsfil eller i registret.
    • Glöm inte att överföra den offentliga delen av signeringscertifikatet. Ladda aldrig upp .pfx- (PKCS12) eller .pem-filer som innehåller privata nycklar till etableringstjänsten.

  7. Med exemplet kan du ange en IoT-hubb i registreringsgruppen som enheten ska etableras till. Detta måste vara en IoT-hubb som tidigare har länkats till etableringstjänsten. I den här artikeln låter vi DPS välja mellan de länkade hubbarna enligt standardallokeringsprincipen, jämnt viktad distribution. Kommentera ut följande instruktion i filen:

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

  8. Exempelkoden skapar, uppdaterar, frågar och tar bort en registreringsgrupp för X.509-enheter. Om du vill verifiera att registreringsgruppen har skapats i Azure-portalen kommenterar du ut följande kodrader nära slutet av filen:

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

  9. Spara filen ServiceEnrollmentGroupSample.java .

Köra exemplet för registrering av grupp

  1. Kör exemplet:

    dotnet run

  2. När det har skapats visar kommandofönstret egenskaperna för den nya registreringsgruppen.

  1. Kör följande kommando i kommandotolken. Inkludera citattecken runt kommandoargumenten och ersätt <connection string> med anslutningssträng du kopierade i föregående avsnitt och <certificate .pem file> med sökvägen till certifikatfilen.pem. Den här filen representerar den offentliga delen av ett rotcertifikatutfärdare X.509-certifikat som tidigare har laddats upp och verifierats med etableringstjänsten, eller ett mellanliggande certifikat som själv har laddats upp och verifierats eller som har ett certifikat i signeringskedjan uppladdat och verifierats.

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

  2. När det har skapats visar kommandofönstret egenskaperna för den nya registreringsgruppen.

  1. Från mappen azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample i kommandotolken kör du följande kommando för att skapa exemplet:

    mvn install -DskipTests

    Det här kommandot laddar ned Azure IoT DPS-tjänstklienten Maven-paketet till datorn och skapar exemplet. Det här paketet innehåller binärfilerna för Java Service SDK.

  2. Växla till målmappen och kör exemplet. Versionen i föregående steg matar ut .jar fil i målmappen med följande filformat: provisioning-x509-sample-{version}-with-deps.jar; till exempel: provisioning-x509-sample-1.8.1-with-deps.jar. Du kan behöva ersätta versionen i kommandot nedan.

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

  3. När det har skapats visar kommandofönstret egenskaperna för den nya registreringsgruppen.

Så här kontrollerar du att registreringsgruppen har skapats:

  1. Gå till instansen av enhetsetableringstjänsten i Azure-portalen.

  2. På menyn Inställningar väljer du Hantera registreringar.

  3. Välj fliken Registreringsgrupper . Du bör se en ny registreringspost som motsvarar det registreringsgrupps-ID som du använde i exemplet.

Screenshot that shows the newly created enrollment group in the portal.

Screenshot that shows the newly created enrollment group in the portal.

Screenshot that shows the newly created enrollment group in the portal.

Rensa resurser

Om du planerar att utforska självstudierna för Azure IoT Hub Device Provisioning Service ska du inte rensa resurserna som skapats i den här artikeln. Annars kan du använda följande steg för att ta bort alla resurser som skapats av den här artikeln.

  1. Stäng exempelutdatafönstret på datorn.

  2. På den vänstra menyn i Azure-portalen väljer du Alla resurser.

  3. Välj enhetsetableringstjänsten.

  4. I den vänstra menyn under Inställningar väljer du Hantera registreringar.

  5. Välj fliken Registreringsgrupper .

  6. Markera kryssrutan bredvid gruppnamnet för den registreringsgrupp som du skapade i den här artikeln.

  7. Välj Ta bort längst upp på sidan.

  8. Från enhetsetableringstjänsten i Azure-portalen väljer du Certifikat under Inställningar på den vänstra menyn.

  9. Välj det certifikat som du laddade upp för den här artikeln.

  10. Längst upp i Certifikatinformation väljer du Ta bort.

Certifikatverktyg

Azure IoT C SDK har skript som kan hjälpa dig att skapa och hantera certifikat. Mer information finns i Hantera certifikat för testcertifikatutfärdare för exempel och självstudier.

Azure IoT-Node.js SDK har skript som kan hjälpa dig att skapa och hantera certifikat. Mer information finns i Verktyg för Azure IoT Device Provisioning Device SDK för Node.js.

Du kan också använda verktyg som är tillgängliga i Azure IoT C SDK. Mer information finns i Hantera certifikat för testcertifikatutfärdare för exempel och självstudier.

Azure IoT Java SDK innehåller testverktyg som kan hjälpa dig att skapa och hantera certifikat. Mer information finns i X509-certifikatgeneratorn med DICE-emulatorn.

Nästa steg

I den här artikeln har du skapat en registreringsgrupp för ett mellanliggande X.509- eller rotcertifikatutfärdarcertifikat med hjälp av Azure IoT Hub Device Provisioning Service. Mer information finns på följande länkar: