Suporte do hub IoT a identidades gerenciadas

As identidades gerenciadas fornecem aos serviços do Azure uma identidade gerenciada automaticamente no Microsoft Entra ID de forma segura. Isso elimina a necessidade de os desenvolvedores gerenciarem credenciais fornecendo uma identidade. Há dois tipos de identidades gerenciadas: atribuída pelo sistema e atribuída pelo usuário. O hub IoT dá suporte a ambos.

No Hub IoT, as identidades gerenciadas podem ser usadas para conectar o Hub IoT a outros serviços do Azure para o uso de recursos como roteamento de mensagens, upload de arquivo e importação/exportação de dispositivos em massa. Neste artigo, você aprenderá a usar identidades gerenciadas atribuídas pelo sistema e atribuídas por usuário em seu Hub IoT para diferentes funcionalidades.

Pré-requisitos

• Entenda as diferenças entre a identidade gerenciada atribuída pelo sistema e atribuída pelo usuário em O que são as identidades gerenciadas para recursos do Azure?

• Um Hub IoT na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.

Identidade gerenciada atribuída pelo sistema

Portal do Azure

Você pode habilitar ou desabilitar a identidade gerenciada atribuída pelo sistema no portal do Azure

1. Entre no Portal do Azure e navegue até o Hub IoT.

2. Selecione Identidade na seção Configurações de segurança do menu de navegação.

3. Selecione a guia Atribuído pelo sistema.

4. Defina o Status da identidade gerenciada atribuída pelo sistema como Ativado ou Desativado e selecione Salvar.

   Observação

   Você não pode desativar a identidade gerenciada atribuída pelo sistema enquanto ela estiver em uso. Verifique se os pontos de extremidade personalizados estão usando a autenticação de identidade gerenciada atribuída pelo sistema antes de desabilitar o recurso.

   

Azure Resource Manager

Você pode habilitar a identidade gerenciada atribuída pelo sistema no momento da criação do hub usando um modelo do ARM

Para habilitar a identidade gerenciada atribuída pelo sistema no seu hub IoT no momento de provisionamento do recurso, use o modelo do Azure Resource Manager (ARM) abaixo.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": 
    {
      "iotHubName": {
        "type": "string",
        "metadata": {
          "description": "Name of iothub resource"
        }
      },
      "skuName": {
        "type": "string",
        "defaultValue": "S1",
        "metadata": {
          "description": "SKU name of iothub resource, by default is Standard S1"
        }
      },
      "skuTier": {
        "type": "string",
        "defaultValue": "Standard",
        "metadata": {
          "description": "SKU tier of iothub resource, by default is Standard"
        }
      },
      "location": {
        "type": "string",
        "defaultValue": "[resourceGroup().location]",
        "metadata": {
          "description": "Location of iothub resource. Please provide any of supported-regions of iothub"
        }
      }
    },
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-10-01",
      "name": "createIotHub",
      "properties": {
        "mode": "Incremental",
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "resources": [
            {
              "type": "Microsoft.Devices/IotHubs",
              "apiVersion": "2021-03-31",
              "name": "[parameters('iotHubName')]",
              "location": "[parameters('location')]",
              "identity": {
                "type": "SystemAssigned"
              },
              "sku": {
              "name": "[parameters('skuName')]",
              "tier": "[parameters('skuTier')]",
              "capacity": 1
              }
            }
          ] 
        }
      }
    }
  ]
}

Depois de substituir os valores do recurso name, locationSKU.name e SKU.tier, você poderá usar a CLI do Azure para implantar o recurso em um grupo de recursos existente usando:

az deployment group create --name <deployment-name> --resource-group <resource-group-name> --template-file <template-file.json> --parameters iotHubName=<valid-iothub-name> skuName=<sku-name> skuTier=<sku-tier> location=<any-of-supported-regions>

Você pode recuperar a identidade gerenciada atribuída pelo sistema que foi atribuída ao hub usando a CLI do Azure:

az resource show --resource-type Microsoft.Devices/IotHubs --name <iot-hub-resource-name> --resource-group <resource-group-name>

Identidade gerenciada atribuída pelo usuário

Portal do Azure

Nesta seção, você aprende como adicionar e remover uma identidade gerenciada atribuída ao usuário de um hub IoT usando o portal do Azure.

