Creación mediante programación de un grupo de inscripción de Device Provisioning Service para la atestación de certificados X.509

Artículo
03/19/2024

En este artículo se muestra cómo crear mediante programación un grupo de inscripción que usa certificados X.509 intermedios o raíces de una entidad de certificación. El grupo de inscripción se crea mediante el SDK del servicio DPS de Azure IoT Hub y un ejemplo de aplicación. Un grupo de inscripción controla el acceso al servicio de aprovisionamiento de los dispositivos que comparten un certificado de firma común en su cadena de certificados. Para obtener más información, consulte el artículo sobre cómo controlar el acceso a dispositivos con certificados X.509. Para más información sobre el uso de la infraestructura de clave pública (PKI) basada en certificados X.509 con Azure IoT Hub y el servicio Device Provisioning, consulte Introducción a la seguridad mediante certificados de entidades de certificación X.509.

Requisitos previos

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
Realice los pasos que se describen en Configuración de IoT Hub Device Provisioning Service con Azure Portal.

Instale el SDK de .NET 6.0 o versiones posteriores en una máquina con Windows. Para comprobar la versión, use el siguiente comando.
```
dotnet --info
```

Instale Node.js v4.0 o una versión posterior en la máquina.

Java SE Development Kit 8. En este artículo se usa el SDK de Azure IoT para Java, que funciona en Windows y Linux. En este artículo se usa Windows.
Maven 3.

Instale la última versión de Git. Asegúrese de que Git se ha agregado a las variables de entorno accesibles desde la ventana de comandos. Consulte las herramientas de cliente de Git de Software Freedom Conservancy para instalar la versión más reciente de las herramientas git, lo que incluye Git Bash, la aplicación de línea de comandos que puede usar para interactuar con su repositorio de Git local.

Nota:

Aunque los pasos de este artículo funcionan en equipos Windows y Linux, en este artículo se usa un equipo de desarrollo de Windows.

Creación de certificados de prueba

Los grupos de inscripción que usan la atestación de certificados X.509 se pueden configurar para usar un certificado de entidad de certificación raíz o un certificado intermedio. El caso más habitual es configurar el grupo de inscripción con un certificado intermedio. El uso de un certificado intermedio proporciona más flexibilidad, ya que el mismo certificado de CA raíz puede generar o revocar varios certificados intermedios.

Para este artículo, necesita un archivo de certificado de CA raíz, un archivo de certificado de CA intermedia o ambos en formato .pem o .cer. Un archivo contiene la parte pública del certificado X.509 de CA raíz y el otro contiene la parte pública del certificado X.509 de CA intermedio.

Si ya tiene un archivo de ENTIDAD de certificación raíz o un archivo de CA intermedio, puede proceder a agregar y comprobar el certificado de CA raíz o intermedio.

Si no tiene un archivo de ENTIDAD de certificación raíz o un archivo de CA intermedio, siga los pasos descritos en Creación de una cadena de certificados X.509 para crearlos. Puede detenerse después de completar los pasos descritos en Creación del certificado de entidad intermedia, ya que no necesita certificados de dispositivo para completar los pasos descritos en este artículo. Cuando haya terminado, tendrá dos archivos de certificado X.509: ./certs/azure-iot-test-only.root.ca.cert.pem y ./certs/azure-iot-test-only.intermediate.cert.pem.

Agregar y comprobar el certificado de CA raíz o intermedio

Los dispositivos que se aprovisionan a través de un grupo de inscripción mediante certificados X.509 presentan toda la cadena de certificados cuando se autentican con DPS. Para que el DPS pueda validar la cadena de certificados, la raíz o certificado intermedio configurados en un grupo de inscripción deben ser un certificado verificado o deben acumularse en un certificado verificado en la cadena de certificados que un dispositivo presenta al autenticarse con el servicio.

En este artículo, suponiendo que tenga un certificado de CA raíz y un certificado de CA intermedia firmado por la CA raíz:

Si planea crear el grupo de inscripción con el certificado de entidad de certificación raíz, debe cargar y comprobar el certificado de CA raíz.
Si planea crear el grupo de inscripción con el certificado de entidad de certificación intermedia, puede cargar y comprobar el certificado de CA raíz o el certificado de CA intermedio. (Si tiene varios certificados de ENTIDAD de certificación intermedios en la cadena de certificados, podría cargar y comprobar cualquier certificado intermedio que se encuentra entre el certificado de CA raíz y el certificado intermedio con el que se crea el grupo de inscripción).

