Membuat grup pendaftaran Device Provisioning Service secara terprogram untuk pengesahan sertifikat X.509

Artikel
01/19/2024

Artikel ini memperlihatkan kepada Anda cara membuat grup pendaftaran secara terprogram yang menggunakan sertifikat CA X.509 menengah atau akar. Grup pendaftaran dibuat dengan menggunakan SDK layanan Azure IoT Hub DPS dan aplikasi sampel. Grup pendaftaran mengontrol akses ke layanan penyediaan untuk perangkat yang berbagi sertifikat penandatanganan umum dalam rantai sertifikat mereka. Untuk mempelajari selengkapnya, lihat Mengontrol akses perangkat dengan sertifikat X.509. Untuk informasi selengkapnya tentang menggunakan Public Key Infrastructure (PKI) berbasis sertifikat X.509 dengan Azure IoT Hub dan Device Provisioning Service, lihat Ringkasan keamanan sertifikat CA X.509.

Prasyarat

Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.
Selesaikan langkah-langkah dalam Menyiapkan IoT Hub Device Provisioning Service dengan portal Microsoft Azure.

Instal .NET 6.0 SDK atau yang lebih baru atau yang lebih baru di komputer berbasis Windows Anda. Anda bisa menggunakan perintah berikut untuk memeriksa versi yang Anda gunakan.
```
dotnet --info
```

Instal Node.js v4.0 atau yang lebih baru atau lebih baru di komputer Anda.

Java SE Development Kit 8. Artikel ini menggunakan Azure IoT SDK untuk Java, yang berfungsi di Windows dan Linux. Artikel ini menggunakan Windows.
Maven 3.

Pasang versi terbaru Git. Pastikan Git ditambahkan ke variabel lingkungan yang dapat diakses oleh jendela perintah. Lihat alat klien Git Software Freedom Conservancy untuk versi terbaru alat git yang akan diinstal, yang mencakup Git Bash, aplikasi baris perintah yang dapat Anda gunakan untuk berinteraksi dengan repositori Git lokal.

Catatan

Meskipun langkah-langkah dalam artikel ini berfungsi pada komputer Windows maupun Linux, artikel ini menggunakan komputer pengembangan Windows.

Membuat sertifikat uji

Grup pendaftaran yang menggunakan pengesahan sertifikat X.509 dapat dikonfigurasi untuk menggunakan sertifikat OS akar atau sertifikat perantara. Kasus yang lebih biasa adalah mengonfigurasi grup pendaftaran dengan sertifikat perantara. Menggunakan sertifikat perantara memberikan lebih banyak fleksibilitas karena beberapa sertifikat perantara dapat dihasilkan atau dicabut oleh sertifikat OS akar yang sama.

Untuk artikel ini, Anda memerlukan file sertifikat OS akar, file sertifikat OS perantara, atau dalam format .pem atau .cer . Satu file berisi bagian publik dari sertifikat CA X.509 akar dan yang lainnya berisi bagian publik sertifikat CA X.509 menengah.

Jika Anda sudah memiliki file OS akar dan/atau file CA perantara, Anda dapat terus Menambahkan dan memverifikasi sertifikat OS akar atau menengah Anda.

Jika Anda tidak memiliki file CA akar dan/atau file CA perantara, ikuti langkah-langkah dalam Membuat rantai sertifikat X.509 untuk membuatnya. Anda dapat berhenti setelah menyelesaikan langkah-langkah dalam Membuat sertifikat OS perantara karena Anda tidak memerlukan sertifikat perangkat untuk menyelesaikan langkah-langkah dalam artikel ini. Setelah selesai, Anda memiliki dua file sertifikat X.509: ./certs/azure-iot-test-only.root.ca.cert.pem dan ./certs/azure-iot-test-only.intermediate.cert.pem.

Menambahkan dan memverifikasi sertifikat OS akar atau menengah Anda

Perangkat yang menyediakan melalui grup pendaftaran menggunakan sertifikat X.509, menyajikan seluruh rantai sertifikat saat diautentikasi dengan DPS. Agar DPS dapat memvalidasi rantai sertifikat, sertifikat akar atau menengah yang dikonfigurasi dalam grup pendaftaran harus berupa sertifikat terverifikasi atau harus digulung ke sertifikat terverifikasi dalam rantai sertifikat yang disajikan perangkat saat diautentikasi dengan layanan.

Untuk artikel ini, dengan asumsi Anda memiliki sertifikat OS akar dan sertifikat OS perantara yang ditandatangani oleh CA akar:

