Cara menyambungkan perangkat dengan sertifikat X.509 ke Aplikasi IoT Central

  • Artikel

IoT Central mendukung tanda tangan akses bersama (SAS) dan sertifikat X.509 untuk mengamankan komunikasi antara perangkat dan aplikasi Anda. Tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central Anda menggunakan SAS. Dalam artikel ini, Anda akan mempelajari cara mengubah contoh kode untuk menggunakan sertifikat X.509. Sertifikat X.509 direkomendasikan untuk lingkungan produksi. Untuk informasi selengkapnya, lihat Konsep autentikasi perangkat.

Artikel ini menjelaskan dua cara menggunakan sertifikat X.509 - pendaftaran grup yang biasanya digunakan dalam lingkungan produksi, dan pendaftaran individu yang berguna untuk pengujian. Artikel ini juga menjelaskan cara menggulung sertifikat perangkat untuk mempertahankan konektivitas saat sertifikat kedaluwarsa.

Panduan ini dibangun berdasarkan sampel yang ditampilkan dalam tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central yang menggunakan C#, Java, JavaScript, dan Python. Untuk contoh yang menggunakan bahasa pemrograman C, lihat Memprovisikan beberapa perangkat X.509 menggunakan grup pendaftaran.

Prasyarat

Untuk menyelesaikan langkah-langkah dalam panduan ini, Anda harus terlebih dahulu menyelesaikan tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central Anda. Anda mengubah kode yang Anda gunakan dalam tutorial saat mengikuti langkah-langkah dalam panduan ini.

Dalam panduan cara ini, Anda menghasilkan beberapa sertifikat X.509 pengujian. Agar dapat menghasilkan sertifikat ini, Anda perlu:

  • Komputer pengembangan dengan Node.js versi 6 atau yang lebih baru diinstal. Anda dapat menjalankan node --version di baris perintah untuk memeriksa versi Anda. Instruksi dalam tutorial ini mengasumsikan Anda menjalankan perintah node pada perintah Windows. Namun, Anda dapat menggunakan Node.js di banyak sistem operasi lain.
  • Salinan lokal repositori GitHub Microsoft Azure IoT SDK untuk Node.js yang berisi skrip untuk mengasilkan sertifikat X.509 pengujian. Gunakan tautan ini untuk mengunduh salinan repositori: Unduh ZIP. Kemudian unzip file ke lokasi yang sesuai di komputer lokal Anda.

Menggunakan pendaftaran grup

Gunakan sertifikat X.509 dengan pendaftaran grup untuk lingkungan produksi. Dalam pendaftaran grup, Anda perlu menambahkan sertifikat X.509 root atau perantara ke aplikasi IoT Central Anda. Perangkat dengan sertifikat leaf yang berasal dari root atau sertifikat perantara dapat tersambung ke aplikasi Anda.

Membuat sertifikat akar dan perangkat

Pada bagian ini, Anda menggunakan sertifikat X.509 untuk menyambungkan perangkat dengan sertifikat yang berasal dari sertifikat grup pendaftaran IoT Central.

Peringatan

Cara pembuatan sertifikat X.509 ini hanya untuk pengujian. Untuk lingkungan produksi, Anda harus menggunakan mekanisme yang resmi dan aman untuk pembuatan sertifikat.

  1. Navigasikan ke skrip generator sertifikat di Microsoft Azure IoT SDK untuk Node.js yang Anda unduh. Instal paket yang diperlukan:

    cd azure-iot-sdk-node/provisioning/tools
npm install

  2. Buat sertifikat root dan buat sertifikat perangkat dengan menjalankan skrip:

    node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert

    Tip

    ID perangkat dapat menggunakan huruf, angka, dan karakter -.

Perintah ini menghasilkan akar berikut dan sertifikat perangkat:

filename konten
mytestrootcert_cert.pem Bagian publik dari sertifikat X509 akar
mytestrootcert_key.pem Kunci privat untuk sertifikat X509 akar
mytestrootcert_fullchain.pem Seluruh rantai kunci untuk sertifikat X509 akar.
mytestrootcert.pfx File PFX untuk sertifikat X509 akar.
sampleDevice01_cert.pem Bagian publik dari sertifikat X509 perangkat
sampleDevice01_key.pem Kunci privat untuk sertifikat X509 perangkat
sampleDevice01_fullchain.pem Seluruh rantai kunci untuk sertifikat X509 perangkat.
sampleDevice01.pfx File PFX untuk sertifikat X509 perangkat.

Catat lokasi file-file ini. Anda akan membutuhkannya nanti.

Buat pendaftaran grup

  1. Buka aplikasi IoT Central Anda dan navigasi ke Izin di panel kiri dan pilih Grup koneksi perangkat.

  2. Pilih + Baru untuk membuat grup pendaftaran baru yang disebut MyX509Group dengan jenis pengesahan Sertifikat (X.509). Anda dapat membuat grup pendaftaran untuk perangkat IoT atau perangkat IoT Edge.

  3. Di grup pendaftaran yang Anda buat, pilih Kelola utama.

  4. Di panel Sertifikat utama, pilih Tambahkan sertifikat.

  5. Unggah file sertifikat akar yang disebut mytestrootcert_cert.pem yang Anda buat sebelumnya.

  6. Jika Anda menggunakan otoritas sertifikat menengah atau akar yang Anda percayai dan tahu bahwa Anda memiliki kepemilikan penuh sertifikat, Anda dapat membuktikan sendiri bahwa Anda memverifikasi sertifikat dengan mengatur status sertifikat yang diverifikasi saat diunggah ke Aktif. Jika tidak, atur status sertifikat yang diverifikasi saat diunggah ke Nonaktif.

  7. Jika Anda mengatur status sertifikat yang diverifikasi saat diunggah ke Nonaktif, pilih Hasilkan kode verifikasi.

  8. Salin kode verifikasi, salin, lalu buat sertifikat verifikasi X.509. Misalnya, pada prompt perintah:

    node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}

  9. Pilih Verifikasi untuk mengunggah sertifikat verifikasi yang ditandatangani verification_cert.pem untuk menyelesaikan verifikasi.

  10. Status sertifikat utama sekarang Diverifikasi:

    Screenshot that shows a verified X509 certificate.

