Programowe tworzenie grupy rejestracji usługi Device Provisioning Service dla zaświadczania certyfikatów X.509

Artykuł
01/19/2024

W tym artykule pokazano, jak programowo utworzyć grupę rejestracji w usłudze Azure IoT Hub Device Provisioning Service (DPS), która używa certyfikatów X.509 pośredniego lub głównego urzędu certyfikacji. Grupa rejestracji jest tworzona przy użyciu zestawu SDK usługi Azure IoT i przykładowej aplikacji. Grupa rejestracji steruje dostępem do usługi aprowizacji dla urządzeń, które mają wspólny certyfikat podpisywania w swoim łańcuchu certyfikatów. Aby dowiedzieć się więcej, zobacz Używanie certyfikatów X.509 z usługą DPS. Aby uzyskać więcej informacji na temat używania infrastruktury kluczy publicznych opartej na certyfikatach X.509 z usługą Azure IoT Hub i Device Provisioning, zobacz Omówienie zabezpieczeń certyfikatu X.509 urzędu certyfikacji.

Wymagania wstępne

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
Wykonaj kroki opisane w temacie Konfigurowanie usługi IoT Hub Device Provisioning Przy użyciu witryny Azure Portal.

Zainstaluj zestaw .NET 6.0 SDK lub nowszy lub nowszy na maszynie z systemem Windows. Aby sprawdzić wersję, możesz użyć następującego polecenia.
```
dotnet --info
```

Zainstaluj Node.js w wersji 4.0 lub nowszej lub nowszej na maszynie.

Java SE Development Kit 8. W tym artykule jest używany zestaw SDK usługi Azure IoT dla języka Java, który działa zarówno w systemach Windows, jak i Linux. W tym artykule jest używany system Windows.
Maven 3.

Zainstaluj najnowszą wersję usługi Git. Upewnij się, że usługa Git jest dodawana do zmiennych środowiskowych dostępnych w oknie polecenia. Zobacz Narzędzia klienckie Git firmy Software Freedom Conservancy, aby zapoznać się z najnowszą wersją git narzędzi do zainstalowania, która obejmuje powłokę Git Bash, aplikację wiersza polecenia, której można użyć do interakcji z lokalnym repozytorium Git.

Uwaga

Mimo że kroki opisane w tym artykule działają zarówno na komputerach z systemami Windows, jak i Linux, w tym artykule jest używany komputer deweloperzy z systemem Windows.

Tworzenie certyfikatów testowych

Grupy rejestracji korzystające z zaświadczania certyfikatu X.509 można skonfigurować do używania certyfikatu głównego urzędu certyfikacji lub certyfikatu pośredniego. Bardziej typowym przypadkiem jest skonfigurowanie grupy rejestracji przy użyciu certyfikatu pośredniego. Użycie certyfikatu pośredniego zapewnia większą elastyczność, ponieważ można wygenerować lub odwołać wiele certyfikatów pośrednich przez ten sam certyfikat głównego urzędu certyfikacji.

W tym artykule potrzebny jest plik certyfikatu głównego urzędu certyfikacji, plik certyfikatu pośredniego urzędu certyfikacji lub w formacie pem lub .cer . Jeden plik zawiera publiczną część certyfikatu X.509 głównego urzędu certyfikacji, a drugi zawiera publiczną część certyfikatu X.509 pośredniego urzędu certyfikacji.

Jeśli masz już plik głównego urzędu certyfikacji i/lub plik pośredniego urzędu certyfikacji, możesz kontynuować dodawanie i weryfikowanie certyfikatu głównego lub pośredniego urzędu certyfikacji.

Jeśli nie masz pliku głównego urzędu certyfikacji i/lub pliku pośredniego urzędu certyfikacji, wykonaj kroki opisane w artykule Tworzenie łańcucha certyfikatów X.509, aby je utworzyć. Po wykonaniu kroków opisanych w artykule Tworzenie certyfikatu pośredniego urzędu certyfikacji można zatrzymać, ponieważ nie potrzebujesz certyfikatów urządzeń, aby wykonać kroki opisane w tym artykule. Po zakończeniu masz dwa pliki certyfikatów X.509: ./certs/azure-iot-test-only.root.ca.cert.pem i ./certs/azure-iot-test-only.intermediate.cert.pem.