1. Primeiro, você precisa criar uma identidade gerenciada atribuída por usuário como um recurso autônomo. Para fazer isso, siga as instruções descritas em Gerenciar identidades gerenciadas atribuídas pelo usuário.

2. Acesse o seu hub IoT e navegue até a Identidade no portal do hub IoT.

3. Na guia Atribuído pelo usuário, clique em Associar identidade gerenciada atribuída pelo usuário. Escolha a identidade gerenciada atribuída por usuário que você deseja adicionar ao seu hub e clique em Selecionar.

4. Você pode remover uma identidade atribuída por usuário de um hub IoT. Escolha a identidade atribuída por usuário que você deseja remover e clique no botão Remover. Observe que você a está removendo somente do hub IoT e que essa remoção não exclui a identidade atribuída por usuário como recurso. Para excluir a identidade atribuída pelo usuário como um recurso, siga as instruções descritas em Gerenciar identidades gerenciadas atribuídas pelo usuário.

   

Azure Resource Manager

Veja a seguir o modelo de exemplo que pode ser usado para criar um hub com a identidade gerenciada atribuída pelo usuário. Este modelo cria uma identidade com o nome [iothub-name-provided]-identity atribuída pelo usuário ao Hub IoT criado. Você pode alterar o modelo para adicionar várias identidades atribuídas pelo usuário, conforme necessário.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "iotHubName": {
      "type": "string",
      "metadata": {
        "description": "Name of iothub resource"
      }
    },
  "skuName": {
    "type": "string",
    "defaultValue": "S1",
    "metadata": {
      "description": "SKU name of iothub resource, by default is Standard S1"
    }
  },
  "skuTier": {
    "type": "string",
    "defaultValue": "Standard",
    "metadata": {
      "description": "SKU tier of iothub resource, by default is Standard"
    }
  },
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]",
    "metadata": {
      "description": "Location of iothub resource. Please provide any of supported-regions of iothub"
    }
  }
},
  "variables": {
    "identityName": "[concat(parameters('iotHubName'), '-identity')]"
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-10-01",
      "name": "createIotHub",
      "properties": {
        "mode": "Incremental",
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "resources": [
            {
              "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
              "name": "[variables('identityName')]",
              "apiVersion": "2018-11-30",
              "location": "[resourceGroup().location]"
            },
            {
              "type": "Microsoft.Devices/IotHubs",
              "apiVersion": "2021-03-31",
              "name": "[parameters('iotHubName')]",
              "location": "[parameters('location')]",
              "identity": {
                "type": "UserAssigned",
                "userAssignedIdentities": {
                  "[resourceID('Microsoft.ManagedIdentity/userAssignedIdentities/',variables('identityName'))]": {}
                }
              },
              "sku": {
                "name": "[parameters('skuName')]",
                "tier": "[parameters('skuTier')]",
                "capacity": 1
              },
              "dependsOn": [
                "[resourceID('Microsoft.ManagedIdentity/userAssignedIdentities/',variables('identityName'))]"
              ]
            }
          ]
        }
      }
    }
  ]
}

az deployment group create --name <deployment-name> --resource-group <resource-group-name> --template-file <template-file.json> --parameters iotHubName=<valid-iothub-name> skuName=<sku-name> skuTier=<sku-tier> location=<any-of-supported-regions>

Depois que o recurso for criado, você pode recuperar a identidade gerenciada atribuída por usuário em seu hub usando a CLI do Azure:

az resource show --resource-type Microsoft.Devices/IotHubs --name <iot-hub-resource-name> --resource-group <resource-group-name>

Conectividade de saída do Hub IoT para outros recursos do Azure

As identidades gerenciadas podem ser usadas para conectividade de saída do Hub IoT para outros serviços do Azure. Você pode escolher que identidade gerenciada usar para cada conectividade de saída do hub IoT para pontos de extremidade de propriedade do cliente, incluindo contas de armazenamento, hubs de eventos e pontos de extremidade de barramento de serviço.

Observação

Apenas a identidade gerenciada atribuída pelo sistema permite que o Hub IoT acesse recursos privados. Se quiser usar a identidade gerenciada atribuída pelo usuário, o acesso público nesses recursos privados precisará ser habilitado para permitir a conectividade.