Anda kini dapat menyambungkan perangkat dengan sertifikat X.509 yang berasal dari sertifikat root utama ini.

Setelah Anda menyimpan grup pendaftaran, catat cakupan ID. Anda akan membutuhkannya nanti.

Jalankan contoh kode perangkat

Jika Anda menggunakan Windows, sertifikat X.509 harus berada di penyimpanan sertifikat Windows agar contoh dapat berfungsi. Di Windows Explorer, klik dua kali pada file PFX yang Anda buat sebelumnya - mytestrootcert.pfx dan sampleDevice01.pfx. Di Wizard Impor Sertifikat, pilih Pengguna Saat Ini sebagai lokasi penyimpanan, masukkan 1234 sebagai kata sandi, dan biarkan wizard memilih penyimpanan sertifikat secara otomatis. Wizard mengimpor sertifikat ke penyimpanan privat pengguna saat ini.

Untuk mengubah kode sampel untuk menggunakan sertifikat X.509:

  1. Di solusi Visual Studio IoTHubDeviceSamples, buka file Parameter.cs di proyek TemperatureController.

  2. Tambahkan dua definisi parameter berikut ke kelas:

    [Option(
    'x',
    "CertificatePath",
    HelpText = "(Required if DeviceSecurityType is \"dps\"). \nThe device PFX file to use during device provisioning." +
    "\nDefaults to environment variable \"IOTHUB_DEVICE_X509_CERT\".")]
public string CertificatePath { get; set; } = Environment.GetEnvironmentVariable("IOTHUB_DEVICE_X509_CERT");

[Option(
    'p',
    "CertificatePassword",
    HelpText = "(Required if DeviceSecurityType is \"dps\"). \nThe password of the PFX certificate file." +
    "\nDefaults to environment variable \"IOTHUB_DEVICE_X509_PASSWORD\".")]
public string CertificatePassword { get; set; } = Environment.GetEnvironmentVariable("IOTHUB_DEVICE_X509_PASSWORD");

    Simpan perubahan.

  3. Di solusi Visual Studio IoTHubDeviceSamples, buka file Program.cs di proyek TemperatureController.

  4. Tambahkan pernyataan using berikut:

    using System.Security.Cryptography.X509Certificates;
using System.IO;

  5. Tambahkan metode berikut ke kelas:

    private static X509Certificate2 LoadProvisioningCertificate(Parameters parameters)
{
    var certificateCollection = new X509Certificate2Collection();
    certificateCollection.Import(
        parameters.CertificatePath,
        parameters.CertificatePassword,
        X509KeyStorageFlags.UserKeySet);

    X509Certificate2 certificate = null;

    foreach (X509Certificate2 element in certificateCollection)
    {
        Console.WriteLine($"Found certificate: {element?.Thumbprint} {element?.Subject}; PrivateKey: {element?.HasPrivateKey}");
        if (certificate == null && element.HasPrivateKey)
        {
            certificate = element;
        }
        else
        {
            element.Dispose();
        }
    }

    if (certificate == null)
    {
        throw new FileNotFoundException($"{parameters.CertificatePath} did not contain any certificate with a private key.");
    }

    Console.WriteLine($"Using certificate {certificate.Thumbprint} {certificate.Subject}");

    return certificate;
}

  6. Di metode SetupDeviceClientAsync, ganti blok kode untuk case "dps" dengan kode berikut:

    case "dps":
    s_logger.LogDebug($"Initializing via DPS");
    Console.WriteLine($"Loading the certificate...");
    X509Certificate2 certificate = LoadProvisioningCertificate(parameters);
    DeviceRegistrationResult dpsRegistrationResult = await ProvisionDeviceAsync(parameters, certificate, cancellationToken);
    var authMethod = new DeviceAuthenticationWithX509Certificate(dpsRegistrationResult.DeviceId, certificate);
    deviceClient = InitializeDeviceClient(dpsRegistrationResult.AssignedHub, authMethod);
    break;

  7. Ganti metode ProvisionDeviceAsync dengan kode berikut:

    private static async Task<DeviceRegistrationResult> ProvisionDeviceAsync(Parameters parameters, X509Certificate2 certificate, CancellationToken cancellationToken)
{
    SecurityProvider security = new SecurityProviderX509Certificate(certificate);
    ProvisioningTransportHandler mqttTransportHandler = new ProvisioningTransportHandlerMqtt();
    ProvisioningDeviceClient pdc = ProvisioningDeviceClient.Create(parameters.DpsEndpoint, parameters.DpsIdScope, security, mqttTransportHandler);

    var pnpPayload = new ProvisioningRegistrationAdditionalData
    {
        JsonData = PnpConvention.CreateDpsPayload(ModelId),
    };
    return await pdc.RegisterAsync(pnpPayload, cancellationToken);
}

    Simpan perubahan.

Untuk menjalankan sampel:

  1. Tambahkan variabel lingkungan berikut ke proyek:

    • IOTHUB_DEVICE_X509_CERT: <full path to folder that contains PFX files>sampleDevice01.pfx
    • IOTHUB_DEVICE_X509_PASSWORD: 1234.

  2. Membuat dan menjalankan aplikasi. Verifikasi bahwa provisi perangkat telah berhasil.

