Crear y administrar las asignaciones de roles en Azure Digital Twins

Artículo
02/07/2020

Importante

Se ha publicado una nueva versión del servicio Azure Digital Twins. A la luz de las funcionalidades expandidas del nuevo servicio, se ha retirado el servicio original de Azure Digital Twins (descrito en este conjunto de documentación).

Para ver la documentación del nuevo servicio, visite la documentación activa de Azure Digital Twins.

Azure Digital Twins usa el control de acceso basado en rol (RBAC) para administrar el acceso a los recursos.

Información general sobre asignaciones de roles

Cada asignación de roles se ajusta a la siguiente definición:

{
  "roleId": "00e00ad7-00d4-4007-853b-b9968ad000d1",
  "objectId": "be2c6daa-a3a0-0c0a-b0da-c000000fbc5f",
  "objectIdType": "ServicePrincipalId",
  "path": "/",
  "tenantId": "00f000bf-86f1-00aa-91ab-2d7cd000db47"
}

En la tabla siguiente se describe cada atributo.

Atributo	Nombre	Obligatorio	Tipo	Descripción
roleId	Identificador de definición de rol	Sí	String	El identificador único de la asignación de roles deseada. Busque las definiciones de roles y su identificador consultando la API de sistema o revisando la siguiente tabla.
objectId	Identificador de objeto	Sí	String	Un identificador de Azure Active Directory, el identificador de objeto de la entidad de servicio o el nombre de dominio. ¿A qué o a quién se asignan los roles? La asignación de roles debe tener el formato en función del tipo asociado. Para el objectIdType `DomainName`, objectId debe comenzar con el carácter `“@”`.
objectIdType	Tipo de identificador de objeto	Sí	String	El tipo del identificador de objeto utilizado. Consulte ObjectIdTypes admitidos a continuación.
path	Ruta de acceso al espacio	Sí	String	Ruta de acceso completa al objeto `Space`. Un ejemplo es `/{Guid}/{Guid}`. Si un identificador necesita la asignación de roles para todo el grafo, especifique `"/"`. Este carácter designa la raíz, pero se desaconseja su uso. Siga siempre el principio de privilegio mínimo.
tenantId	Identificador de inquilino	Varía	String	En la mayoría de los casos, un identificador de inquilino de Azure Active Directory. No se permite para los ObjectIdType `DeviceId` y `TenantId`. Obligatorio para los ObjectIdType `UserId` y `ServicePrincipalId`. Opcional para el ObjectIdType DomainName.

Identificadores de definición de roles admitidos

Cada asignación de roles asocia una definición de rol a una entidad en el entorno de Azure Digital Twins.

En la tabla siguiente se describen los roles que están disponibles en Azure Digital Twins:

Rol	Descripción	Identificador
Administrador del espacio	Permiso CREAR, LEER, ACTUALIZAR y ELIMINAR para el espacio especificado y todos los nodos inferiores. Permiso global.	98e44ad7-28d4-4007-853b-b9968ad132d1
Administrador de usuarios	Permiso CREAR, LEER, ACTUALIZAR y ELIMINAR para usuarios y objetos relacionados con usuarios. Permiso READ para espacios.	dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac
Administrador de dispositivos	Permiso CREAR, LEER, ACTUALIZAR y ELIMINAR para dispositivos y objetos relacionados con dispositivos. Permiso READ para espacios.	3cdfde07-bc16-40d9-bed3-66d49a8f52ae
Administrador de claves	Permiso CREATE, READ, UPDATE y DELETE para las claves de acceso. Permiso READ para espacios.	5a0b1afc-e118-4068-969f-b50efb8e5da6
Administrador de tokens	Permiso LEER y ACTUALIZAR para las claves de acceso. Permiso READ para espacios.	38a3bb21-5424-43b4-b0bf-78ee228840c3
Usuario	Permiso LEER para espacios, sensores y usuarios, incluidos sus correspondientes objetos relacionados.	b1ffdb77-c635-4e7e-ad25-948237d85b30
Especialista de soporte técnico	Permiso LEER para todo, excepto las claves de acceso.	6e46958b-dc62-4e7c-990c-c3da2e030969
Instalador de dispositivos	Permiso LEER y ACTUALIZAR para dispositivos y sensores, incluidos sus correspondientes objetos relacionados. Permiso READ para espacios.	b16dd9fe-4efe-467b-8c8c-720e2ff8817c
Dispositivo de puerta de enlace	Permiso CREAR para sensores. Permiso READ para dispositivos y sensores, que incluye sus objetos relacionados correspondientes.	d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8

Tipos de identificadores de objetos admitidos

Anteriormente, se introdujo el atributo objectIdType.

objectIdType (o tipo de identificador de objeto) hace referencia al tipo de identidad que se asigna a un rol. Además de los tipos DeviceId y UserDefinedFunctionId, los tipos de identificador de objeto se corresponden con las propiedades de los objetos de Azure Active Directory.

En la tabla siguiente se incluyen los tipos de identificador de objeto admitidos en Azure Digital Twins:

