Compartir vía

Introducción a la integración de ADR y la administración de certificados X.509 respaldados por Microsoft en IoT Hub (versión preliminar)

En este artículo se explica cómo crear una nueva instancia de IoT Hub con la integración de Azure Device Registry (ADR) y la administración de certificados X.509 respaldada por Microsoft.

Importante

Azure IoT Hub con integración de ADR y administración de certificados X.509 respaldado por Microsoft está en versión preliminar pública y no se recomienda para cargas de trabajo de producción. Para más información, consulte las preguntas más frecuentes: Novedades de IoT Hub.

Prerrequisitos

  • Una suscripción de Azure activa. Si no tiene una suscripción a Azure, cree una cuenta gratuita.

  • Si no tiene instalada la CLI de Azure, siga los pasos para instalar la CLI de Azure.

  • Instale la extensión de la CLI de Azure IoT con versiones preliminares habilitadas para acceder a las funcionalidades de integración de ADR y administración de certificados para IoT Hub:

    1. Compruebe si hay instalaciones de extensiones de la CLI de Azure existentes.

      az extension list

    2. Quite las instalaciones existentes de Azure IoT.

      az extension remove --name azure-iot

    3. Instale la extensión azure-iot desde el índice con las previsualizaciones activadas.

      az extension add --name azure-iot --allow-preview

      o descargue el archivo .whl desde la página de versiones de GitHub para instalar la extensión manualmente.

      az extension add --upgrade --source https://github.com/Azure/azure-iot-cli-extension/releases/download/v0.30.0b1/azure_iot-0.30.0b1-py3-none-any.whl

    4. Después de la instalación, valide que la versión de la extensión azure-iot sea mayor que 0.30.0b1.

      az extension list

  • Asegúrese de que tiene el privilegio de realizar asignaciones de roles dentro del ámbito de destino. La realización de asignaciones de roles en Azure requiere un rol con privilegios, como propietario o administrador de acceso de usuario en el ámbito adecuado.

Elegir un método de implementación

Para usar la administración de certificados, también debe configurar IoT Hub, ADR y Device Provisioning Service (DPS). Si lo prefiere, puede optar por no habilitar la administración de certificados y configurar solo IoT Hub con ADR.

Para configurar IoT Hub con la integración de ADR y la administración de certificados, puede usar la CLI de Azure o un script que automatice el proceso de configuración.

Método de implementación Description
Seleccione la CLI de Azure en la parte superior de la página. Use la CLI de Azure para crear una instancia de IoT Hub, una instancia de DPS y un espacio de nombres de ADR y configurar todas las opciones necesarias.
Seleccione Script de PowerShell en la parte superior de la página. Use un script de PowerShell (solo Windows) para automatizar la creación de un nuevo centro de IoT Hub, una instancia de DPS y un espacio de nombres de ADR y configurar todas las opciones necesarias.

Información general

Use los comandos de la CLI de Azure para crear una instancia de IoT Hub con la integración de ADR y la administración de certificados.

El proceso de instalación de este artículo incluye los pasos siguientes:

  1. Creación de un grupo de recursos
  2. Configuración de los privilegios de aplicación necesarios
  3. Creación de una identidad administrada asignada por el usuario
  4. Creación de un espacio de nombres de ADR con identidad administrada asignada por el sistema
  5. Crear una credencial (CA raíz) y una directiva (CA emisora) limitadas a ese espacio de nombres
  6. Creación de una instancia de IoT Hub (versión preliminar) con un espacio de nombres vinculado e identidad administrada
  7. Crear un DPS con un IoT Hub vinculado y un espacio de nombres.
  8. Sincroniza tus credenciales y políticas (certificados de autoridad certificadora) al espacio de nombres de ADR
  9. Crear un grupo de inscripción y vincularlo con su directiva para habilitar el aprovisionamiento de certificados

Importante

Durante el período de versión preliminar, IoT Hub con características de integración de ADR y administración de certificados habilitadas sobre IoT Hub están disponibles de forma gratuita. Device Provisioning Service (DPS) se factura por separado y no se incluye en la oferta de versión preliminar. Para más información sobre los precios de DPS, consulte Precios de Azure IoT Hub.

Preparación del entorno