Dodawanie i weryfikowanie certyfikatu głównego lub pośredniego urzędu certyfikacji

Urządzenia aprowizowania za pośrednictwem grupy rejestracji przy użyciu certyfikatów X.509 prezentują cały łańcuch certyfikatów podczas uwierzytelniania w usłudze DPS. Aby usługa DPS mogła zweryfikować łańcuch certyfikatów, certyfikat główny lub pośredni skonfigurowany w grupie rejestracji musi być zweryfikowanym certyfikatem lub musi zostać zbiorczy do zweryfikowanego certyfikatu w łańcuchu certyfikatów, które urządzenie przedstawia podczas uwierzytelniania w usłudze.

W tym artykule przyjęto założenie, że masz zarówno certyfikat głównego urzędu certyfikacji, jak i certyfikat pośredniego urzędu certyfikacji podpisany przez główny urząd certyfikacji:

Jeśli planujesz utworzenie grupy rejestracji przy użyciu certyfikatu głównego urzędu certyfikacji, musisz przekazać i zweryfikować certyfikat głównego urzędu certyfikacji.
Jeśli planujesz utworzenie grupy rejestracji przy użyciu certyfikatu pośredniego urzędu certyfikacji, możesz przekazać i zweryfikować certyfikat głównego urzędu certyfikacji lub certyfikat pośredniego urzędu certyfikacji. (Jeśli w łańcuchu certyfikatów znajduje się wiele certyfikatów pośredniego urzędu certyfikacji, możesz również przekazać i zweryfikować dowolny certyfikat pośredni, który znajduje się między certyfikatem głównego urzędu certyfikacji a certyfikatem pośrednim, za pomocą którego tworzysz grupę rejestracji).

Aby dodać i zweryfikować certyfikat głównego lub pośredniego urzędu certyfikacji do usługi Device Provisioning Service:

Zaloguj się w witrynie Azure Portal.
W menu po lewej stronie lub na stronie portalu wybierz pozycję Wszystkie zasoby.
Wybierz usługę Device Provisioning Service.
W menu Ustawienia wybierz pozycję Certyfikaty.
W górnym menu wybierz pozycję + Dodaj:.
Wprowadź nazwę certyfikatu głównego lub pośredniego urzędu certyfikacji i przekaż plik pem lub .cer .
Wybierz pozycję Ustaw stan certyfikatu, aby zweryfikować podczas przekazywania.
Wybierz pozycję Zapisz.

Uzyskiwanie parametrów połączenia usługi aprowizacji

Aby uzyskać przykład w tym artykule, potrzebujesz parametry połączenia dla usługi aprowizacji. Aby go pobrać, wykonaj następujące czynności.

Zaloguj się w witrynie Azure Portal.
W menu po lewej stronie lub na stronie portalu wybierz pozycję Wszystkie zasoby.
Wybierz usługę Device Provisioning Service.
W menu Ustawienia wybierz pozycję Zasady dostępu współdzielonego.
Wybierz zasady dostępu, których chcesz użyć.
Na panelu Zasady dostępu skopiuj i zapisz klucz podstawowy parametry połączenia.

Tworzenie przykładowej grupy rejestracji

W tej sekcji pokazano, jak utworzyć aplikację konsolową platformy .NET Core, która dodaje grupę rejestracji do usługi aprowizacji.

Otwórz wiersz polecenia systemu Windows i przejdź do folderu, w którym chcesz utworzyć aplikację.
Aby utworzyć projekt konsoli, uruchom następujące polecenie:
```
dotnet new console --framework net6.0 --use-program-main 
```
Aby dodać odwołanie do zestawu SDK usługi DPS, uruchom następujące polecenie:
```
dotnet add package Microsoft.Azure.Devices.Provisioning.Service 
```
Ten krok pobiera, instaluje i dodaje odwołanie do pakietu NuGet klienta usługi Azure IoT DPS i jego zależności. Ten pakiet zawiera pliki binarne zestawu SDK usługi .NET.
Otwórz plik Program.cs w edytorze.
Zastąp instrukcję przestrzeni nazw w górnej części pliku następującym wierszem:
```
namespace CreateEnrollmentGroup;
```