Untuk mengubah kode sampel untuk menggunakan sertifikat X.509:

  1. Navigasikan ke folder azure-iot-sdk-java/device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample yang berisi file pom.xml dan folder src untuk contoh perangkat pengontrol suhu.

  2. Edit file pom.xml untuk menambahkan konfigurasi dependensi berikut di simpul <dependencies>:

    <dependency>
    <groupId>com.microsoft.azure.sdk.iot.provisioning.security</groupId>
    <artifactId>${x509-provider-artifact-id}</artifactId>
    <version>${x509-provider-version}</version>
</dependency>

    Simpan perubahan.

  3. Buka file src/main/java/samples/com/microsoft/azure/sdk/iot/device/TemperatureController.java di editor teks Anda.

  4. Ganti impor SecurityProviderSymmetricKey dengan impor berikut ini:

    import com.microsoft.azure.sdk.iot.provisioning.security.SecurityProvider;
import com.microsoft.azure.sdk.iot.provisioning.security.hsm.SecurityProviderX509Cert;
import com.microsoft.azure.sdk.iot.provisioning.security.exceptions.SecurityProviderException;

  5. Tambahkan impor berikut:

    import java.nio.file.*;

  6. Tambahkan SecurityProviderException ke daftar pengecualian yang ditampilkan metode main:

    public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningDeviceClientException, InterruptedException, SecurityProviderException {

  7. Ganti metode initializeAndProvisionDevice dengan kode berikut:

    private static void initializeAndProvisionDevice() throws ProvisioningDeviceClientException, IOException, URISyntaxException, InterruptedException, SecurityProviderException {
    String deviceX509Key = new String(Files.readAllBytes(Paths.get(System.getenv("IOTHUB_DEVICE_X509_KEY"))));
    String deviceX509Cert = new String(Files.readAllBytes(Paths.get(System.getenv("IOTHUB_DEVICE_X509_CERT"))));
    SecurityProvider securityProviderX509 = new SecurityProviderX509Cert(deviceX509Cert, deviceX509Key, null);
    ProvisioningDeviceClient provisioningDeviceClient;
    ProvisioningStatus provisioningStatus = new ProvisioningStatus();

    provisioningDeviceClient = ProvisioningDeviceClient.create(globalEndpoint, scopeId, provisioningProtocol, securityProviderX509);

    AdditionalData additionalData = new AdditionalData();
    additionalData.setProvisioningPayload(com.microsoft.azure.sdk.iot.provisioning.device.plugandplay.PnpHelper.createDpsPayload(MODEL_ID));

    provisioningDeviceClient.registerDevice(new ProvisioningDeviceClientRegistrationCallbackImpl(), provisioningStatus, additionalData);

    while (provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() != ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_ASSIGNED)
    {
        if (provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_ERROR ||
                provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_DISABLED ||
                provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_FAILED)
        {
            provisioningStatus.exception.printStackTrace();
            System.out.println("Registration error, bailing out");
            break;
        }
        System.out.println("Waiting for Provisioning Service to register");
        Thread.sleep(MAX_TIME_TO_WAIT_FOR_REGISTRATION);
    }

    ClientOptions options = new ClientOptions();
    options.setModelId(MODEL_ID);

    if (provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_ASSIGNED) {
        System.out.println("IotHUb Uri : " + provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getIothubUri());
        System.out.println("Device ID : " + provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getDeviceId());

        String iotHubUri = provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getIothubUri();
        String deviceId = provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getDeviceId();

        log.debug("Opening the device client.");
        deviceClient = DeviceClient.createFromSecurityProvider(iotHubUri, deviceId, securityProviderX509, IotHubClientProtocol.MQTT, options);
        deviceClient.open();
    }
}

    Simpan perubahan.

Untuk menjalankan sampel:

  1. Dalam lingkungan shell Anda, tambahkan dua variabel lingkungan berikut. Pastikan Anda memberikan jalur penuh ke file PEM dan gunakan pemisah jalur yang benar untuk sistem operasi Anda:

    set IOTHUB_DEVICE_X509_CERT=<full path to folder that contains PEM files>sampleDevice01_cert.pem
set IOTHUB_DEVICE_X509_KEY=<full path to folder that contains PEM files>sampleDevice01_key.pem

    Tip

    Atur variabel lingkungan lain yang diperlukan saat menyelesaikan tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central.

  2. Membuat dan menjalankan aplikasi. Verifikasi bahwa provisi perangkat telah berhasil.

Untuk mengubah kode sampel untuk menggunakan sertifikat X.509:

  1. Navigasi ke folder azure-iot-sdk-node/device/samples/javascript yang berisi aplikasi pnp_temperature_controller.js dan jalankan perintah berikut untuk menginstal paket X.509:

    npm install azure-iot-security-x509 --save

  2. Buka file pnp_temperature_controller.js di editor teks.

  3. Edit pernyataan require untuk menyertakan kode berikut:

    const fs = require('fs');
const X509Security = require('azure-iot-security-x509').X509Security;

  4. Tambahkan empat baris berikut ke bagian "Informasi koneksi DPS" untuk menginisialisasi variabel deviceCert:

    const deviceCert = {
  cert: fs.readFileSync(process.env.IOTHUB_DEVICE_X509_CERT).toString(),
  key: fs.readFileSync(process.env.IOTHUB_DEVICE_X509_KEY).toString()
};

  5. Edit fungsi provisionDevice untuk membuat klien dengan mengganti baris pertama dengan kode berikut:

    var provSecurityClient = new X509Security(registrationId, deviceCert);

  6. Dalam fungsi yang sama, ubah baris untuk mengatur variabel deviceConnectionString sebagai berikut:

    deviceConnectionString = 'HostName=' + result.assignedHub + ';DeviceId=' + result.deviceId + ';x509=true';

  7. Dalam fungsi main, tambahkan baris berikut setelah baris untuk memanggil Client.fromConnectionString:

    client.setOptions(deviceCert);

    Simpan perubahan.

Untuk menjalankan sampel:

  1. Dalam lingkungan shell Anda, tambahkan dua variabel lingkungan berikut. Pastikan Anda memberikan jalur penuh ke file PEM dan gunakan pemisah jalur yang benar untuk sistem operasi Anda:

    set IOTHUB_DEVICE_X509_CERT=<full path to folder that contains PEM files>sampleDevice01_cert.pem
set IOTHUB_DEVICE_X509_KEY=<full path to folder that contains PEM files>sampleDevice01_key.pem

    Tip

    Atur variabel lingkungan lain yang diperlukan saat menyelesaikan tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central.

  2. Jalankan skripnya dan verifikasi bahwa perangkat telah berhasil diprovisikan:

    node pnp_temperature_controller.js

Untuk mengubah kode sampel untuk menggunakan sertifikat X.509:

  1. Navigasikan ke folder azure-iot-device/samples/pnp dan buka file temp_controller_with_thermostats.py dalam editor teks.

  2. Tambahkan pernyataan from berikut untuk mengimpor fungsi X.509:

    from azure.iot.device import X509

  3. Ubah bagian pertama dari fungsi provision_device seperti berikut:

    async def provision_device(provisioning_host, id_scope, registration_id, x509, model_id):
    provisioning_device_client = ProvisioningDeviceClient.create_from_x509_certificate(
        provisioning_host=provisioning_host,
        registration_id=registration_id,
        id_scope=id_scope,
        x509=x509,
    )

  4. Dalam fungsi main, ubah baris yang mengatur variabel symmetric_key dengan kode berikut:

    x509 = X509(
    cert_file=os.getenv("IOTHUB_DEVICE_X509_CERT"),
    key_file=os.getenv("IOTHUB_DEVICE_X509_KEY"),
)

  5. Dalam fungsi main, ubah panggilan ke fungsi provision_device dengan kode berikut:

    registration_result = await provision_device(
    provisioning_host, id_scope, registration_id, x509, model_id
)

  6. Dalam fungsi main, ubah panggilan ke fungsi IoTHubDeviceClient.create_from_symmetric_key dengan kode berikut:

    device_client = IoTHubDeviceClient.create_from_x509_certificate(
    x509=x509,
    hostname=registration_result.registration_state.assigned_hub,
    device_id=registration_result.registration_state.device_id,
    product_info=model_id,
)

    Simpan perubahan.

Untuk menjalankan sampel:

  1. Dalam lingkungan shell Anda, tambahkan dua variabel lingkungan berikut. Pastikan Anda memberikan jalur penuh ke file PEM dan gunakan pemisah jalur yang benar untuk sistem operasi Anda:

    set IOTHUB_DEVICE_X509_CERT=<full path to folder that contains PEM files>sampleDevice01_cert.pem
set IOTHUB_DEVICE_X509_KEY=<full path to folder that contains PEM files>sampleDevice01_key.pem

    Tip

    Atur variabel lingkungan lain yang diperlukan saat menyelesaikan tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central.

  2. Jalankan skripnya dan verifikasi bahwa perangkat telah berhasil diprovisikan:

    python temp_controller_with_thermostats.py

Verifikasi bahwa telemetri muncul pada tampilan perangkat di aplikasi IoT Central Anda:

Screenshot showing telemetry from a device that connected using X.509.

Menggunakan pendaftaran individu

Gunakan sertifikat X.509 dengan pendaftaran individu untuk menguji perangkat dan solusi Anda. Untuk pendaftaran individu, tidak ada root atau sertifikat X.509 perantara di aplikasi IoT Central Anda. Perangkat menggunakan sertifikat X.509 yang ditandatangani sendiri untuk menyambungkan ke aplikasi Anda.

Membuat sertifikat perangkat yang ditandatangani sendiri

Pada bagian ini, Anda perlu menggunakan sertifikat X.509 yang ditandatangani sendiri untuk menyambungkan perangkat dengan pendaftaran individu, yang digunakan untuk mendaftarkan satu perangkat. Sertifikat yang ditandatangani sendiri hanya untuk pengujian.

Peringatan

Cara pembuatan sertifikat X.509 ini hanya untuk pengujian. Untuk lingkungan produksi, Anda harus menggunakan mekanisme yang resmi dan aman untuk pembuatan sertifikat.

Buat sertifikat perangkat X.509 yang ditandatangani sendiri dengan menjalankan perintah berikut:

  cd azure-iot-sdk-node/provisioning/tools
  node create_test_cert.js device mytestselfcertprimary
  node create_test_cert.js device mytestselfcertsecondary

Tip

ID perangkat dapat menggunakan huruf, angka, dan karakter -.

Perintah ini menghasilkan sertifikat perangkat berikut:

filename konten
mytestselfcertprimary_cert.pem Bagian publik dari sertifikat X509 perangkat utama
mytestselfcertprimary_key.pem Kunci privat untuk sertifikat X509 perangkat utama
mytestselfcertprimary_fullchain.pem Seluruh rantai kunci untuk sertifikat X509 perangkat utama.
mytestselfcertprimary.pfx File PFX untuk sertifikat X509 perangkat utama.
mytestselfcertsecondary_cert.pem Bagian publik dari sertifikat X509 perangkat sekunder
mytestselfcertsecondary_key.pem Kunci privat untuk sertifikat X509 perangkat sekunder
mytestselfcertsecondary_fullchain.pem Seluruh rantai kunci untuk sertifikat X509 perangkat sekunder.
mytestselfcertsecondary.pfx File PFX untuk sertifikat X509 perangkat sekunder.

Buat pendaftaran individu

  1. Di aplikasi Azure IoT Central, pilih Perangkat, dan buat perangkat baru dengan ID Perangkat sebagai mytestselfcertprimary dari templat perangkat termostat. Catat cakupan ID, Anda menggunakannya nanti.

  2. Buka perangkat yang Anda buat dan pilih Sambungkan.

  3. Pilih Pendaftaran individu sebagai Jenis autentikasi dan Sertifikat (X.509) sebagai metode Autentikasi.

  4. Unggah file mytestselfcertprimary_cert.pem yang Anda buat sebelumnya sebagai sertifikat utama.

  5. Unggah file mytestselfcertsecondary_cert.pem yang Anda buat sebelumnya sebagai sertifikat sekunder. Kemudian pilih Simpan.

  6. Perangkat sekarang memiliki pendaftaran individu dengan sertifikat X.509.

    Screenshot that shows how to connect a device using an X.509 individual enrollment.

Jalankan contoh perangkat pendaftaran individu

Jika Anda menggunakan Windows, sertifikat X.509 harus berada di penyimpanan sertifikat Windows agar contoh dapat berfungsi. Di Windows Explorer, klik dua kali pada file PFX yang Anda buat sebelumnya - mytestselfcertprimary.pfx dan mytestselfcertsecondary.pfx. Di Wizard Impor Sertifikat, pilih Pengguna Saat Ini sebagai lokasi penyimpanan, masukkan 1234 sebagai kata sandi, dan biarkan wizard memilih penyimpanan sertifikat secara otomatis. Wizard mengimpor sertifikat ke penyimpanan privat pengguna saat ini.

Untuk mengubah kode sampel untuk menggunakan sertifikat X.509:

  1. Di solusi Visual Studio IoTHubDeviceSamples, buka file Parameter.cs di proyek TemperatureController.

  2. Tambahkan dua definisi parameter berikut ke kelas:

    [Option(
    'x',
    "CertificatePath",
    HelpText = "(Required if DeviceSecurityType is \"dps\"). \nThe device PFX file to use during device provisioning." +
    "\nDefaults to environment variable \"IOTHUB_DEVICE_X509_CERT\".")]
public string CertificatePath { get; set; } = Environment.GetEnvironmentVariable("IOTHUB_DEVICE_X509_CERT");

[Option(
    'p',
    "CertificatePassword",
    HelpText = "(Required if DeviceSecurityType is \"dps\"). \nThe password of the PFX certificate file." +
    "\nDefaults to environment variable \"IOTHUB_DEVICE_X509_PASSWORD\".")]
public string CertificatePassword { get; set; } = Environment.GetEnvironmentVariable("IOTHUB_DEVICE_X509_PASSWORD");

    Simpan perubahan.

  3. Di solusi Visual Studio IoTHubDeviceSamples, buka file Program.cs di proyek TemperatureController.

  4. Tambahkan pernyataan using berikut:

    using System.Security.Cryptography.X509Certificates;
using System.IO;

  5. Tambahkan metode berikut ke kelas:

    private static X509Certificate2 LoadProvisioningCertificate(Parameters parameters)
{
    var certificateCollection = new X509Certificate2Collection();
    certificateCollection.Import(
        parameters.CertificatePath,
        parameters.CertificatePassword,
        X509KeyStorageFlags.UserKeySet);

    X509Certificate2 certificate = null;

    foreach (X509Certificate2 element in certificateCollection)
    {
        Console.WriteLine($"Found certificate: {element?.Thumbprint} {element?.Subject}; PrivateKey: {element?.HasPrivateKey}");
        if (certificate == null && element.HasPrivateKey)
        {
            certificate = element;
        }
        else
        {
            element.Dispose();
        }
    }

    if (certificate == null)
    {
        throw new FileNotFoundException($"{parameters.CertificatePath} did not contain any certificate with a private key.");
    }

    Console.WriteLine($"Using certificate {certificate.Thumbprint} {certificate.Subject}");

    return certificate;
}

  6. Di metode SetupDeviceClientAsync, ganti blok kode untuk case "dps" dengan kode berikut:

    case "dps":
    s_logger.LogDebug($"Initializing via DPS");
    Console.WriteLine($"Loading the certificate...");
    X509Certificate2 certificate = LoadProvisioningCertificate(parameters);
    DeviceRegistrationResult dpsRegistrationResult = await ProvisionDeviceAsync(parameters, certificate, cancellationToken);
    var authMethod = new DeviceAuthenticationWithX509Certificate(dpsRegistrationResult.DeviceId, certificate);
    deviceClient = InitializeDeviceClient(dpsRegistrationResult.AssignedHub, authMethod);
    break;

  7. Ganti metode ProvisionDeviceAsync dengan kode berikut:

    private static async Task<DeviceRegistrationResult> ProvisionDeviceAsync(Parameters parameters, X509Certificate2 certificate, CancellationToken cancellationToken)
{
    SecurityProvider security = new SecurityProviderX509Certificate(certificate);
    ProvisioningTransportHandler mqttTransportHandler = new ProvisioningTransportHandlerMqtt();
    ProvisioningDeviceClient pdc = ProvisioningDeviceClient.Create(parameters.DpsEndpoint, parameters.DpsIdScope, security, mqttTransportHandler);

    var pnpPayload = new ProvisioningRegistrationAdditionalData
    {
        JsonData = PnpConvention.CreateDpsPayload(ModelId),
    };
    return await pdc.RegisterAsync(pnpPayload, cancellationToken);
}

    Simpan perubahan.

Untuk menjalankan sampel:

  1. Tambahkan variabel lingkungan berikut ke proyek:

    • IOTHUB_DEVICE_DPS_DEVICE_ID: mytestselfcertprimary
    • IOTHUB_DEVICE_X509_CERT: <full path to folder that contains PFX files>mytestselfcertprimary.pfx
    • IOTHUB_DEVICE_X509_PASSWORD: 1234.

  2. Membuat dan menjalankan aplikasi. Verifikasi bahwa provisi perangkat telah berhasil.

Untuk mengubah kode sampel untuk menggunakan sertifikat X.509:

  1. Navigasikan ke folder azure-iot-sdk-java/device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample yang berisi file pom.xml dan folder src untuk contoh perangkat pengontrol suhu.

  2. Edit file pom.xml untuk menambahkan konfigurasi dependensi berikut di simpul <dependencies>:

    <dependency>
    <groupId>com.microsoft.azure.sdk.iot.provisioning.security</groupId>
    <artifactId>${x509-provider-artifact-id}</artifactId>
    <version>${x509-provider-version}</version>
</dependency>

    Simpan perubahan.

  3. Buka file src/main/java/samples/com/microsoft/azure/sdk/iot/device/TemperatureController.java di editor teks Anda.

  4. Ganti impor SecurityProviderSymmetricKey dengan impor berikut ini:

    import com.microsoft.azure.sdk.iot.provisioning.security.SecurityProvider;
import com.microsoft.azure.sdk.iot.provisioning.security.hsm.SecurityProviderX509Cert;
import com.microsoft.azure.sdk.iot.provisioning.security.exceptions.SecurityProviderException;

  5. Tambahkan impor berikut:

    import java.nio.file.*;

  6. Tambahkan SecurityProviderException ke daftar pengecualian yang ditampilkan metode main:

    public static void main(String[] args) throws IOException, URISyntaxException, ProvisioningDeviceClientException, InterruptedException, SecurityProviderException {

  7. Ganti metode initializeAndProvisionDevice dengan kode berikut:

    private static void initializeAndProvisionDevice() throws ProvisioningDeviceClientException, IOException, URISyntaxException, InterruptedException, SecurityProviderException {
    String deviceX509Key = new String(Files.readAllBytes(Paths.get(System.getenv("IOTHUB_DEVICE_X509_KEY"))));
    String deviceX509Cert = new String(Files.readAllBytes(Paths.get(System.getenv("IOTHUB_DEVICE_X509_CERT"))));
    SecurityProvider securityProviderX509 = new SecurityProviderX509Cert(deviceX509Cert, deviceX509Key, null);
    ProvisioningDeviceClient provisioningDeviceClient;
    ProvisioningStatus provisioningStatus = new ProvisioningStatus();

    provisioningDeviceClient = ProvisioningDeviceClient.create(globalEndpoint, scopeId, provisioningProtocol, securityProviderX509);

    AdditionalData additionalData = new AdditionalData();
    additionalData.setProvisioningPayload(com.microsoft.azure.sdk.iot.provisioning.device.plugandplay.PnpHelper.createDpsPayload(MODEL_ID));

    provisioningDeviceClient.registerDevice(new ProvisioningDeviceClientRegistrationCallbackImpl(), provisioningStatus, additionalData);

    while (provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() != ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_ASSIGNED)
    {
        if (provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_ERROR ||
                provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_DISABLED ||
                provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_FAILED)
        {
            provisioningStatus.exception.printStackTrace();
            System.out.println("Registration error, bailing out");
            break;
        }
        System.out.println("Waiting for Provisioning Service to register");
        Thread.sleep(MAX_TIME_TO_WAIT_FOR_REGISTRATION);
    }

    ClientOptions options = new ClientOptions();
    options.setModelId(MODEL_ID);

    if (provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_ASSIGNED) {
        System.out.println("IotHUb Uri : " + provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getIothubUri());
        System.out.println("Device ID : " + provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getDeviceId());

        String iotHubUri = provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getIothubUri();
        String deviceId = provisioningStatus.provisioningDeviceClientRegistrationInfoClient.getDeviceId();

        log.debug("Opening the device client.");
        deviceClient = DeviceClient.createFromSecurityProvider(iotHubUri, deviceId, securityProviderX509, IotHubClientProtocol.MQTT, options);
        deviceClient.open();
    }
}

    Simpan perubahan.

Untuk menjalankan sampel:

  1. Dalam lingkungan shell Anda, tambahkan dua variabel lingkungan berikut. Pastikan Anda memberikan jalur penuh ke file PEM dan gunakan pemisah jalur yang benar untuk sistem operasi Anda:

    set IOTHUB_DEVICE_DPS_DEVICE_ID=mytestselfcertprimary
set IOTHUB_DEVICE_X509_CERT=<full path to folder that contains PEM files>mytestselfcertprimary_cert.pem
set IOTHUB_DEVICE_X509_KEY=<full path to folder that contains PEM files>mytestselfcertprimary_key.pem

    Tip

    Atur variabel lingkungan lain yang diperlukan saat menyelesaikan tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central.

  2. Membuat dan menjalankan aplikasi. Verifikasi bahwa provisi perangkat telah berhasil.

Anda juga dapat mengulangi langkah-langkah di atas untuk sertifikat mytestselfcertsecondary.

Untuk mengubah kode sampel untuk menggunakan sertifikat X.509:

  1. Navigasi ke folder azure-iot-sdk-node/device/samples/javascript yang berisi aplikasi pnp_temperature_controller.js dan jalankan perintah berikut untuk menginstal paket X.509:

    npm install azure-iot-security-x509 --save

  2. Buka file pnp_temperature_controller.js di editor teks.

  3. Edit pernyataan require untuk menyertakan kode berikut:

    const fs = require('fs');
const X509Security = require('azure-iot-security-x509').X509Security;

  4. Tambahkan empat baris berikut ke bagian "Informasi koneksi DPS" untuk menginisialisasi variabel deviceCert:

    const deviceCert = {
  cert: fs.readFileSync(process.env.IOTHUB_DEVICE_X509_CERT).toString(),
  key: fs.readFileSync(process.env.IOTHUB_DEVICE_X509_KEY).toString()
};

  5. Edit fungsi provisionDevice untuk membuat klien dengan mengganti baris pertama dengan kode berikut:

    var provSecurityClient = new X509Security(registrationId, deviceCert);

  6. Dalam fungsi yang sama, ubah baris untuk mengatur variabel deviceConnectionString sebagai berikut:

    deviceConnectionString = 'HostName=' + result.assignedHub + ';DeviceId=' + result.deviceId + ';x509=true';

  7. Dalam fungsi main, tambahkan baris berikut setelah baris untuk memanggil Client.fromConnectionString:

    client.setOptions(deviceCert);

    Simpan perubahan.

Untuk menjalankan sampel:

  1. Dalam lingkungan shell Anda, tambahkan dua variabel lingkungan berikut. Pastikan Anda memberikan jalur penuh ke file PEM dan gunakan pemisah jalur yang benar untuk sistem operasi Anda:

    set IOTHUB_DEVICE_DPS_DEVICE_ID=mytestselfcertprimary
set IOTHUB_DEVICE_X509_CERT=<full path to folder that contains PEM files>mytestselfcertprimary_cert.pem
set IOTHUB_DEVICE_X509_KEY=<full path to folder that contains PEM files>mytestselfcertprimary_key.pem

    Tip

    Atur variabel lingkungan lain yang diperlukan saat menyelesaikan tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central.

  2. Jalankan skripnya dan verifikasi bahwa perangkat telah berhasil diprovisikan:

    node pnp_temperature_controller.js

Anda juga dapat mengulangi langkah-langkah di atas untuk sertifikat mytestselfcertsecondary.

Untuk mengubah kode sampel untuk menggunakan sertifikat X.509:

  1. Navigasikan ke folder azure-iot-device/samples/pnp dan buka file temp_controller_with_thermostats.py dalam editor teks.

  2. Tambahkan pernyataan from berikut untuk mengimpor fungsi X.509:

    from azure.iot.device import X509

  3. Ubah bagian pertama dari fungsi provision_device seperti berikut:

    async def provision_device(provisioning_host, id_scope, registration_id, x509, model_id):
    provisioning_device_client = ProvisioningDeviceClient.create_from_x509_certificate(
        provisioning_host=provisioning_host,
        registration_id=registration_id,
        id_scope=id_scope,
        x509=x509,
    )

  4. Dalam fungsi main, ubah baris yang mengatur variabel symmetric_key dengan kode berikut:

    x509 = X509(
    cert_file=os.getenv("IOTHUB_DEVICE_X509_CERT"),
    key_file=os.getenv("IOTHUB_DEVICE_X509_KEY"),
)

  5. Dalam fungsi main, ubah panggilan ke fungsi provision_device dengan kode berikut:

    registration_result = await provision_device(
    provisioning_host, id_scope, registration_id, x509, model_id
)

  6. Dalam fungsi main, ubah panggilan ke fungsi IoTHubDeviceClient.create_from_symmetric_key dengan kode berikut:

    device_client = IoTHubDeviceClient.create_from_x509_certificate(
    x509=x509,
    hostname=registration_result.registration_state.assigned_hub,
    device_id=registration_result.registration_state.device_id,
    product_info=model_id,
)

    Simpan perubahan.

Untuk menjalankan sampel:

  1. Dalam lingkungan shell Anda, tambahkan dua variabel lingkungan berikut. Pastikan Anda memberikan jalur penuh ke file PEM dan gunakan pemisah jalur yang benar untuk sistem operasi Anda:

    set IOTHUB_DEVICE_DPS_DEVICE_ID=mytestselfcertprimary
set IOTHUB_DEVICE_X509_CERT=<full path to folder that contains PEM files>mytestselfcertprimary_cert.pem
set IOTHUB_DEVICE_X509_KEY=<full path to folder that contains PEM files>mytestselfcertprimary_key.pem

    Tip

    Atur variabel lingkungan lain yang diperlukan saat menyelesaikan tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central.

  2. Jalankan skripnya dan verifikasi bahwa perangkat telah berhasil diprovisikan:

    python temp_controller_with_thermostats.py

Anda juga dapat mengulangi langkah-langkah di atas untuk sertifikat mytestselfcertsecondary.

Membuat perangkat IoT Edge

Bagian ini mengasumsikan Anda menggunakan pendaftaran grup untuk menyambungkan perangkat IoT Edge Anda. Ikuti langkah-langkah di bagian sebelumnya untuk:

Untuk menyambungkan perangkat IoT Edge ke IoT Central menggunakan sertifikat perangkat X.509:

  • Salin sertifikat perangkat dan file kunci ke perangkat IoT Edge Anda. Dalam contoh pendaftaran grup sebelumnya, file ini disebut sampleDevice01_key.pem dan sampleDevice01_cert.pem.

  • Pada perangkat IoT Edge, edit provisioning bagian di file konfigurasi /etc/aziot/config.toml sebagai berikut:

    # DPS X.509 provisioning configuration
provisioning:
  source: "dps"
  global_endpoint: "https://global.azure-devices-provisioning.net"
  scope_id: "<SCOPE_ID>"
  attestation:
    method: "x509"
#   registration_id: "<OPTIONAL REGISTRATION ID. LEAVE COMMENTED OUT TO REGISTER WITH CN OF identity_cert>"
    identity_cert: "file:///<path>/sampleDevice01_cert.pem"
    identity_pk: "file:///<path>/sampleDevice01_key.pem"
#  always_reprovision_on_startup: true
#  dynamic_reprovisioning: false

[provisioning]
source = "dps"
global_endpoint = "https://global.azure-devices-provisioning.net"
id_scope = "<SCOPE_ID>"

[provisioning.attestation]
method = "x509"
registration_id = "env-sens-001"
identity_pk = "file:///<path>/envSens001_key.pem"
identity_cert = "file:///<path>/envSens001_cert.pem"

    Tip

    Anda tidak perlu menambahkan nilai untuk registration_id. IoT Edge dapat menggunakan nilai CN dari sertifikat X.509.

  • Jalankan perintah berikut untuk memulai ulang runtime bahasa umum IoT Edge:

    sudo iotedge config apply

Untuk informasi selengkapnya, lihat Membuat dan memprovisikan perangkat IoT Edge menggunakan sertifikat X.509.

Koneksi perangkat hilir ke IoT Edge

IoT Edge menggunakan sertifikat X.509 untuk mengamankan koneksi antara perangkat hilir dan perangkat IoT Edge yang bertindak sebagai gateway transparan. Untuk mempelajari lebih lanjut tentang konfigurasi skenario ini, lihat Menyambungkan perangkat downstream ke gateway Azure IoT Edge.

Gulung sertifikat perangkat X.509 Anda

Selama siklus hidup aplikasi IoT Central, Anda mungkin perlu menggulung sertifikat X.509 Anda. Contohnya:

  • Jika Anda mengalami pelanggaran keamanan, menggulung sertifikat adalah praktik terbaik keamanan untuk membantu mengamankan sistem Anda.
  • Sertifikat X.509 memiliki tanggal kedaluwarsa. Frekuensi Anda menggulung sertifikat akan tergantung pada kebutuhan keamanan solusi Anda. Pelanggan dengan solusi yang melibatkan data yang sangat sensitif mungkin menggulung sertifikat setiap hari, sementara yang lain menggulirkan sertifikat mereka setiap beberapa tahun.

Untuk konektivitas tanpa gangguan, IoT Central memungkinkan Anda mengonfigurasi sertifikat X.509 primer dan sekunder. Jika sertifikat primer dan sekunder memiliki tanggal kedaluwarsa yang berbeda, Anda dapat menggulung sertifikat yang kedaluwarsa, sementara perangkat terus tersambung dengan sertifikat yang lain.

Untuk mempelajari selengkapnya, lihat Metodologi Asumsikan Pelanggaran.

Bagian ini menjelaskan cara menggulung sertifikat di IoT Central. Saat Anda menggulung sertifikat di IoT Central, Anda juga perlu menyalin sertifikat perangkat baru ke perangkat Anda.

Dapatkan sertifikat X.509 baru

Dapatkan sertifikat X.509 baru dari penyedia sertifikat Anda. Anda dapat membuat sertifikat X.509 Anda sendiri menggunakan alat seperti OpenSSL. Pendekatan ini sangat bagus untuk menguji sertifikat X.509, tetapi memberikan sedikit jaminan seputar keamanan. Hanya gunakan pendekatan ini untuk pengujian kecuali Anda siap untuk bertindak sebagai penyedia OS Anda sendiri.

Grup pendaftaran dan pelanggaran keamanan

Untuk memperbarui pendaftaran grup sebagai tanggapan atas pelanggaran keamanan, Anda harus menggunakan pendekatan berikut untuk segera memperbarui sertifikat saat ini. Selesaikan langkah-langkah ini untuk sertifikat primer dan sekunder, jika keduanya disusupi:

  1. Navigasi ke Izin di panel kiri dan pilih Grup koneksi perangkat.

  2. Pilih nama grup dalam daftar di bawah Grup pendaftaran.

  3. Untuk pembaruan sertifikat, pilih Kelola utama atau Kelola Sekunder.

  4. Tambahkan dan verifikasi sertifikat root X.509 di grup pendaftaran.

Pendaftaran individu dan pelanggaran keamanan

Jika Anda menggulung sertifikat sebagai tanggapan atas pelanggaran keamanan, gunakan pendekatan berikut untuk segera memperbarui sertifikat saat ini. Selesaikan langkah-langkah ini untuk sertifikat primer dan sekunder, jika keduanya disusupi:

  1. Pilih Perangkat,dan pilih perangkat.

  2. Pilih Sambungkan, dan pilih metode sambungkan sebagai Pendaftaran Individu

  3. Pilih Sertifikat (X.509) sebagai mekanisme.

  4. Untuk pembaruan sertifikat, pilih ikon folder untuk memilih sertifikat baru yang akan diunggah untuk entri pendaftaran. Pilih Simpan.

Grup pendaftaran dan kedaluwarsa sertifikat

Jika Anda menangani sertifikat yang kedaluwarsa, gunakan pendekatan berikut untuk segera memperbarui sertifikat saat ini:

  1. Navigasi ke Izin di panel kiri dan pilih Grup koneksi perangkat.

  2. Pilih nama grup dalam daftar di bawah Grup pendaftaran.

  3. Untuk pembaruan sertifikat, pilih Kelola Utama.

  4. Tambahkan dan verifikasi sertifikat root X.509 di grup pendaftaran.

  5. Kemudian ketika sertifikat sekunder kedaluwarsa, kembali dan perbarui sertifikat sekunder.

Pendaftaran individu dan kedaluwarsa sertifikat

Jika Anda menggulung sertifikat untuk menangani kedaluwarsa sertifikat, Anda harus menggunakan konfigurasi sertifikat sekunder sebagai berikut untuk mengurangi waktu henti bagi perangkat yang mencoba menyediakan dalam aplikasi Anda.

Ketika sertifikat sekunder mendekati kedaluwarsa, dan perlu digulirkan, Anda dapat memutar untuk menggunakan konfigurasi utama. Memutar antara sertifikat utama dan sekunder dengan cara ini mengurangi waktu henti untuk perangkat yang mencoba menyediakan di aplikasi Anda.

  1. Pilih Perangkat,dan pilih perangkat.

  2. Pilih Sambungkan, dan pilih metode sambungkan sebagai Pendaftaran Individu

  3. Pilih Sertifikat (X.509) sebagai mekanisme.

  4. Untuk pembaruan sertifikat, pilih ikon folder untuk memilih sertifikat baru yang akan diunggah untuk entri pendaftaran. Pilih Simpan.

  5. Kemudian ketika sertifikat primer telah kedaluwarsa, kembali dan perbarui sertifikat primer tersebut.