Para preparar el entorno para usar Azure Device Registry, complete los pasos siguientes:

  1. Abra una ventana de terminal.

  2. Para iniciar sesión en su cuenta de Azure, ejecute az login.

  3. Para enumerar todas las suscripciones e inquilinos a los que tiene acceso, ejecute az account list.

  4. Si tiene acceso a varias suscripciones de Azure, establezca la suscripción activa donde se crean los dispositivos IoT mediante la ejecución del comando siguiente.

    az account set --subscription "<your subscription name or ID>"

  5. Para mostrar los detalles de la cuenta actual, ejecute az account show. Copie ambos valores de la salida del comando y guárdelos en una ubicación segura.

    • El GUID de id. Este valor se usa para proporcionar el identificador de suscripción.
    • El GUID de tenantId. Use este valor para actualizar los permisos mediante el identificador de inquilino.

Configuración del grupo de recursos, los permisos y la identidad administrada

Para crear un grupo de recursos, un rol y permisos para la solución de IoT, complete los pasos siguientes:

  1. Cree un grupo de recursos para su entorno.

    az group create --name <RESOURCE_GROUP_NAME> --location <REGION>

  2. Asigne un rol colaborador a IoT Hub en el nivel de grupo de recursos. El valor AppId, que es el ID principal de IoT Hub, es 89d10474-74af-4874-99a7-c23c2f643083 y es el mismo para todas las aplicaciones del centro.

    az role assignment create --assignee "89d10474-74af-4874-99a7-c23c2f643083" --role "Contributor" --scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>"

  3. Cree una nueva identidad administrada asignada por el usuario (UAMI).

    az identity create --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME> --location <REGION>

  4. Recupere el Id. de recurso de la identidad administrada. Necesita el identificador de recurso para asignar roles, configurar directivas de acceso o vincular la identidad a otros recursos.

    UAMI_RESOURCE_ID=$(az identity show --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME> --query id -o tsv)

Creación de un nuevo espacio de nombres de ADR

En esta sección, crea un nuevo espacio de nombres de ADR con una identidad administrada asignada por el sistema. Este proceso genera automáticamente una credencial de entidad de certificación raíz y una directiva de entidad de certificación emisora para el espacio de nombres. Para obtener más información sobre cómo se usan las credenciales y directivas para firmar certificados de hoja del dispositivo durante el aprovisionamiento, consulte Administración de Certificados.

Nota:

Las credenciales son opcionales. También puede crear un espacio de nombres sin una identidad administrada si omite las banderas --enable-credential-policy y --policy-name.

  1. Cree un nuevo espacio de nombres de ADR. El espacio de nombres name solo puede contener letras minúsculas y guiones ("-") en el centro del nombre, pero no al principio o al final. Por ejemplo, el nombre "msft-namespace" es válido.
    El comando --enable-credential-policy crea credenciales (CA raíz) y directiva predeterminadas (CA emisora) para este espacio de nombres. Puede configurar el nombre de esta directiva mediante el --policy-name comando . De forma predeterminada, una directiva puede emitir certificados con una validez de 30 días.

    az iot adr ns create --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --location <REGION> --enable-credential-policy true --policy-name <POLICY_NAME>

    Sugerencia

    Opcionalmente, puede crear una directiva personalizada agregando los --cert-subject parámetros y --cert-validity-days . Para obtener más información, consulte Creación de una directiva personalizada.

    Nota:

    La creación del espacio de nombres de ADR con la identidad administrada asignada por el sistema puede tardar hasta 5 minutos.

  2. Compruebe que se crea el espacio de nombres con una identidad administrada asignada por el sistema, o un Id. de entidad de seguridad.

    az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  3. Compruebe que se crea una credencial y una directiva denominada.

    az iot adr ns credential show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot adr ns policy show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --name <POLICY_NAME>

    Nota:

    Si no asignó un nombre de directiva, la directiva se crea con el nombre "default".

Asignación de un rol de UAMI para acceder al espacio de nombres de ADR