Dodaj następujące using instrukcje w górnej części pliku powyżej instrukcji namespace :

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

Dodaj następujące pola do Program klasy i wprowadź wskazane zmiany.
```
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}";
```
- Zastąp wartość symbolu ProvisioningServiceConnectionString zastępczego parametry połączenia usługi aprowizacji skopiowaną w poprzedniej sekcji.
- Zastąp wartość symbolu X509RootCertPath zastępczego ścieżką do pliku pem lub .cer. Ten plik reprezentuje publiczną część certyfikatu X.509 głównego urzędu certyfikacji, który został wcześniej przekazany i zweryfikowany w usłudze aprowizacji, lub certyfikat pośredni, który został przekazany i zweryfikowany lub miał certyfikat w łańcuchu podpisywania przekazany i zweryfikowany.
- Możesz opcjonalnie zmienić EnrollmentGroupId wartość. Ciąg może zawierać tylko małe litery i łączniki.
Ważne

W kodzie produkcyjnym pamiętaj o następujących kwestiach dotyczących zabezpieczeń:
- Trwałe kodowanie parametrów połączenia administratora usługi aprowizacji jest niezgodne z najlepszymi rozwiązaniami dotyczącymi zabezpieczeń. Zamiast tego parametry połączenia powinny być przechowywane w sposób bezpieczny, np. w zabezpieczonym pliku konfiguracji lub rejestrze.
- Pamiętaj, aby przekazać tylko publiczną część certyfikatu podpisywania. Nigdy nie przekazuj plików pfx (PKCS12) ani plików pem zawierających klucze prywatne do usługi aprowizacji.

Dodaj następującą metodę do Program klasy . Ten kod tworzy wpis, a następnie wywołuje ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync metodę EnrollmentGroup , aby dodać grupę rejestracji do usługi aprowizacji.

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

    }
}

Na koniec zastąp metodę Main następującymi wierszami:

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

Zapisz zmiany.

W tej sekcji pokazano, jak utworzyć skrypt Node.js, który dodaje grupę rejestracji do usługi aprowizacji.

Napiwek

Dla uproszczenia w tym przykładzie uwierzytelnianie SAS jest używane do nawiązywania połączenia z interfejsem API usługi DPS. Bezpieczniejszym podejściem jest użycie poświadczeń tokenu platformy Azure. Przykład tej metody uwierzytelniania można znaleźć w przykładzie create_tpm_enrollment_with_token_credentials.js w zestawie SDK Node.js.

Z poziomu okna polecenia w folderze roboczym uruchom następujące polecenie:
```
npm install azure-iot-provisioning-service
```
Ten krok pobiera, instaluje i dodaje odwołanie do pakietu klienta usługi Azure IoT DPS i jego zależności. Ten pakiet zawiera pliki binarne zestawu SDK usługi Node.js.

Za pomocą edytora tekstu utwórz plik create_enrollment_group.js w folderze roboczym. Dodaj następujący kod do pliku i zapisz go:

    '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));
          }
        });
      }
    });

Otwórz wiersz polecenia systemu Windows.
Sklonuj repozytorium GitHub dla przykładowego kodu rejestracji urządzeń przy użyciu zestawu SDK usługi Java:
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```

Z lokalizacji, w której pobrano repozytorium, przejdź do folderu przykładowego:

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

Otwórz plik /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java w wybranym edytorze.
Zastąp [Provisioning Connection String] wartość parametry połączenia skopiowaną w sekcji Pobierz parametry połączenia dla usługi aprowizacji.
Zastąp PUBLIC_KEY_CERTIFICATE_STRING ciąg stały wartością pliku certyfikatu głównego lub pośredniego urzędu .pem certyfikacji. Ten plik reprezentuje publiczną część certyfikatu X.509 głównego urzędu certyfikacji, który został wcześniej przekazany i zweryfikowany w usłudze aprowizacji, lub certyfikat pośredni, który został przekazany i zweryfikowany lub miał certyfikat w łańcuchu podpisywania przekazany i zweryfikowany.

Składnia tekstu certyfikatu musi być zgodna z tym wzorcem bez dodatkowych spacji ani znaków:
```
private static final String PUBLIC_KEY_CERTIFICATE_STRING = 
        "-----BEGIN CERTIFICATE-----\n" +
        "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
            ...
        "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
        "-----END CERTIFICATE-----";