Tipo	Descripción
UserId	Asigna un rol a un usuario.
deviceId	Asigna un rol a un dispositivo.
DomainName	Asigna un rol a un nombre de dominio. Cada usuario con el nombre de dominio especificado tiene los derechos de acceso del rol correspondiente.
TenantId	Asigna un rol a un inquilino. Cada usuario al que pertenezca el identificador de inquilino de Azure AD especificado tiene los derechos de acceso del rol correspondiente.
ServicePrincipalId	Asigna un rol a un identificador de objeto de entidad de servicio.
UserDefinedFunctionId	Asigna un rol a una función definida por el usuario (UDF).

Operaciones de asignación de roles

Azure Digital Twins admite operaciones completas CREATE, READ y DELETE para las asignaciones de roles. Las operaciones UPDATE se controlan mediante la adición de asignaciones de roles, la eliminación de asignaciones de roles o la modificación de los nodos de Spatial Intelligence Graph a los que dan acceso las asignaciones de roles.

La documentación de referencia de Swagger proporcionada contiene información adicional acerca de todos los puntos de conexión de API disponibles, las operaciones de solicitudes y las definiciones.

Sugerencia

Se proporciona un preestreno de Swagger para demostrar el conjunto de características de la API. Se hospeda en docs.westcentralus.azuresmartspaces.net/management/swagger.

Puede acceder a su propia documentación de Management API generada con Swagger en:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Nombre	Reemplazar por
YOUR_INSTANCE_NAME	El nombre de la instancia de Azure Digital Twins
YOUR_LOCATION	La región de servidor en la que está hospedada la instancia

En los ejemplos siguientes, YOUR_MANAGEMENT_API_URL hace referencia al identificador URI de la API de Digital Twins:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Nombre	Reemplazar por
YOUR_INSTANCE_NAME	El nombre de la instancia de Azure Digital Twins
YOUR_LOCATION	La región en la que está hospedada la instancia

Conceder permisos a la entidad de servicio

Conceder permisos a la entidad de servicio suele ser uno de los primeros pasos que debe realizar cuando trabaja con Azure Digital Twins. Esto implica:

Iniciar sesión en la instancia de Azure a mediante la CLI de Azure o PowerShell.
Adquirir la información de la entidad de servicio.
Asignar el rol deseado a la entidad de servicio.

El identificador de la aplicación se suministra en Azure Active Directory. Para obtener más información sobre la configuración y el aprovisionamiento de Azure Digital Twins en Active Directory, lea la Guía de inicio rápido.

Una vez que tenga el identificador de la aplicación, ejecute uno de los comandos siguientes. En la CLI de Azure:

az login
az ad sp show --id <ApplicationId>

En PowerShell:

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

Un usuario con el rol de administrador puede asignar el rol de administrador de espacio a un usuario mediante una solicitud HTTP POST autenticada a la dirección URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Con el siguiente cuerpo JSON:

{
  "roleId": "98e44ad7-28d4-4007-853b-b9968ad132d1",
  "objectId": "YOUR_SERVICE_PRINCIPLE_OBJECT_ID",
  "objectIdType": "ServicePrincipalId",
  "path": "YOUR_PATH",
  "tenantId": "YOUR_TENANT_ID"
}

Recuperar todos los roles

Para obtener una lista de todos los roles disponibles (definiciones de roles), realice una solicitud HTTP GET autenticada a:

YOUR_MANAGEMENT_API_URL/system/roles

Una solicitud correcta devolverá una matriz JSON con entradas para cada rol que puede asignarse:

[
    {
        "id": "3cdfde07-bc16-40d9-bed3-66d49a8f52ae",
        "name": "DeviceAdministrator",
        "permissions": [
            {
                "notActions": [],
                "actions": [
                    "Read",
                    "Create",
                    "Update",
                    "Delete"
                ],
                "condition": "@Resource.Type Any_of {'Device', 'DeviceBlobMetadata', 'DeviceExtendedProperty', 'Sensor', 'SensorBlobMetadata', 'SensorExtendedProperty'} || ( @Resource.Type == 'ExtendedType' && (!Exists @Resource.Category || @Resource.Category Any_of { 'DeviceSubtype', 'DeviceType', 'DeviceBlobType', 'DeviceBlobSubtype', 'SensorBlobSubtype', 'SensorBlobType', 'SensorDataSubtype', 'SensorDataType', 'SensorDataUnitType', 'SensorPortType', 'SensorType' } ) )"
            },
            {
                "notActions": [],
                "actions": [
                    "Read"
                ],
                "condition": "@Resource.Type == 'Space' && @Resource.Category == 'WithoutSpecifiedRbacResourceTypes' || @Resource.Type Any_of {'ExtendedPropertyKey', 'SpaceExtendedProperty', 'SpaceBlobMetadata', 'SpaceResource', 'Matcher'}"
            }
        ],
        "accessControlPath": "/system",
        "friendlyPath": "/system",
        "accessControlType": "System"
    }
]

Comprobar una asignación de roles específica