Configurar o roteamento de mensagens com identidades gerenciadas

Nesta seção, usamos como exemplo o roteamento de mensagens para um ponto de extremidade personalizado do Hubs de Eventos. O mesmo também se aplica a outros pontos de extremidade personalizados de roteamento.

1. Acesse seu hub de eventos no portal do Azure para atribuir à identidade gerenciada o acesso certo.

2. Selecione IAM (Controle de acesso) .

3. Selecione Adicionar > Adicionar atribuição de função.

   

4. Na guia Função, selecione Remetente de Dados dos Hubs de Eventos do Azure.

   Observação

   Para uma conta de armazenamento, selecione Colaborador de Dados de Blob de Armazenamento (não Colaborador ou Colaborador de Conta de Armazenamento) como função. Para um barramento de serviço, selecione Remetente de Dados de Barramento de Serviço do Azure.

5. Na guia Membros, selecione Identidade gerenciadae selecione Selecionar membros.

6. Para identidades gerenciadas atribuídas pelo usuário, selecione sua assinatura e selecione Identidade gerenciada atribuída pelo usuário, em seguida, selecione a identidade gerenciada atribuída pelo usuário.

7. Para identidades gerenciadas atribuídas pelo sistema, selecione sua assinatura e selecione Todas as identidades gerenciadas atribuídas pelo sistema, em seguida, selecione o nome do recurso do Hub IoT.

8. Na guia Examinar + atribuir, selecione Examinar + atribuir para atribuir a função.

   Para obter mais informações sobre atribuições de função, confira Atribuir funções do Azure usando o portal do Azure.

9. Se você precisar restringir a conectividade ao seu ponto de extremidade personalizado por meio de uma VNet, será necessário ativar a exceção interna confiável da Microsoft para dar ao seu hub IoT acesso ao ponto de extremidade específico. Por exemplo, se você estiver adicionando um ponto de extremidade personalizado de hub de eventos, navegue até a guia Firewalls e redes virtuais no seu hub de eventos e habilite a opção Permitir acesso de redes selecionadas. Na lista Exceções, marque a caixa Permitir que serviços confiáveis da Microsoft acessem hubs de eventos. Clique no botão Salvar . Isso também se aplica à conta de armazenamento e ao barramento de serviço. Saiba mais sobre Suporte ao hub IoT para redes virtuais.

   Observação

   Você precisa concluir as etapas acima para atribuir à identidade gerenciada o acesso correto antes de adicionar o hub de eventos como um ponto de extremidade personalizado no hub IoT. Aguarde alguns minutos para que a atribuição de função se propague.

10. Em seguida, vá até o seu hub IoT. No hub, navegue até Roteamento de Mensagens e selecione Adicionar.

11. Na guia Ponto de extremidade, crie um ponto de extremidade para sua seu hub de eventos fornecendo as seguintes informações:

    Parâmetro	Valor
    Tipo de ponto de extremidade	Selecione a opção Hubs de Eventos.
    Nome do ponto de extremidade	Forneça um nome exclusivo para um novo ponto de extremidade ou selecione Selecionar existente para escolher um ponto de extremidade existente dos Hubs de Eventos.
    Namespace do Hubs de Eventos	Use o menu suspenso para selecionar um namespace existente dos Hubs de Eventos em sua assinatura.
    Instância do hub de eventos	Use o menu suspenso para selecionar um hub de eventos existente em seu namespace.
    Tipo de autenticação	Selecione Atribuído pelo usuário e, em seguida, use o menu suspenso para selecionar a identidade atribuída pelo usuário que você criou no hub de eventos.

    

12. Selecione Criar + avançar. Você pode continuar por meio do assistente para criar uma rota que aponte para esse ponto de extremidade ou pode fechar o assistente.

Você pode alterar o tipo de autenticação de um ponto de extremidade personalizado existente. Use as etapas a seguir para modificar um ponto de extremidade:

1. No hub IoT, selecione Roteamento de mensagens no painel de navegação esquerdo e, em seguida, Pontos de extremidade personalizados.

2. Marque a caixa de seleção do ponto de extremidade personalizado que você deseja modificar e selecione Alterar tipo de autenticação.

3. Escolha o novo tipo de autenticação para esse ponto de extremidade, e, em seguida, selecione Salvar.