```
Ręczne aktualizowanie tej wartości ciągu może być podatne na błąd. Aby wygenerować właściwą składnię, możesz skopiować i wkleić następujące polecenie do wiersza polecenia powłoki Git Bash , zastąpić your-cert.pem lokalizacją pliku certyfikatu i nacisnąć ENTER. To polecenie generuje składnię stałej PUBLIC_KEY_CERTIFICATE_STRING wartości ciągu i zapisuje ją w danych wyjściowych.
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' your-cert.pem
```
Skopiuj i wklej tekst wyjściowego certyfikatu dla stałej wartości.
Ważne

W kodzie produkcyjnym pamiętaj o następujących kwestiach dotyczących zabezpieczeń:
- Trwałe kodowanie parametrów połączenia administratora usługi aprowizacji jest niezgodne z najlepszymi rozwiązaniami dotyczącymi zabezpieczeń. Zamiast tego parametry połączenia powinny być przechowywane w sposób bezpieczny, np. w zabezpieczonym pliku konfiguracji lub rejestrze.
- Pamiętaj, aby przekazać tylko publiczną część certyfikatu podpisywania. Nigdy nie przekazuj plików pfx (PKCS12) ani plików pem zawierających klucze prywatne do usługi aprowizacji.
Przykład umożliwia ustawienie centrum IoT w grupie rejestracji w celu aprowizacji urządzenia. Musi to być centrum IoT, które wcześniej było połączone z usługą aprowizacji. W tym artykule możemy wybrać usługę DPS z połączonych centrów zgodnie z domyślnymi zasadami alokacji, równomiernie ważonymi rozkładami. Oznacz następującą instrukcję w pliku jako komentarz:
```
enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);                // Optional parameter.
```
Przykładowy kod tworzy, aktualizuje, wykonuje zapytania i usuwa grupę rejestracji dla urządzeń X.509. Aby zweryfikować pomyślne utworzenie grupy rejestracji w witrynie Azure Portal, oznacz jako komentarz następujące wiersze kodu na końcu pliku:
```
// ************************************** Delete info of enrollmentGroup ***************************************
System.out.println("\nDelete the enrollmentGroup...");
provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);
```
Zapisz plik ServiceEnrollmentGroupSample.java.

Uruchamianie przykładowej grupy rejestracji

Uruchom przykład:
```
dotnet run
```
Po pomyślnym utworzeniu w oknie polecenia zostaną wyświetlone właściwości nowej grupy rejestracji.

Uruchom następujące polecenie w wierszu polecenia. Uwzględnij cudzysłowy wokół argumentów poleceń i zastąp <connection string> ciąg parametry połączenia skopiowanymi w poprzedniej sekcji oraz <certificate .pem file> ścieżką do pliku certyfikatu.pem. Ten plik reprezentuje publiczną część certyfikatu X.509 głównego urzędu certyfikacji, który został wcześniej przekazany i zweryfikowany w usłudze aprowizacji, lub certyfikat pośredni, który został przekazany i zweryfikowany lub miał certyfikat w łańcuchu podpisywania przekazany i zweryfikowany.
```
node create_enrollment_group.js "<connection string>" "<certificate .pem file>"
```
Po pomyślnym utworzeniu w oknie polecenia zostaną wyświetlone właściwości nowej grupy rejestracji.

W folderze azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample w wierszu polecenia uruchom następujące polecenie, aby skompilować przykład:
```
mvn install -DskipTests
```
To polecenie pobiera pakiet Maven klienta usługi Azure IoT DPS na maszynę i kompiluje przykład. Ten pakiet zawiera pliki binarne zestawu SDK usługi Java.
Przejdź do folderu docelowego i uruchom przykład. Kompilacja w poprzednim kroku zwraca .jar plik w folderze docelowym o następującym formacie pliku: provisioning-x509-sample-{version}-with-deps.jarna przykład: provisioning-x509-sample-1.8.1-with-deps.jar. Może być konieczne zastąpienie wersji w poniższym poleceniu.
```
cd target
java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar
```
Po pomyślnym utworzeniu w oknie polecenia zostaną wyświetlone właściwości nowej grupy rejestracji.

