Autenticación y autorización de llamadas API de REST en IoT Central

Article
03/01/2024

La API de REST de IoT Central permite desarrollar aplicaciones cliente que se integran con aplicaciones de IoT Central. Use la API de REST para trabajar con recursos de la aplicación de IoT Central, como plantillas de dispositivo, dispositivos, trabajos, usuarios y roles.

Cada llamada API de REST en IoT Central requiere un encabezado de autorización que IoT Central usa para determinar la identidad del autor de la llamada y los permisos que se conceden al autor de la llamada dentro de la aplicación.

En este artículo se describen los tipos de token que puede usar en el encabezado de autorización y cómo obtenerlos. Las entidades de servicio son el enfoque recomendado para la administración de acceso a la API de REST de IoT Central.

Tipos de token

Para acceder a la aplicación de IoT Central con la API de REST, puede usar lo siguiente:

Token al portador de Microsoft Entra. Un token al portador está asociado a una cuenta de usuario de Microsoft Entra o a un servicio principal. El token concede al autor de la llamada los mismos permisos que tiene el usuario o la entidad de servicio en la aplicación de IoT Central.
Token de API de IoT Central. Un token de API está asociado a un rol en la aplicación de IoT Central.

Use un token de portador asociado a su cuenta de usuario mientras desarrolla y prueba la automatización y los scripts que usan la API REST. Use un token de portador asociado a una entidad de servicio para la automatización y los scripts de producción. Use un token de portador en preferencia para un token de API para reducir el riesgo de fugas y problemas cuando expiren los tokens.

Para obtener más información sobre los usuarios y roles de IoT Central, vea Administrar usuarios y roles en la aplicación de IoT Central.

Obtención de un token de portador

Para obtener un token de portador para la cuenta de usuario de Microsoft Entra, use los siguientes comandos de la CLI de Azure:

az login
az account get-access-token --resource https://apps.azureiotcentral.com

Importante

El comando az login es necesario incluso si usa Cloud Shell.

La salida JSON del comando anterior es similar al ejemplo siguiente:

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

El token de portador es válido durante una hora aproximadamente, pero después debe crear otro.

Para obtener un token de portador para una entidad de servicio, consulte Autenticación de entidad de servicio.

Obtención de un token de API

Para obtener un token de API, puede usar la interfaz de usuario de IoT Central o una llamada API de REST. Los administradores asociados a la organización raíz y los usuarios asignados al rol correcto pueden crear tokens de API.

Sugerencia

Las operaciones de creación y eliminación en tokens de API se registran en el registro de auditoría.

En la interfaz de usuario de IoT Central:

Desplácese hasta Permisos > Tokens API.
Seleccione + Nuevo o en Crear un token de API.
Escriba un nombre para el token y seleccione un rol y una organización.
Seleccione Generar.
IoT Central muestra el token similar al ejemplo siguiente:

SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

Esta pantalla es la única vez que puede ver el token de API; si lo pierde, debe generar uno nuevo.

Un token de API es válido durante un año aproximadamente. Puede generar tokens para roles integrados y personalizados en la aplicación de IoT Central. La organización que elija al crear el token de API determina a qué dispositivos tiene acceso la API. Los tokens de API creados antes de agregar organizaciones a la aplicación están asociados a la organización raíz.

Puede eliminar tokens de API en la interfaz de usuario de IoT Central si necesita revocar el acceso.

Mediante la API de REST:

Use la API de REST para recuperar una lista de identificadores de rol de la aplicación:

GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-07-31

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

Use la API de REST para crear un token de API para un rol. Por ejemplo, para crear un token de API llamado operator-token para el rol de operador:

PUT https://{your app subdomain}.azureiotcentral.com/api/apiToken/operator-token?api-version=2022-07-31

Cuerpo de la solicitud:

{
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}

La respuesta al comando anterior es similar al siguiente elemento JSON:

{
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}

Esta respuesta es la única vez que tiene acceso al token de API, si lo pierde, debe generar uno nuevo.

Puede usar la API de REST para enumerar y eliminar tokens de API en una aplicación.

Uso de un token de portador

Para usar un token de portador al realizar una llamada API de REST, el encabezado de autorización tiene un aspecto similar al del ejemplo siguiente:

Authorization: Bearer eyJ0eX...fNQ

Uso de un token de API

Para usar un token de API al realizar una llamada API de REST, el encabezado de autorización tiene un aspecto similar al del ejemplo siguiente:

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889

Comparteix a través de