Jika Anda berencana membuat grup pendaftaran dengan sertifikat OS akar, Anda perlu mengunggah dan memverifikasi sertifikat OS akar.
Jika Anda berencana membuat grup pendaftaran dengan sertifikat OS perantara, Anda dapat mengunggah dan memverifikasi sertifikat OS akar atau sertifikat OS perantara. (Jika Anda memiliki beberapa sertifikat OS perantara dalam rantai sertifikat, Anda dapat, atau, mengunggah dan memverifikasi sertifikat perantara yang berada di antara sertifikat OS akar dan sertifikat perantara yang Anda buat grup pendaftaran dengan.)

Untuk menambahkan dan memverifikasi sertifikat OS akar atau menengah Anda ke Device Provisioning Service:

Masuk ke portal Azure.
Di menu sebelah kiri atau di halaman portal, pilih Semua sumber daya.
Pilih Device Provisioning Service Anda.
Di menu Pengaturan, pilih Sertifikat.
Di menu atas, pilih +Tambahkan:.
Masukkan nama untuk sertifikat OS akar atau menengah Anda, dan unggah file .pem atau .cer .
Pilih Atur status sertifikat menjadi terverifikasi saat pengunggahan.
Pilih Simpan.

Mendapatkan string koneksi untuk layanan penyediaan Anda

Untuk sampel dalam artikel ini, Anda memerlukan string koneksi untuk layanan provisi Anda. Gunakan langkah-langkah berikut untuk mengambilnya.

Masuk ke portal Azure.
Di menu sebelah kiri atau di halaman portal, pilih Semua sumber daya.
Pilih Device Provisioning Service Anda.
Di menu Pengaturan, pilih Kebijakan akses bersama.
Pilih kebijakan akses yang ingin Anda gunakan.
Di panel Kebijakan Akses, salin dan simpan string koneksi kunci primer.

Membuat sampel grup pendaftaran

Bagian ini menunjukkan cara membuat aplikasi konsol .NET Core yang menambahkan grup pendaftaran ke layanan provisi Anda.

Buka perintah Windows dan navigasikan ke folder tempat Anda ingin membuat aplikasi.

Untuk membuat proyek konsol, jalankan perintah berikut:

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

Untuk menambahkan referensi ke SDK layanan DPS, jalankan perintah berikut:
```
dotnet add package Microsoft.Azure.Devices.Provisioning.Service 
```
Langkah ini mengunduh, menginstal, dan menambahkan referensi ke paket NuGet klien layanan Azure IoT DPS dan dependensinya. Paket ini mencakup biner untuk SDK layanan .NET.
Buka file Program.cs di editor.
Ganti pernyataan namespace layanan di bagian atas file dengan baris berikut:
```
namespace CreateEnrollmentGroup;
```

Tambahkan pernyataan berikut using di bagian atas file di atasnamespace pernyataan:

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

Tambahkan bidang berikut ke Program kelas, dan buat perubahan yang ditunjukkan.
```
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}";
```
- Ganti nilai tempat penampung ProvisioningServiceConnectionString dengan string koneksi layanan provisi yang disalin di bagian sebelumnya.
- Ganti nilai tempat penampung X509RootCertPath dengan jalur ke file .pem atau .cer. File ini mewakili bagian publik dari sertifikat CA X.509 akar yang sebelumnya telah diunggah dan diverifikasi dengan layanan provisi Anda, atau sertifikat perantara yang telah diunggah dan diverifikasi atau memiliki sertifikat dalam rantai penandatanganannya yang diunggah dan diverifikasi.
- Anda dapat secara opsional mengubah nilai EnrollmentGroupId. String hanya dapat berisi karakter huruf kecil dan tanda hubung.
Penting

Dalam kode produksi, ketahui pertimbangan keamanan berikut:
- Pengodean secara permanen string koneksi untuk administrator layanan penyediaan bertentangan dengan praktik terbaik keamanan. Sebaliknya, string koneksi harus disimpan dengan cara yang aman, seperti dalam file konfigurasi aman atau di registri.
- Pastikan untuk mengunggah hanya bagian publik dari sertifikat penandatanganan. Jangan pernah mengunggah file .pfx (PKCS12) atau .pem yang berisi kunci privat ke layanan penyediaan.

Tambahkan metode berikut ke kelas Program. Kode ini membuat EnrollmentGroup entri lalu memanggil ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync metode untuk menambahkan grup pendaftaran ke layanan provisi.

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

    }
}