Para agregar y comprobar el certificado de entidad de certificación raíz o intermedio al servicio Device Provisioning:

Inicie sesión en Azure Portal.
En el menú de la izquierda o en la página del portal, seleccione Todos los recursos.
Seleccione la instancia de Device Provisioning Service.
En el menú Configuración, seleccione Certificados.
En el menú superior, seleccione +Agregar:.
Escriba un nombre para el certificado de entidad de certificación raíz o intermedio y cargue el archivo .pem o .cer.
Seleccione Establecer el estado del certificado como comprobado al cargar.
Seleccione Guardar.

Obtención de la cadena de conexión para el servicio de aprovisionamiento

En el ejemplo de este artículo, necesita la cadena de conexión del servicio de aprovisionamiento. Siga estos pasos para recuperarlo.

Inicie sesión en Azure Portal.
En el menú de la izquierda o en la página del portal, seleccione Todos los recursos.
Seleccione la instancia de Device Provisioning Service.
En el menú Configuración, seleccione Directivas de acceso compartidas.
Seleccione la directiva de acceso que quiera usar.
En el panel Directiva de acceso, copie y guarde la cadena de conexión de la clave principal.

Crear el ejemplo del grupo de inscripción

En esta sección se muestra cómo crear una aplicación de consola de .NET Core que agrega un grupo de inscripción al servicio de aprovisionamiento.

Abra un símbolo del sistema de Windows y vaya a la carpeta donde quiera crear la aplicación.
Para crear un proyecto de consola, ejecute el siguiente comando:
```
dotnet new console --framework net6.0 --use-program-main 
```
Para agregar una referencia al SDK del servicio DPS, ejecute el siguiente comando:
```
dotnet add package Microsoft.Azure.Devices.Provisioning.Service 
```
Este paso permite descargar, instalar y agregar una referencia al paquete de cliente de servicio de NuGet de Azure IoT DPS y sus dependencias. Este paquete incluye los archivos binarios para el SDK del servicio .NET.
Abra el archivo Program.cs en un editor.
Reemplace la instrucción del espacio de nombres en la parte superior del archivo con la siguiente línea:
```
namespace CreateEnrollmentGroup;
```

Agregue las siguientes instrucciones using en la parte superior del archivo encima de la instrucción namespace:

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

Agregue los siguientes campos a la clase Program y realice los cambios indicados.
```
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}";
```
- Reemplace el valor del marcador de posición ProvisioningServiceConnectionString con la cadena de conexión del servicio de aprovisionamiento que copió en la sección anterior.
- Reemplace el valor del marcador de posición X509RootCertPath por la ruta de acceso a un archivo .pem o .cer. Este archivo representa la parte pública de un certificado X.509 de CA raíz que se ha cargado y comprobado previamente con el servicio de aprovisionamiento, o bien un certificado intermedio que se ha cargado y comprobado o que ha tenido un certificado en su cadena de firma cargado y comprobado.
- Tiene la opción de cambiar el valor EnrollmentGroupId. La cadena solo puede contener caracteres en minúsculas y guiones.
Importante

En el código de producción, tenga en cuenta las consideraciones de seguridad siguientes:
- La codificación de forma rígida de la cadena de conexión para el administrador del servicio de aprovisionamiento va contra los procedimientos recomendados de seguridad. En su lugar, la cadena de conexión debe mantenerse de forma segura, como en un archivo de configuración seguro o en el registro.
- Asegúrese de cargar solo la parte pública del certificado de firma. No cargue nunca archivos .pfx (PKCS12) o .pem que contengan claves privadas en el servicio de aprovisionamiento.

Agrega el método siguiente a la clase Program: Este código crea una entrada EnrollmentGroup y llama al método ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync para agregar el grupo de inscripción al servicio de aprovisionamiento.

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

    }
}

Por último, reemplace el método Main por las siguientes líneas:

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

Guarde los cambios.

En esta sección, se muestra cómo crear un script de Node.js que agregue un grupo de inscripción al servicio de aprovisionamiento.

