Skapa programmatiskt en registreringsgrupp för enhetsetableringstjänsten för X.509-certifikatattestering
Den här artikeln visar hur du programmatiskt skapar en registreringsgrupp i Azure IoT Hub Device Provisioning Service (DPS) som använder mellanliggande certifikat eller rotcertifikatutfärdare X.509-certifikat. Registreringsgruppen skapas med hjälp av Azure IoT Service SDK och ett exempelprogram. En registreringsgrupp kontrollerar åtkomst till etableringstjänsten för enheter som delar ett gemensamt signeringscertifikat i certifikatkedjan. Mer information finns i Använda X.509-certifikat med DPS. 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
Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.
Slutför stegen i Konfigurera IoT Hub Device Provisioning Service med Azure Portal.
Installera .NET 6.0 SDK eller senare eller senare på din Windows-baserade dator. Du kan använda följande kommando för att kontrollera din version.
dotnet --info
- Installera Node.js v4.0 eller senare på datorn.
Java SE Development Kit 8. Den här artikeln använder Azure IoT SDK för Java, som fungerar på både Windows och Linux. Den här artikeln använder Windows.
- 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:
Logga in på Azure-portalen.
På den vänstra menyn eller på portalsidan väljer du Alla resurser.
Välj enhetsetableringstjänsten.
I menyn Inställningar väljer du Certifikat.
På den översta menyn väljer du + Lägg till:.
Ange ett namn för rotcertifikatutfärdarcertifikatet eller mellanliggande CERTIFIKATutfärdarcertifikat och ladda upp .pem - eller .cer-filen .
Välj Ange certifikatstatus till verifierad vid uppladdning.
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.
Logga in på Azure-portalen.
På den vänstra menyn eller på portalsidan väljer du Alla resurser.
Välj enhetsetableringstjänsten.
I menyn Inställningar väljer du Principer för delad åtkomst.
Välj den åtkomstprincip som du vill använda.
I panelen Åtkomstprincip kopierar och sparar du den primära nyckeln anslutningssträng.
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.
Öppna en Windows-kommandotolk och gå till en mapp där du vill skapa din app.
Kör följande kommando för att skapa ett konsolprojekt:
dotnet new console --framework net6.0 --use-program-main
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.
Öppna Program.cs fil i ett redigeringsprogram.
Ersätt namespace-instruktionen överst i filen med följande rad:
namespace CreateEnrollmentGroup;
Lägg till följande
using
instruktioner överst i filen ovanför -instruktionennamespace
:using System.Security.Cryptography.X509Certificates; using System.Threading.Tasks; using Microsoft.Azure.Devices.Provisioning.Service;
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 har laddats upp och verifierats eller där ett certifikat i signeringskedjan har laddats upp 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.
Lägg till följande metod i
Program
klassen. Den här koden skapar enEnrollmentGroup
post och anroparProvisioningServiceClient.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 } }
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(); }
Spara dina ändringar.
Det här avsnittet visar hur du skapar ett Node.js skript som lägger till en registreringsgrupp i etableringstjänsten.
Dricks
För enkelhetens skull använder det här exemplet SAS-autentisering för att ansluta till DPS-tjänst-API:et. En säkrare metod är att använda autentiseringsuppgifter för Azure-token. Ett exempel på den autentiseringsmetoden finns i exemplet create_tpm_enrollment_with_token_credentials.js i Node.js SDK.
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.
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)); } }); } });
Öppna en kommandotolk i Windows.
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
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
Öppna filen /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java i valfri redigerare.
Ersätt
[Provisioning Connection String]
med anslutningssträng som du kopierade i Hämta anslutningssträng för etableringstjänsten.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 har laddats upp och verifierats eller där ett certifikat i signeringskedjan har laddats upp och verifierats.Syntaxen för certifikattext måste följa det här mönstret 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ärdetPUBLIC_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.
Med exemplet kan du ange en IoT-hubb i registreringsgruppen som enheten ska etableras till. Detta måste vara en IoT-hubb som tidigare var länkad 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.
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 Portal kommenterar du ut följande kodrader nära slutet av filen:
// ************************************** Delete info of enrollmentGroup *************************************** System.out.println("\nDelete the enrollmentGroup..."); provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);
Spara filen ServiceEnrollmentGroupSample.java .
Köra exemplet för registrering av grupp
Kör exemplet:
dotnet run
När det har skapats visar kommandofönstret egenskaperna för den nya registreringsgruppen.
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 har laddats upp och verifierats eller där ett certifikat i signeringskedjan har laddats upp och verifierats.node create_enrollment_group.js "<connection string>" "<certificate .pem file>"
När det har skapats visar kommandofönstret egenskaperna för den nya registreringsgruppen.
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.
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 följande kommando.cd target java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar
När det har skapats visar kommandofönstret egenskaperna för den nya registreringsgruppen.
Så här kontrollerar du att registreringsgruppen har skapats:
I Azure Portal navigerar du till instansen av enhetsetableringstjänsten.
I menyn Inställningar väljer du Hantera registreringar.
Välj fliken Registreringsgrupper . Du bör se en ny registreringspost som motsvarar det registreringsgrupps-ID som du använde i exemplet.
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.
Stäng exempelutdatafönstret på datorn.
På den vänstra menyn i Azure Portal väljer du Alla resurser.
Välj enhetsetableringstjänsten.
I den vänstra menyn under Inställningar väljer du Hantera registreringar.
Välj fliken Registreringsgrupper .
Markera kryssrutan bredvid gruppnamnet för den registreringsgrupp som du skapade i den här artikeln.
Välj Ta bort längst upp på sidan.
Från enhetsetableringstjänsten i Azure Portal väljer du Certifikat under Inställningar på den vänstra menyn.
Välj det certifikat som du laddade upp för den här artikeln.
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:
Mer information om X.509-certifikatattestering med DPS finns i X.509-certifikatattestering.
Ett exempel från slutpunkt till slutpunkt för etablering av enheter via en registreringsgrupp med X.509-certifikat finns i självstudien Etablera flera X.509-enheter med hjälp av registreringsgrupper .
Mer information om hur du hanterar enskilda registreringar och registreringsgrupper med hjälp av Azure Portal finns i Hantera enhetsregistreringar med Azure Portal.