Terakhir, ganti metode Main dengan baris berikut:

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

Simpan perubahan.

Bagian ini memperlihatkan kepada Anda cara membuat skrip Node.js yang menambahkan grup pendaftaran ke layanan provisi Anda.

Dari jendela perintah di folder aktif Anda, jalankan:
```
npm install azure-iot-provisioning-service
```
Langkah ini mengunduh, menginstal, dan menambahkan referensi ke paket klien layanan Azure IoT DPS dan dependensinya. Paket ini mencakup biner untuk SDK layanan Node.js.

Dengan menggunakan editor teks, buat file create_enrollment_group.js di folder aktif Anda. Tambahkan kode berikut ke file dan simpan:

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

Buka prompt perintah Windows.
Kloning repositori GitHub untuk sampel kode pendaftaran perangkat menggunakan Java Service SDK:
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```

Dari lokasi tempat Anda mengunduh repositori, buka folder sampel:

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

Buka file /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java di editor pilihan Anda.
Ganti [Provisioning Connection String] dengan string koneksi yang Anda salin di Mendapatkan string koneksi untuk layanan provisi Anda.
PUBLIC_KEY_CERTIFICATE_STRING Ganti string konstanta dengan nilai file sertifikat .pem OS akar atau menengah Anda. File ini mewakili bagian publik dari sertifikat CA X.509 akar yang sebelumnya telah diunggah dan diverifikasi dengan layanan provisi Anda, atau sertifikat perantara yang telah diunggah dan diverifikasi atau memiliki sertifikat dalam rantai penandatanganannya yang diunggah dan diverifikasi.

Sintaks teks sertifikat harus mengikuti pola di bawah ini tanpa spasi atau karakter tambahan.
```
private static final String PUBLIC_KEY_CERTIFICATE_STRING = 
        "-----BEGIN CERTIFICATE-----\n" +
        "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
            ...
        "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
        "-----END CERTIFICATE-----";
```
Memperbarui nilai string ini secara manual dapat rentan terhadap kesalahan. Untuk menghasilkan sintaks yang tepat, Anda dapat menyalin dan menempelkan perintah berikut ke permintaan Git Bash , mengganti your-cert.pem dengan lokasi file sertifikat Anda, dan menekan ENTER. Perintah ini menghasilkan sintaks untuk PUBLIC_KEY_CERTIFICATE_STRING nilai konstanta string dan menulisnya ke output.
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' your-cert.pem
```
Salin dan tempel teks sertifikat output untuk nilai konstanta.
Penting

Dalam kode produksi, ketahui pertimbangan keamanan berikut:
- Pengodean secara permanen string koneksi untuk administrator layanan penyediaan bertentangan dengan praktik terbaik keamanan. Sebaliknya, string koneksi harus disimpan dengan cara yang aman, seperti dalam file konfigurasi aman atau di registri.
- Pastikan untuk mengunggah hanya bagian publik dari sertifikat penandatanganan. Jangan pernah mengunggah file .pfx (PKCS12) atau .pem yang berisi kunci privat ke layanan penyediaan.
Sampel memungkinkan Anda mengatur hub IoT di grup pendaftaran untuk memprovisikan perangkat. Ini harus menjadi hub IoT yang sebelumnya telah ditautkan ke layanan provisi. Untuk artikel ini, kami membiarkan DPS memilih dari hub tertaut sesuai dengan kebijakan alokasi default, distribusi tertimbang merata. Komentari pernyataan berikut dalam file:
```
enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);                // Optional parameter.
```

Kode sampel membuat, memperbarui, mengkueri, dan menghapus grup pendaftaran untuk perangkat X.509. Untuk memverifikasi keberhasilan pembuatan grup pendaftaran di portal Azure, komentari baris kode berikut di dekat akhir file:

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

Simpan file ServiceEnrollmentGroupSample.java.

Menjalankan sampel grup pendaftaran

Jalankan sampel:
```
dotnet run
```
Jika pembuatan berhasil, jendela perintah menampilkan properti grup pendaftaran baru.

Jalankan perintah berikut di prompt perintah Anda. Sertakan tanda kutip di sekitar argumen perintah dan ganti <connection string> dengan string koneksi Anda salin di bagian sebelumnya, dan <certificate .pem file> dengan jalur ke file sertifikat .pem Anda. File ini mewakili bagian publik dari sertifikat CA X.509 akar yang sebelumnya telah diunggah dan diverifikasi dengan layanan provisi Anda, atau sertifikat perantara yang telah diunggah dan diverifikasi atau memiliki sertifikat dalam rantai penandatanganannya yang diunggah dan diverifikasi.
```
node create_enrollment_group.js "<connection string>" "<certificate .pem file>"
```
Jika pembuatan berhasil, jendela perintah menampilkan properti grup pendaftaran baru.