Desde una ventana de comandos en la carpeta de trabajo, ejecute:
```
npm install azure-iot-provisioning-service
```
Este paso permite descargar, instalar y agregar una referencia al paquete de cliente de servicio de Azure IoT DPS y sus dependencias. Este paquete incluye los archivos binarios del SDK del servicio Node.js.

Con un editor de texto, cree un archivo create_enrollment_group.js en la carpeta de trabajo. Agregue el siguiente código al archivo y guárdelo:

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

Abra un símbolo del sistema de Windows.
Clone el repositorio de GitHub para código de ejemplo de inscripción de dispositivos mediante el SDK del servicio de Java:
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```

En la ubicación donde descargó el repositorio, vaya a la carpeta de muestra:

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

Abra el archivo /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java en el editor que prefiera.
Reemplace [Provisioning Connection String] por la cadena de conexión que copió en Obtención de la cadena de conexión del servicio de aprovisionamiento.
Reemplace la cadena constante PUBLIC_KEY_CERTIFICATE_STRING por el valor del archivo de certificado de entidad de certificación raíz o intermedio .pem. Este archivo representa la parte pública de un certificado X.509 de CA raíz que se ha cargado y comprobado previamente con el servicio de aprovisionamiento, o bien un certificado intermedio que se ha cargado y comprobado o que ha tenido un certificado en su cadena de firma cargado y comprobado.

La sintaxis del texto del certificado debe seguir el patrón que aparece a continuación, sin espacios adicionales ni caracteres.
```
private static final String PUBLIC_KEY_CERTIFICATE_STRING = 
        "-----BEGIN CERTIFICATE-----\n" +
        "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
            ...
        "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
        "-----END CERTIFICATE-----";
```
La actualización manual de este valor de cadena puede ser propensa a errores. Para generar la sintaxis adecuada, puede copiar y pegar el siguiente comando en un símbolo del sistema de Git Bash, reemplazar your-cert.pem por la ubicación del archivo de certificado y presionar ENTRAR. Este comando genera la sintaxis para el valor de constante de la cadena PUBLIC_KEY_CERTIFICATE_STRING y la escribe en la salida.
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' your-cert.pem
```
Copie y pegue el texto del certificado de salida para el valor de constante.
Importante

En el código de producción, tenga en cuenta las consideraciones de seguridad siguientes:
- La codificación de forma rígida de la cadena de conexión para el administrador del servicio de aprovisionamiento va contra los procedimientos recomendados de seguridad. En su lugar, la cadena de conexión debe mantenerse de forma segura, como en un archivo de configuración seguro o en el registro.
- Asegúrese de cargar solo la parte pública del certificado de firma. No cargue nunca archivos .pfx (PKCS12) o .pem que contengan claves privadas en el servicio de aprovisionamiento.
El ejemplo permite establecer un centro de IoT en el grupo de inscripción en el que aprovisionar el dispositivo. Debe ser un centro de IoT que se haya vinculado previamente al servicio de aprovisionamiento. En este artículo, permitiremos que DPS elija entre los centros vinculados según la distribución ponderada uniformemente de la directiva de asignación predeterminada. Escriba la siguiente instrucción en el archivo:
```
enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);                // Optional parameter.
```
El código del ejemplo crea, actualiza, consulta y elimina un grupo de inscripción para dispositivos X.509. Para comprobar la creación correcta del grupo de inscripción en Azure Portal, escriba las siguientes líneas de código cerca del final del archivo:
```
// ************************************** Delete info of enrollmentGroup ***************************************
System.out.println("\nDelete the enrollmentGroup...");
provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);
```
Guarde el archivo ServiceEnrollmentGroupSample.java.

Ejecutar el ejemplo del grupo de inscripción

Ejecución del ejemplo:
```
dotnet run
```
Si se realiza una creación correcta, la ventana de comandos muestra las propiedades del grupo de inscripción nuevo.

