Como autenticar e autorizar chamadas à API REST do IoT Central

Artigo
03/01/2024

A API REST do IoT Central permite desenvolver aplicativos cliente que se integram aos aplicativos do IoT Central. Use a API REST para trabalhar com recursos em seu aplicativo IoT Central, como modelos de dispositivo, dispositivos, trabalhos, usuários e funções.

Cada chamada de API REST do IoT Central requer um cabeçalho de autorização que o IoT Central usa para determinar a identidade do chamador e as permissões que o chamador recebe dentro do aplicativo.

Este artigo descreve os tipos de token que você pode usar no cabeçalho de autorização e como obtê-los. As entidades de serviço são a abordagem recomendada para o gerenciamento de acesso à API REST do IoT Central.

Tipos de token

Para acessar um aplicativo do IoT Central usando a API REST, você pode usar um:

Microsoft Entra token de portador. Um token de portador está associado a uma conta de usuário ou entidade de serviço do Microsoft Entra. O token concede ao chamador as mesmas permissões que o usuário ou entidade de serviço tem no aplicativo IoT Central.
Token da API do IoT Central. Um token de API está associado a uma função em seu aplicativo IoT Central.

Use um token de portador associado à sua conta de usuário enquanto desenvolve e testa automação e scripts que usam a API REST. Use um token de portador associado a uma entidade de serviço para automação de produção e scripts. Use um token de portador em vez de um token de API para reduzir o risco de vazamentos e problemas quando os tokens expirarem.

Para saber mais sobre usuários e funções no IoT Central, consulte Gerenciar usuários e funções em seu aplicativo do IoT Central.

Obter um token ao portador

Para obter um token de portador para sua conta de usuário do Microsoft Entra, use os seguintes comandos da CLI do Azure:

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

Importante

O az login comando é necessário mesmo se você estiver usando o Cloud Shell.

A saída JSON do comando anterior se parece com o exemplo a seguir:

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

O token ao portador é válido por aproximadamente uma hora, após a qual você precisa criar um novo.

Para obter um token de portador para uma entidade de serviço, consulte Autenticação da entidade de serviço.

Obter um token de API

Para obter um token de API, você pode usar a interface do usuário do IoT Central ou uma chamada de API REST. Os administradores associados à organização raiz e os usuários atribuídos à função correta podem criar tokens de API.

Gorjeta

As operações de criação e exclusão em tokens de API são registradas no log de auditoria.

Na interface do usuário do IoT Central:

Navegue até Tokens de API de permissões>.
Selecione + Novo ou Criar um token de API.
Insira um nome para o token e selecione uma função e organização.
Selecione Gerar.
O IoT Central exibe o token semelhante ao exemplo a seguir:

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

Esta tela é a única vez que você pode ver o token da API, se você perdê-lo você precisa gerar um novo.

Um token de API é válido por aproximadamente um ano. Você pode gerar tokens para funções internas e personalizadas em seu aplicativo IoT Central. A organização escolhida ao criar o token de API determina a quais dispositivos a API tem acesso. Todos os tokens de API criados antes de adicionar quaisquer organizações ao seu aplicativo são associados à organização raiz.

Você pode excluir tokens de API na interface do usuário do IoT Central se precisar revogar o acesso.

Com a API REST:

Use a API REST para recuperar uma lista de IDs de função do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "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 a API REST para criar um token de API para uma função. Por exemplo, para criar um token de API chamado operator-token para a função de operador:

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

Corpo do pedido:

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

A resposta ao comando anterior se parece com o seguinte 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 resposta é a única vez que você tem acesso ao token da API, se você perdê-lo você precisa gerar um novo.

Você pode usar a API REST para listar e excluir tokens de API em um aplicativo.

Use um token ao portador

Para usar um token de portador quando você faz uma chamada de API REST, seu cabeçalho de autorização se parece com o exemplo a seguir:

Authorization: Bearer eyJ0eX...fNQ

Usar um token de API

Para usar um token de API quando você faz uma chamada de API REST, seu cabeçalho de autorização se parece com o exemplo a seguir:

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

Partilhar via