Dari folder azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample di prompt perintah Anda, jalankan perintah berikut untuk membuat sampel:
```
mvn install -DskipTests
```
Perintah ini mengunduh paket Maven klien layanan Azure IoT DPS ke komputer Anda dan membangun sampel. Paket ini mencakup biner untuk SDK layanan Java.
Beralih ke folder target dan jalankan sampel. Build dalam langkah sebelumnya menghasilkan file .jar di folder target dengan format file berikut: provisioning-x509-sample-{version}-with-deps.jar; misalnya: provisioning-x509-sample-1.8.1-with-deps.jar. Anda mungkin perlu mengganti versi dalam perintah di bawah ini.
```
cd target
java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar
```
Jika pembuatan berhasil, jendela perintah menampilkan properti grup pendaftaran baru.

Untuk memverifikasi bahwa grup pendaftaran telah dibuat:

Di portal Azure, navigasikan ke instans Device Provisioning Service Anda.
Di menu Pengaturan, pilih Kelola pendaftaran.
Pilih tab Grup pendaftaran. Anda akan melihat entri pendaftaran baru yang sesuai dengan ID grup pendaftaran yang Anda gunakan dalam sampel.

Cuplikan layar yang memperlihatkan grup pendaftaran yang baru dibuat di portal.

Membersihkan sumber daya

Jika Anda berencana untuk menjelajahi tutorial Azure IoT Hub Device Provisioning Service, jangan bersihkan sumber daya yang dibuat dalam artikel ini. Jika tidak, gunakan langkah-langkah berikut untuk menghapus semua sumber daya yang dibuat oleh artikel ini.

Tutup jendela output sampel di komputer Anda.
Dari menu sebelah kiri di portal Azure, pilih Semua sumber daya.
Pilih Device Provisioning Service Anda.
Di menu sebelah kiri di bawah Pengaturan, pilih Kelola pendaftaran.
Pilih tab Grup pendaftaran.
Pilih kotak centang di samping nama grup grup pendaftaran yang Anda buat di artikel ini.
Di bagian atas halaman, pilih Hapus.
Dari Device Provisioning Service Anda di portal Azure, pilih Sertifikat di bawah Pengaturan di menu sebelah kiri.
Pilih sertifikat yang Anda unggah untuk artikel ini.
Di bagian atas Detail sertifikat, pilih Hapus.

Peralatan sertifikat

Azure IoT C SDK memiliki skrip yang dapat membantu Anda membuat dan mengelola sertifikat. Untuk mempelajari selengkapnya, lihat Mengelola sertifikat CA pengujian untuk sampel dan tutorial.

Azure IoT Node.js SDK memiliki skrip yang dapat membantu Anda membuat dan mengelola sertifikat. Untuk mempelajari selengkapnya, lihat Alat untuk Azure IoT Device Provisioning Device SDK untuk Node.js.

Anda juga dapat menggunakan alat yang tersedia di Azure IoT C SDK. Untuk mempelajari selengkapnya, lihat Mengelola sertifikat CA pengujian untuk sampel dan tutorial.

Azure IoT Java SDK berisi alat pengujian yang dapat membantu Anda membuat dan mengelola sertifikat. Untuk mempelajari lebih lanjut, lihat Generator sertifikat X509 menggunakan emulator DICE.

Langkah berikutnya

Dalam artikel ini, Anda membuat grup pendaftaran untuk sertifikat OS menengah atau root X.509 menggunakan Azure IoT Hub Device Provisioning Service. Untuk menjelajahi lebih lanjut, lihat tautan berikut:

Untuk informasi selengkapnya tentang pengesahan sertifikat X.509 dengan DPS, lihat pengesahan sertifikat X.509.
Untuk contoh end-to-end provisi perangkat melalui grup pendaftaran menggunakan sertifikat X.509, lihat tutorial Memprovisikan beberapa perangkat X.509 menggunakan grup pendaftaran.
Untuk mempelajari tentang mengelola pendaftaran individu dan grup pendaftaran menggunakan portal Azure, lihat Cara mengelola pendaftaran perangkat dengan portal Azure.