Ejecute el siguiente comando en el símbolo del sistema. Incluya comillas alrededor de los argumentos de comando y reemplace <connection string> por la cadena de conexión que copió en la sección anterior y <certificate .pem file> por la ruta de acceso al archivo de certificado .pem. Este archivo representa la parte pública de un certificado X.509 de CA raíz que se ha cargado y comprobado previamente con el servicio de aprovisionamiento, o bien un certificado intermedio que se ha cargado y comprobado o que ha tenido un certificado en su cadena de firma cargado y comprobado.
```
node create_enrollment_group.js "<connection string>" "<certificate .pem file>"
```
Si se realiza una creación correcta, la ventana de comandos muestra las propiedades del grupo de inscripción nuevo.

En la carpeta azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample del símbolo del sistema, ejecute el siguiente comando para compilar el ejemplo:
```
mvn install -DskipTests
```
Este comando descarga el paquete de Maven de cliente de servicio Azure IoT DPS en la máquina y compila la muestra. Este paquete incluye los archivos binarios para el SDK de servicio de Java.
Cambie a la carpeta target y ejecute la muestra. La compilación del paso anterior genera el archivo .jar en la carpeta target con el siguiente formato de archivo: provisioning-x509-sample-{version}-with-deps.jar; por ejemplo: provisioning-x509-sample-1.8.1-with-deps.jar. Es posible que tenga que reemplazar la versión en el comando siguiente.
```
cd target
java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar
```
Si se realiza una creación correcta, la ventana de comandos muestra las propiedades del grupo de inscripción nuevo.

Compruebe que se ha creado el grupo de inscripción:

En Azure Portal, vaya a la instancia de Device Provisioning Service (DPS).
En el menú de Configuración, seleccione Administrar inscripciones.
Seleccione la pestaña Grupos de inscripción. Debería ver una nueva entrada de inscripción que corresponda al identificador de grupo de inscripción que usó en el ejemplo.

Captura de pantalla que muestra el grupo de inscripción recién creado en el portal.

Limpieza de recursos

Si planea explorar los tutoriales de Azure IoT Hub Device Provisioning Service, no elimine los recursos creados en este artículo. De lo contrario, use el siguiente comando para eliminar todos los recursos creados en este artículo.

Cierre la ventana de salida de ejemplo en el equipo.
En Azure Portal, seleccione Todos los recursos en el menú de la izquierda.
Seleccione la instancia de Device Provisioning Service.
En el menú de la izquierda, en Configuración, seleccione Administrar inscripciones.
Seleccione la pestaña Grupos de inscripción.
Active la casilla situada junto al nombre de grupo del grupo de inscripción que creó en este artículo.
En la parte superior de la página, seleccione Eliminar.
En device Provisioning Service en el Azure Portal, seleccione Certificados en Configuración en el menú de la izquierda.
Seleccione el certificado que cargó para este artículo.
En la parte superior de Detalles del certificado, seleccione Eliminar.

Herramientas de certificado

El SDK de C de Azure IoT tiene scripts que pueden ayudarle a crear y administrar certificados. Para más información, consulte Administración de certificados de entidad de certificación de prueba para ver ejemplos y tutoriales.

El SDK de Node.js de Azure IoT tiene scripts que pueden ayudarle a crear y administrar certificados. Para más información, consulte Herramientas para el SDK de dispositivo de aprovisionamiento de dispositivos de Azure IoT para Node.js.

También puede usar herramientas disponibles en Azure IoT C SDK. Para más información, consulte Administración de certificados de entidad de certificación de prueba para ver ejemplos y tutoriales.

El SDK de Java de Azure IoT contiene herramientas de prueba que pueden ayudarle a crear y administrar certificados. Para más información, consulte el Generador de certificados X509 mediante el emulador de DICE.

Pasos siguientes

En este artículo, ha creado un grupo de inscripción para un certificado X.509 de entidad de certificación intermedio o raíz mediante Azure IoT Hub Device Provisioning Service. Para más información, consulte los siguientes enlaces:

Para más información sobre la atestación de certificados X.509 con DPS, consulte Atestación de certificados X.509.
Para obtener un ejemplo completo de aprovisionamiento de dispositivos a través de un grupo de inscripción mediante certificados X.509, consulte el tutorial Aprovisionamiento de varios dispositivos X.509 mediante grupos de inscripción.
Para obtener información sobre cómo administrar inscripciones individuales y grupos de inscripción mediante Azure Portal, consulte Administración de inscripciones de dispositivos con Azure Portal.

Share via