Criar e gerenciar atribuições de função nos Gêmeos Digitais do Azure

Artigo
02/07/2020

Importante

Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz das funcionalidades expandidas do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.

Para exibir a documentação do novo serviço, visite a Documentação ativa dos Gêmeos Digitais do Azure.

Os Gêmeos Digitais do Azure usam RBAC (controle de acesso baseado em função) para gerenciar o acesso aos recursos.

Visão geral das atribuições de função

Cada atribuição de função está em conformidade com a seguinte definição:

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

A tabela abaixo descreve cada atributo:

Atributo	Nome	Obrigatório	Type	Descrição
roleId	Identificador de definição de função	Sim	String	A ID exclusiva da atribuição de função desejada. Encontre definições de funções e seus identificadores consultando a API do Sistema ou examinando a tabela abaixo.
objectId	Identificador de objeto	Sim	String	Uma ID do Azure Active Directory, ID de objeto de entidade de serviço ou nome de domínio. Para o que atribuições de função é atribuída. A atribuição de função precisa ser formatada de acordo com seu tipo associado. Para o ObjectIdType `DomainName`, ObjectId precisa começar com o caractere `“@”`.
objectIdType	Tipo de identificador de objeto	Sim	String	O tipo de identificador de Objeto usado. Consulte ObjectIdTypes com suporte abaixo.
caminho	Caminho de espaço	Sim	String	O caminho de acesso completo para o objeto `Space`. Um exemplo é `/{Guid}/{Guid}`. Se um identificador precisar da atribuição de função para todo o gráfico, especifique `"/"`. Esse caractere designa a raiz, mas seu uso é desencorajado. Sempre siga o princípio de privilégios mínimos.
tenantId	Identificador de locatário	Varia	String	Na maioria dos casos, uma ID de locatário do Azure Active Directory. Não permitido para ObjectIdTypes `DeviceId` e `TenantId`. Obrigatório para ObjectIdTypes `UserId` e `ServicePrincipalId`. Opcional para o ObjectIdType DomainName.

Identificadores de definição de função com suporte

Cada atribuição de função associa uma definição de função a uma entidade no dos Gêmeos Digitais do Azure.

A tabela a seguir descreve as funções que estão disponíveis no Gêmeos Digitais do Azure:

Função	Descrição	Identificador
Administrador de Espaço	Permissão CREATE, READ, UPDATE e DELETE para o espaço especificado e todos os nós abaixo. Permissão global.	98e44ad7-28d4-4007-853b-b9968ad132d1
Administrador de usuários	Permissão CREATE, READ, UPDATE e DELETE para usuários e objetos relacionados ao usuário. Permissão READ para espaços.	dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac
Administrador de Dispositivo	Permissão CREATE, READ, UPDATE e DELETE para dispositivos e objetos relacionados aos dispositivos. Permissão READ para espaços.	3cdfde07-bc16-40d9-bed3-66d49a8f52ae
Administrador de Chave	Permissão CREATE, READ, UPDATE e DELETE para chaves de acesso. Permissão READ para espaços.	5a0b1afc-e118-4068-969f-b50efb8e5da6
Administrador de Token	Permissão READ e UPDATE para chaves de acesso. Permissão READ para espaços.	38a3bb21-5424-43b4-b0bf-78ee228840c3
Usuário	Permissão READ para espaços, sensores e usuários, incluindo seus respectivos objetos relacionados.	b1ffdb77-c635-4e7e-ad25-948237d85b30
Especialista de Suporte	Permissão READ para tudo, exceto chaves de acesso.	6e46958b-dc62-4e7c-990c-c3da2e030969
Instalador do Dispositivo	Permissão READ e UPDATE para dispositivos e sensores, incluindo seus respectivos objetos relacionados. Permissão READ para espaços.	b16dd9fe-4efe-467b-8c8c-720e2ff8817c
Dispositivos de gateway	Permissão CREATE para sensores. Permissão READ para dispositivos e sensores, que inclui seus objetos relacionados correspondentes.	d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8

Tipos de identificador de objeto com suporte

Anteriormente, o atributo objectIdType foi introduzido.

O objectIdType (ou tipo de identificador de objeto) refere-se ao tipo de identidade que é dada a uma função. Além dos tipos DeviceId e UserDefinedFunctionId, os tipos de identificador de objeto correspondem às propriedades dos objetos do Azure Active Directory.

A tabela a seguir contém os tipos de identificador de objeto com suporte no Gêmeos Digitais do Azure:

Type	Descrição
UserId	Atribui uma função a um usuário.
deviceId	Atribui uma função a um dispositivo.
DomainName	Atribui uma função a um nome de domínio. Cada usuário com o nome de domínio especificado possui os direitos de acesso da função correspondente.
TenantId	Atribui uma função a um locatário. Cada usuário que pertence ao ID de locatário do Microsoft Azure Active Directory especificado tem os direitos de acesso da função correspondente.
ServicePrincipalId	Atribui uma função a uma ID de objeto de entidade de serviço.
UserDefinedFunctionId	Atribui uma função a uma UDF (função definida pelo usuário).

Operações de atribuição de função

Os Gêmeos Digitais do Azure oferecem suporte para operações CREATE, READ e DELETE completas para atribuições de função. As operações UPDATE são tratadas pela adição de atribuições de função, remoção de atribuições de função, ou modificação de nós Spatial Intelligence Graph aos quais as atribuições de função concedem acesso.