Para comprobar una asignación de roles específica, realice una solicitud HTTP GET autenticada a:

YOUR_MANAGEMENT_API_URL/roleassignments/check?userId=YOUR_USER_ID&path=YOUR_PATH&accessType=YOUR_ACCESS_TYPE&resourceType=YOUR_RESOURCE_TYPE

Valor del parámetro	Obligatorio	Tipo	Descripción
YOUR_USER_ID	True	String	El valor de objectId para el objectIdType UserId.
YOUR_PATH	True	String	La ruta de acceso elegida cuyo acceso se comprobará.
YOUR_ACCESS_TYPE	True	String	Read, Create, Update o Delete
YOUR_RESOURCE_TYPE	True	String	Device, DeviceBlobMetadata, DeviceExtendedProperty, ExtendedPropertyKey, ExtendedType, Endpoint, KeyStore, Matcher, Ontology, Report, RoleDefinition, Sensor, SensorExtendedProperty, Space, SpaceBlobMetadata, SpaceExtendedProperty, SpaceResource, SpaceRoleAssignment, System, UerDefinedFunction, User, UserBlobMetadata o UserExtendedProperty

Una solicitud correcta devolverá un valor booleano true o false para indicar si se ha asignado el tipo de acceso al usuario para el recurso y la ruta de acceso específica.

Obtener asignaciones de roles por ruta de acceso

Para obtener todas las asignaciones de roles por ruta de acceso, realice una solicitud HTTP GET autenticada a:

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

Valor	Reemplazar por
YOUR_PATH	Ruta de acceso completa al espacio

Una solicitud correcta devolverá una matriz JSON con cada asignación de roles asociada con el parámetro path seleccionado:

[
    {
        "id": "0000c484-698e-46fd-a3fd-c12aa11e53a1",
        "roleId": "98e44ad7-28d4-4007-853b-b9968ad132d1",
        "objectId": "0de38846-1aa5-000c-a46d-ea3d8ca8ee5e",
        "objectIdType": "UserId",
        "path": "/"
    }
]

Revocar un permiso

Para revocar un permiso de un destinatario, elimine la asignación de roles con una solicitud HTTP DELETE autenticada:

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

Parámetro	Reemplazar por
YOUR_ROLE_ASSIGNMENT_ID	El id de la asignación de roles que se quitará

Una solicitud DELETE correcta devolverá un estado de respuesta 204. Compruebe la eliminación de la asignación de roles comprobando si la asignación de roles aún sigue siendo válida.

Crear una asignación de rol

Para crear una asignación de roles, realice una solicitud HTTP GET autenticada a la URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Compruebe que el cuerpo JSON se ajuste al esquema siguiente:

{
  "roleId": "YOUR_ROLE_ID",
  "objectId": "YOUR_OBJECT_ID",
  "objectIdType": "YOUR_OBJECT_ID_TYPE",
  "path": "YOUR_PATH",
  "tenantId": "YOUR_TENANT_ID"
}

Una solicitud correcta devolverá un estado de respuesta 201 junto con el identificador de la asignación de roles recién creada:

"d92c7823-6e65-41d4-aaaa-f5b32e3f01b9"

Ejemplos de configuración

Los siguientes ejemplos muestran cómo configurar el cuerpo JSON en varios escenarios habituales de asignación de roles.

Ejemplo: un usuario necesita acceso administrativo a un piso de un espacio de inquilino.

{
  "roleId": "98e44ad7-28d4-4007-853b-b9968ad132d1",
  "objectId" : " 0fc863aa-eb51-4704-a312-7d635d70e000",
  "objectIdType" : "UserId",
  "tenantId": " a0c20ae6-e830-4c60-993d-a00ce6032724",
  "path": "/ 000e349c-c0ea-43d4-93cf-6b00abd23a44/ d84e82e6-84d5-45a4-bd9d-006a000e3bab"
}

Ejemplo: una aplicación ejecuta escenarios de prueba simulando dispositivos y sensores.

{
  "roleId": "98e44ad7-28d4-0007-853b-b9968ad132d1",
  "objectId" : "cabf7aaa-af0b-41c5-000a-ce2f4c20000b",
  "objectIdType" : "ServicePrincipalId",
  "tenantId": " a0c20ae6-e000-4c60-993d-a91ce6000724",
  "path": "/"
}

Ejemplo: todos los usuarios que forman parte de un dominio reciben acceso de lectura para espacios, sensores y usuarios. Este acceso incluye sus correspondientes objetos relacionados.
```
{
  "roleId": " b1ffdb77-c635-4e7e-ad25-948237d85b30",
  "objectId" : "@microsoft.com",
  "objectIdType" : "DomainName",
  "path": "/000e349c-c0ea-43d4-93cf-6b00abd23a00"
}
```

Pasos siguientes

Para revisar role-based-access-control de Azure Digital Twins, lea Role-base-access-control.
Para más información sobre la autenticación de la API de Azure Digital Twins, consulte el artículo sobre la autenticación en las API.

Compartir a través de