Configurar o upload de arquivo com identidades gerenciadas

O recurso de carregamento de arquivos do hub IoT permite que dispositivos façam upload de arquivos para uma conta de armazenamento de propriedade do cliente. Para possibilitar o funcionamento do upload de arquivo, o hub IoT precisa ter conectividade com a conta de armazenamento. Semelhante ao roteamento de mensagens, você pode escolher o tipo de autenticação e a identidade gerenciada preferidos para a conectividade de saída do hub IoT com a sua conta de armazenamento do Azure.

1. No portal do Azure, navegue até sua conta de armazenamento.

2. Selecione IAM (Controle de acesso) .

3. Selecione Adicionar > Adicionar atribuição de função.

   

4. Na guia Função, selecione o Colaborador de Dados do Blob de Armazenamento. (Não selecione Colaborador ou Colaborador da Conta de Armazenamento.)

5. Na guia Membros, selecione Identidade gerenciadae selecione Selecionar membros.

6. Para identidades gerenciadas atribuídas pelo usuário, selecione sua assinatura e selecione Identidade gerenciada atribuída pelo usuário, em seguida, selecione a identidade gerenciada atribuída pelo usuário.

7. Para identidades gerenciadas atribuídas pelo sistema, selecione sua assinatura e selecione Todas as identidades gerenciadas atribuídas pelo sistema, em seguida, selecione o nome do recurso do Hub IoT.

8. Na guia Examinar + atribuir, selecione Examinar + atribuir para atribuir a função.

   Para obter mais informações sobre atribuições de função, confira Atribuir funções do Azure usando o portal do Azure.

   Se você precisar restringir a conectividade à sua conta de armazenamento por meio de uma VNet, será necessário ativar a exceção interna confiável da Microsoft para dar ao seu hub IoT acesso à conta de armazenamento específica. Na página de recursos da sua conta de armazenamento, vá até a guia Firewalls e redes virtuais e habilite a opção Permitir acesso a partir das redes selecionadas. Na lista Exceções, marque a caixa Permitir que serviços confiáveis da Microsoft acessem esta conta de armazenamento. Clique no botão Salvar . Saiba mais sobre Suporte ao hub IoT para redes virtuais.

   Observação

   Você precisa concluir as etapas acima para atribuir à identidade gerenciada o acesso correto antes de salvar a conta de armazenamento no Hub IoT para upload de arquivo usando a identidade gerenciada. Aguarde alguns minutos para que a atribuição de função se propague.

9. Na página de recursos do seu hub IoT, vá até a guia Upload de arquivos.

10. Na página que aparece, selecione o contêiner que você pretende usar em seu armazenamento de blobs, ajuste as Configurações de notificação de arquivo, TTL do SAS, TTL padrão e a Contagem de entrega máxima conforme desejado. Escolha o tipo de autenticação preferido e clique em salvar. Se você receber um erro nessa etapa, defina temporariamente que sua conta de armazenamento permita o acesso de todas as redes e tente novamente. Você poderá configurar o firewall na conta de armazenamento depois que a configuração de carregamento de arquivo for concluída.

    

    Observação

    No cenário de upload de arquivo, o hub e o dispositivo precisam se conectar com sua conta de armazenamento. As etapas acima são para conectar o hub IoT à conta de armazenamento com o tipo de autenticação desejado. Você ainda precisa conectar o dispositivo com o armazenamento usando o URI SAS. No momento, o URI SAS é gerado usando a cadeia de conexão. Em breve será adicionado o suporte para gerar o URI SAS com identidade gerenciada. Siga as etapas em Upload de arquivo.

Configurar a importação/exportação de dispositivos em massa com identidades gerenciadas

O Hub IoT dá suporte à funcionalidade de importação/exportação de informações de dispositivos em massa bidirecionalmente em um blob de armazenamento fornecido pelo cliente. Essa funcionalidade requer conectividade do Hub IoT à conta de armazenamento.

1. No portal do Azure, navegue até sua conta de armazenamento.

2. Selecione IAM (Controle de acesso) .

3. Selecione Adicionar > Adicionar atribuição de função.

   

4. Na guia Função, selecione o Colaborador de Dados do Blob de Armazenamento. (Não selecione Colaborador ou Colaborador da Conta de Armazenamento.)