En esta sección, asignará el rol Colaborador del Registro de dispositivos de Azure a la identidad administrada y la limitará al espacio de nombres. Este rol personalizado permite el acceso total a los dispositivos IoT dentro del espacio de nombres de ADR.

  1. Recupere el ID principal de la identidad administrada asignada por el usuario. Este identificador es necesario para asignar roles a la identidad.

    UAMI_PRINCIPAL_ID=$(az identity show --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP> --query principalId -o tsv)

  2. Recupere el identificador de recurso del espacio de nombres de ADR. Este id. se usa como ámbito para la asignación de roles.

    NAMESPACE_RESOURCE_ID=$(az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP> --query id -o tsv)

  3. Asigne el rol Colaborador de Azure Device Registry a la identidad administrada. Este rol concede a la identidad administrada los permisos necesarios, en el ámbito del espacio de nombres.

    az role assignment create --assignee $UAMI_PRINCIPAL_ID --role "a5c3590a-3a1a-4cd4-9648-ea0a32b15137" --scope $NAMESPACE_RESOURCE_ID

Creación de una instancia de IoT Hub con integración de ADR

  1. Crear un nuevo IoT Hub que esté asociado al espacio de nombres de ADR y con la UAMI creada anteriormente.

    az iot hub create --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --location <HUB_LOCATION> --sku GEN2 --mi-user-assigned $UAMI_RESOURCE_ID --ns-resource-id $NAMESPACE_RESOURCE_ID --ns-identity-id $UAMI_RESOURCE_ID

    Importante

    Como el centro de IoT se podrá detectar públicamente como un punto de conexión de DNS, asegúrese de que no incluye información de identificación personal ni información confidencial al asignarle un nombre.

  2. Compruebe que IoT Hub tiene configuradas las propiedades de identidad y ADR correctas.

    az iot hub show --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --query identity --output json

Asignación de roles de IoT Hub para acceder al espacio de nombres de ADR

  1. Obtenga el ID principal de la identidad administrada del espacio de nombres ADR. Esta identidad necesita permisos para interactuar con IoT Hub.

    ADR_PRINCIPAL_ID=$(az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP> --query identity.principalId -o tsv)

  2. Recupere el identificador de recurso de IoT Hub. Este id. se usa como ámbito para la asignación de roles.

    HUB_RESOURCE_ID=$(az iot hub show --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --query id -o tsv)

  3. Asigne el rol "Colaborador" a la identidad. Esto concede al colaborador de identidad administrada del espacio de nombres de ADR acceso al IoT Hub. Este rol permite un acceso amplio, incluida la administración de recursos, pero no la asignación de roles.

    az role assignment create --assignee $ADR_PRINCIPAL_ID --role "Contributor" --scope $HUB_RESOURCE_ID

  4. Asigne el rol "Colaborador del registro de IoT Hub" a la identidad de ADR. Esto concede permisos más específicos para administrar identidades de dispositivo en IoT Hub. Esto es esencial para que ADR registre y administre dispositivos en el centro.

    az role assignment create --assignee $ADR_PRINCIPAL_ID --role "IoT Hub Registry Contributor" --scope $HUB_RESOURCE_ID

Creación de una instancia de Device Provisioning Service con integración de ADR

  1. Cree una nueva instancia de DPS vinculada al espacio de nombres de ADR creado en las secciones anteriores. La instancia de DPS debe encontrarse en la misma región que el espacio de nombres de ADR.

    az iot dps create --name <DPS_NAME> --resource-group <RESOURCE_GROUP> --location <LOCATION> --mi-user-assigned $UAMI_RESOURCE_ID --ns-resource-id $NAMESPACE_RESOURCE_ID --ns-identity-id $UAMI_RESOURCE_ID

  2. Compruebe que DPS tiene configurada la identidad correcta y las propiedades de ADR.

    az iot dps show --name <DPS_NAME> --resource-group <RESOURCE_GROUP> --query identity --output json

  1. Vincula IoT Hub a DPS.

    az iot dps linked-hub create --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP> --hub-name <HUB_NAME>

  2. Compruebe que IoT Hub aparece en la lista de hubs vinculados para el DPS.

    az iot dps linked-hub list --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP>

Ejecución de la sincronización de credenciales de ADR

Sincronice las credenciales y directivas con IoT Hub. Este paso garantiza que IoT Hub registre los certificados de la autoridad de certificación y confíe en los certificados finales emitidos por las directivas configuradas.