Aby sprawdzić, czy grupa rejestracji została utworzona:

W witrynie Azure Portal przejdź do wystąpienia usługi Device Provisioning Service.
W menu Ustawienia wybierz pozycję Zarządzaj rejestracjami.
Wybierz kartę Grupy rejestracji. Powinien zostać wyświetlony nowy wpis rejestracji odpowiadający identyfikatorowi grupy rejestracji użytemu w przykładzie.

Czyszczenie zasobów

Jeśli planujesz zapoznać się z samouczkami usługi Azure IoT Hub Device Provisioning Service, nie usuwaj zasobów utworzonych w tym artykule. W przeciwnym razie wykonaj następujące kroki, aby usunąć wszystkie zasoby utworzone w tym artykule.

Zamknij okno przykładowych danych wyjściowych na komputerze.
W menu po lewej stronie w witrynie Azure Portal wybierz pozycję Wszystkie zasoby.
Wybierz usługę Device Provisioning Service.
W menu po lewej stronie w obszarze Ustawienia wybierz pozycję Zarządzaj rejestracjami.
Wybierz kartę Grupy rejestracji.
Zaznacz pole wyboru obok nazwy grupy rejestracji utworzonej w tym artykule.
W górnej części strony wybierz pozycję Usuń.
W usłudze Device Provisioning Service w witrynie Azure Portal wybierz pozycję Certyfikaty w obszarze Ustawienia w menu po lewej stronie.
Wybierz przekazany certyfikat dla tego artykułu.
W górnej części szczegółów certyfikatu wybierz pozycję Usuń.

Narzędzia certyfikatów

Zestaw AZURE IoT C SDK zawiera skrypty, które mogą ułatwić tworzenie certyfikatów i zarządzanie nimi. Aby dowiedzieć się więcej, zobacz Zarządzanie certyfikatami testowego urzędu certyfikacji dla przykładów i samouczków.

Zestaw SDK usługi Azure IoT Node.js zawiera skrypty, które mogą ułatwić tworzenie certyfikatów i zarządzanie nimi. Aby dowiedzieć się więcej, zobacz Tools for the Azure IoT Device Provisioning Device SDK for Node.js (Narzędzia dla zestawu SDK usługi Azure IoT Device Provisioning Device Provisioning dla Node.js).

Możesz również użyć narzędzi dostępnych w zestawie SDK języka C usługi Azure IoT. Aby dowiedzieć się więcej, zobacz Zarządzanie certyfikatami testowego urzędu certyfikacji dla przykładów i samouczków.

Zestaw SDK języka Java usługi Azure IoT zawiera narzędzia testowe, które mogą pomóc w tworzeniu certyfikatów i zarządzaniu nimi. Aby dowiedzieć się więcej, zobacz Generator certyfikatów X509 przy użyciu emulatora DICE.

Następne kroki

W tym artykule utworzono grupę rejestracji dla pośredniego lub głównego certyfikatu urzędu certyfikacji X.509 przy użyciu usługi Azure IoT Hub Device Provisioning Service. Aby dowiedzieć się więcej, zapoznaj się z następującymi linkami:

Aby uzyskać więcej informacji na temat zaświadczania certyfikatów X.509 za pomocą usługi DPS, zobacz Zaświadczenie certyfikatu X.509.
Aby zapoznać się z końcowym przykładem aprowizacji urządzeń za pośrednictwem grupy rejestracji przy użyciu certyfikatów X.509, zobacz samouczek Aprowizowanie wielu urządzeń X.509 przy użyciu grup rejestracji.
Aby dowiedzieć się więcej o zarządzaniu poszczególnymi rejestracjami i grupami rejestracji przy użyciu witryny Azure Portal, zobacz Jak zarządzać rejestracjami urządzeń w witrynie Azure Portal.

Udostępnij za pośrednictwem