5. Na guia Membros, selecione Identidade gerenciadae selecione Selecionar membros.

6. Para identidades gerenciadas atribuídas pelo usuário, selecione sua assinatura e selecione Identidade gerenciada atribuída pelo usuário, em seguida, selecione a identidade gerenciada atribuída pelo usuário.

7. Para identidades gerenciadas atribuídas pelo sistema, selecione sua assinatura e selecione Todas as identidades gerenciadas atribuídas pelo sistema, em seguida, selecione o nome do recurso do Hub IoT.

8. Na guia Examinar + atribuir, selecione Examinar + atribuir para atribuir a função.

   Para obter mais informações sobre atribuições de função, confira Atribuir funções do Azure usando o portal do Azure

Usar a API REST ou o SDK para importar e exportar trabalhos

Agora você pode utilizar os APIs REST da IoT do Azure para criar trabalhos de importação e exportação. Você precisará fornecer as seguintes propriedades no corpo da solicitação:

• storageAuthenticationType: defina o valor como identityBased.
• inputBlobContainerUri: defina essa propriedade somente no trabalho de importação.
• outputBlobContainerUri: : definir essa propriedade para os trabalhos de importação e exportação.
• identity: definir o valor para a identidade gerenciada a ser usada.

Os SDKs do Hub IoT do Azure também dão suporte a essa funcionalidade no gerenciador de registro do cliente de serviço. O snippet de código de C# a seguir mostra como iniciar um trabalho de importação ou exportação usando o SDK de C#.

Snippet de código C#

    // Create an export job
 
    JobProperties jobProperties = JobProperties.CreateForExportJob(
        outputBlobContainerUri: blobContainerUri,
        excludeKeysInExport: false,
        storageAuthenticationType: StorageAuthenticationType.IdentityBased,
        identity: new ManagedIdentity
        {
            userAssignedIdentity = userDefinedManagedIdentityResourceId
        });

    // Create an import job
    
    JobProperties jobProperties = JobProperties.CreateForImportJob(
        inputBlobContainerUri: blobContainerUri,
        outputBlobContainerUri: blobContainerUri,
        storageAuthenticationType: StorageAuthenticationType.IdentityBased,
        identity: new ManagedIdentity
        {
            userAssignedIdentity = userDefinedManagedIdentityResourceId
        });

Snippet de código Python

# see note below
iothub_job_manager = IoTHubJobManager("<IoT Hub connection information>")

# Create an import job
result = iothub_job_manager.create_import_export_job(JobProperties(
    type="import",
    input_blob_container_uri="<input container URI>",
    output_blob_container_uri="<output container URI>",
    storage_authentication_type="identityBased",
    identity=ManagedIdentity(
        user_assigned_identity="<resource ID of user assigned managed identity>"
    )
))

# Create an export job
result = iothub_job_manager.create_import_export_job(JobProperties(
    type="export",
    output_blob_container_uri="<output container URI>",
    storage_authentication_type="identityBased",
    exclude_keys_in_export=True,
    identity=ManagedIdentity(
        user_assigned_identity="<resource ID of user assigned managed identity>"
    ) 
))

Observação

• Se storageAuthenticationType for definido como identityBased e a propriedade userAssignedIdentity não for nula, os trabalhos usarão a identidade gerenciada atribuída por usuário especificada.
• Se o hub IoT não estiver configurado com a identidade gerenciada atribuída por usuário especificada em userAssignedIdentity, o trabalho falhará.
• Se storageAuthenticationType for configurado como identityBased e a propriedade userAssignedIdentity for nula, os trabalhos usarão uma identidade atribuída pelo sistema.
• Se o hub IoT não estiver configurado com a identidade gerenciada atribuída pelo usuário, o trabalho falhará.
• Se storageAuthenticationType for configurado como identityBased e não estiverem configuradas no hub as identidades gerenciadas atribuídas por usuário nem atribuídas pelo sistema, o trabalho falhará.

Amostras do SDK

• Exemplo de SDK do .NET
• Exemplo de SDK do Java
• Exemplo de SDK do Python

Próximas etapas

Use os links abaixo para saber mais sobre os recursos do Hub IoT:

• Roteamento de mensagem
• Carregamento de arquivos
• Importação/exportação de dispositivos em massa