az iot adr ns credential sync --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP>

Validar el certificado de la CA del hub

Verifique que su IoT Hub haya registrado su certificado CA.

az iot hub certificate list --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP>

Crear una inscripción en DPS

Para aprovisionar dispositivos utilizando certificados de hoja, cree un grupo de inscripción en DPS y asígnelo a la directiva de credenciales adecuada con el parámetro --credential-policy.

El comando siguiente crea un grupo de inscripción mediante la atestación de clave simétrica de forma predeterminada:

Nota:

Si creó una directiva con un nombre diferente de "valor predeterminado", asegúrese de usar ese nombre de directiva después del --credential-policy parámetro.

az iot dps enrollment-group create --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP> --enrollment-id <ENROLLMENT_ID> --credential-policy <POLICY_NAME>

La instancia de IoT Hub con la integración de ADR y la administración de certificados ahora está configurada y lista para su uso.

Comandos opcionales

Los siguientes comandos le ayudan a administrar los espacios de nombres de ADR, deshabilitar dispositivos, crear directivas personalizadas y eliminar recursos cuando ya no sean necesarios.

Administre sus espacios de nombres

  1. Enumere todos los namespaces del grupo de recursos.

    az iot adr ns list --resource-group <RESOURCE_GROUP_NAME>

  2. Mostrar detalles de un espacio de nombres específico.

    az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  3. Lista todas las políticas en tu espacio de nombres.

    az iot adr ns policy list --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  4. Mostrar detalles de una directiva específica.

    az iot adr ns policy show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --name <POLICY_NAME>

  5. Enumere todas las credenciales del espacio de nombres.

    az iot adr ns credential list --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

Deshabilitar dispositivos

  1. Enumere todos los dispositivos de IoT Hub.

    az iot hub device-identity list --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME>

  2. Deshabilite un dispositivo actualizando su estado a disabled. Asegúrese de reemplazar <MY_DEVICE_ID> por el identificador de dispositivo que desea deshabilitar.

    az iot hub device-identity update --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME> -d <MY_DEVICE_ID> --status disabled

  3. Vuelva a ejecutar el dispositivo y compruebe que no se puede conectar a una instancia de IoT Hub.

Creación de una directiva personalizada

Cree una directiva personalizada mediante el az iot adr ns policy create comando . Establezca el nombre, el firmante del certificado y el período de validez de la directiva siguiendo estas reglas:

  • El valor de la directiva name debe ser único dentro del espacio de nombres. Si intenta crear una directiva con un nombre que ya existe, recibirá un mensaje de error.
  • El valor del sujeto cert-subject del certificado debe ser único en todas las políticas del espacio de nombres. Si intenta crear una directiva con un asunto que ya existe, recibirá un mensaje de error.
  • El valor del período cert-validity-days de validez debe estar comprendido entre 1 y 30 días. Si intenta crear una directiva con un período de validez fuera de este intervalo, recibirá un mensaje de error.

En el ejemplo siguiente se crea una directiva denominada "custom-policy" con un asunto de "CN=TestDevice" y un período de validez de 30 días.

az iot adr ns policy create --name "custom-policy" --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --cert-subject "CN=TestDevice" --cert-validity-days "30"

Eliminar recursos

Para eliminar el espacio de nombres de ADR, primero debe eliminar las instancias de IoT Hub y DPS vinculadas al espacio de nombres.

az iot hub delete --name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot adr ns delete --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot dps delete --name <DPS_NAME> --resource-group <RESOURCE_GROUP_NAME> 
az identity delete --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME>

Información general

Use el script de PowerShell proporcionado para automatizar la configuración de IoT Hub con la integración de Azure Device Registry. El script realiza todos los pasos necesarios para crear los recursos necesarios y vincularlos juntos, incluidos:

  1. Creación de un grupo de recursos
  2. Configuración de los privilegios de aplicación necesarios
  3. Creación de una identidad administrada asignada por el usuario
  4. Creación de un espacio de nombres de ADR con identidad administrada asignada por el sistema
  5. Crear una credencial (CA raíz) y una directiva (CA emisora) limitadas a ese espacio de nombres
  6. Creación de una instancia de IoT Hub (versión preliminar) con un espacio de nombres vinculado e identidad administrada
  7. Crear un DPS con un IoT Hub vinculado y un espacio de nombres.
  8. Sincroniza tus credenciales y políticas (certificados de autoridad certificadora) al espacio de nombres de ADR
  9. Crear un grupo de inscripción y vincularlo con su directiva para habilitar el aprovisionamiento de certificados