A documentação de referência do Swagger fornecida contém informações adicionais sobre todos os pontos de extremidade disponíveis, operações de solicitação e definições da API.

Dica

Uma versão prévia do Swagger é fornecida para demonstrar o conjunto de recursos da API. Ele está hospedado no docs.westcentralus.azuresmartspaces.net/management/swagger.

Você pode acessar sua própria documentação de Swagger da API de gerenciamento gerada em:

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

Nome	Substitua por
NOME_DA_SUA_INSTÂNCIA	O nome da sua instância de Gêmeos Digitais do Azure
SUA_LOCALIZAÇÃO	Em qual região do servidor de sua instância está hospedada

Nos exemplos a seguir, YOUR_MANAGEMENT_API_URL refere-se ao URI de APIs de Gêmeos Digitais:

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

Nome	Substitua por
NOME_DA_SUA_INSTÂNCIA	O nome da sua instância de Gêmeos Digitais do Azure
SUA_LOCALIZAÇÃO	A região em que sua instância está hospedada

Conceder permissões para a entidade de serviço

Conceder permissões à entidade de serviço geralmente é uma das primeiras etapas que você usará ao trabalhar com os Gêmeos Digitais do Azure. Isso envolve:

Faça logon em sua instância do Azure por meio da CLI do Azure ou do PowerShell.
Adquirir informações da sua entidade de serviço.
Atribuir a função desejada para sua entidade de serviço.

Sua ID de aplicativo é fornecida no Azure Active Directory. Para saber mais informações sobre como configurar e provisionar um Gêmeos Digitais do Azure no Active Directory, leia o Início Rápido.

Depois de ter a ID do aplicativo, execute um dos comandos a seguir. Na CLI do Azure:

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

No Powershell:

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

Um usuário com a função Admin pode então atribuir a função Administrador de Espaço para um usuário, fazendo uma solicitação HTTP POST autenticada para a URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Com o corpo JSON a seguir:

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

Recuperar todas as funções

Para listar todas as funções disponíveis (definições de função), faça uma solicitação HTTP GET autenticada para:

YOUR_MANAGEMENT_API_URL/system/roles

Uma solicitação com êxito retornará uma matriz JSON com as entradas para cada função que pode ser atribuída:

[
    {
        "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"
    }
]

Verificar uma atribuição de função específica

Para verificar uma atribuição de função específica, faça uma solicitação HTTP GET autenticada para:

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

Valor de parâmetro	Necessário	Tipo	Descrição
YOUR_USER_ID	True	String	A objectId para o UserId objectIdType.
YOUR_PATH	True	String	O caminho escolhido para verificar o acesso.
YOUR_ACCESS_TYPE	True	String	Ler, criar, atualizar ou excluir
YOUR_RESOURCE_TYPE	True	String	Device, DeviceBlobMetadata, DeviceExtendedProperty, ExtendedPropertyKey, ExtendedType, Endpoint, KeyStore, Matcher, Onlogy, Report, RoleDefinition, Sensor, SensorExtendedProperty, Space, SpaceBlobMetadata, SpaceExtendedProperty, SpaceResource, SpaceRoleAssignment, System, UerDefinedFunction, User, UserBlobMetadata ou UserExtendedProperty

Uma solicitação bem-sucedida retornará um booliano true ou false para indicar se o tipo de acesso foi atribuído ao usuário para o caminho especificado e o recurso determinado.

Obter atribuições de função por caminho

Para obter todas as atribuições de função para um caminho, faça uma solicitação HTTP GET autenticada para:

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

Valor	Substitua por
YOUR_PATH	O caminho completo para o espaço

Uma solicitação com êxito retornará uma matriz JSON com cada atribuição de função associada ao parâmetro caminho selecionado:

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

Revogar uma permissão

Para revogar uma permissão de um destinatário, exclua a atribuição de função fazendo uma solicitação HTTP DELETE autenticada:

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

Parâmetro	Substitua por
YOUR_ROLE_ASSIGNMENT_ID	A id da atribuição de função a ser removida

Uma solicitação DELETE com êxito retornará um status de resposta 204. Verifique se a remoção da atribuição de função pela verificação ainda mantém a atribuição de função.

Criar uma atribuição de função

Para criar uma atribuição de função, faça uma solicitação HTTP POST autenticada para a URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Verifique se que o corpo JSON está em conformidade com o esquema a seguir:

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

Uma solicitação com êxito retornará um status de resposta 201 juntamente com a id da atribuição de função recém-criada:

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

Exemplos de configuração

Os exemplos a seguir demonstram como configurar o corpo JSON em vários cenários de atribuição de função comumente encontrados.

Exemplo: um usuário precisa de acesso administrativo a um piso de um espaço de locatário.

{
  "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"
}

Exemplo: um aplicativo executa cenários de teste zombando de dispositivos e sensores.

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

Exemplo: todos os usuários que fazem parte de um domínio recebem acesso de leitura para espaços, sensores e usuários. Esse acesso inclui seus objetos relacionados correspondentes.
```
{
  "roleId": " b1ffdb77-c635-4e7e-ad25-948237d85b30",
  "objectId" : "@microsoft.com",
  "objectIdType" : "DomainName",
  "path": "/000e349c-c0ea-43d4-93cf-6b00abd23a00"
}
```

Próximas etapas

Para examinar o controle de acesso baseado em função dos Gêmeos Digitais do Azure, leia Controle de acesso baseado em função.
Para saber mais sobre a autenticação da API dos Gêmeos Digitais do Azure, leia Autenticação de API.

Compartilhar via