Importante

Durante el período de versión preliminar, IoT Hub con características de integración de ADR y administración de certificados habilitadas sobre IoT Hub están disponibles de forma gratuita. Device Provisioning Service (DPS) se factura por separado y no se incluye en la oferta de versión preliminar. Para más información sobre los precios de DPS, consulte Precios de Azure IoT Hub.

Preparación del entorno

  1. Descargue PowerShell 7 para Windows.
  2. Vaya al repositorio de GitHub y descargue la carpeta Scripts , que contiene el archivo de script, iothub-adr-certs-setup-preview.ps1.

Personalización de las variables de script

Abra el archivo de script en un editor de texto y modifique las siguientes variables para que coincidan con la configuración deseada.

  • TenantId: tu ID de inquilino. Para encontrar este valor, ejecute az account show en el terminal.
  • SubscriptionId: identificador de suscripción. Para encontrar este valor, ejecute az account show en el terminal.
  • ResourceGroup: nombre del grupo de recursos.
  • Location: la región de Azure donde desea crear los recursos. Consulte las ubicaciones disponibles para ver las características en versión preliminar en la sección Regiones admitidas .
  • NamespaceName: el espacio de nombres solo puede contener letras minúsculas y guiones ("-") en el centro del nombre, pero no al principio o al final. Por ejemplo, "msft-namespace" es un nombre válido.
  • HubName: El nombre del hub solo puede contener letras minúsculas y números.
  • DpsName: El nombre de la instancia de Device Provisioning Service.
  • UserIdentity: La identidad administrada asignada por el usuario para tus recursos.
  • WorkingFolder: la carpeta local donde se encuentra el script.

Importante

Como el centro de IoT se podrá detectar públicamente como un punto de conexión de DNS, asegúrese de que no incluye información de identificación personal ni información confidencial al asignarle un nombre.

Ejecutar el script de forma interactiva

  1. Abra el script y ejecute en PowerShell 7+ como administrador. Vaya a la carpeta que contiene el script y ejecute .\iothub-adr-certs-setup-preview.ps1.

  2. Si se produce un problema de directiva de ejecución, intente ejecutar powershell -ExecutionPolicy Bypass -File .\iothub-adr-certs-setup-preview.ps1.

  3. Siga las indicaciones guiadas:

    • Presione Enter para continuar con un paso.
    • Presione s o S para omitir un paso.
    • Presione Ctrl + C para abortar

Nota:

La creación del espacio de nombres de ADR, IoT Hub, DPS y otros recursos puede llevar hasta 5 minutos cada uno.

Supervisión de la ejecución y validación de los recursos

  1. El script continúa la ejecución cuando se detectan advertencias y solo se detiene si un comando devuelve un código de salida distinto de cero. Supervise la consola para ver los mensajes de error rojos, que indican problemas que requieren atención.

  2. Una vez completado el script, valide la creación de los recursos visitando el nuevo grupo de recursos en Azure Portal. Debería ver los siguientes recursos creados:

    • Instancia de IoT Hub
    • Instancia del Servicio de Aprovisionamiento de Dispositivos (DPS)
    • Espacio de nombres de Azure Device Registry (ADR)
    • Identidad Administrada Asignada por el Usuario (UAMI)

Pasos siguientes

En este momento, la instancia de IoT Hub con la integración de ADR y la administración de certificados está configurada y lista para usarse. Ahora puede empezar a incorporar los dispositivos IoT al centro mediante la instancia de Device Provisioning Service (DPS) y administrar los dispositivos IoT de forma segura mediante las directivas e inscripciones que ha configurado.

Nuevo: la administración de certificados se admite en los SDK de dispositivo DPS seleccionados. Ahora puede incorporar dispositivos mediante la administración de certificados X.509 respaldada por Microsoft con los siguientes ejemplos de código del SDK:

  • Last updated on