Suporte do Hub IoT para identidades geridas

As identidades geridas proporcionam aos serviços do Azure uma identidade gerida automaticamente no Microsoft Entra ID de forma segura. Desta forma, os programadores não terão de gerir as credenciais ao disponibilizarem uma identidade. Existem dois tipos de identidades geridas: atribuídas pelo sistema e atribuídas pelo utilizador. O Hub IoT suporta os dois tipos.

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

Pré-requisitos

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

• Um hub IoT em sua assinatura do Azure. Se você ainda não tiver um hub, siga as etapas em Criar um hub IoT.

Identidade gerida atribuída pelo sistema

Portal do Azure

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

1. Entre no portal do Azure e navegue até seu 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 ao sistema como Ativado ou Desativado e selecione Salvar.

   Nota

   Não é possível desativar a identidade gerenciada atribuída ao sistema enquanto ela estiver em uso. Certifique-se de que nenhum ponto de extremidade personalizado esteja 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 ao sistema no momento da criação do hub usando o modelo ARM

Para habilitar a identidade gerenciada atribuída ao sistema em seu hub IoT no momento do provisionamento de recursos, use o modelo 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 seu recurso name, locationSKU.name e SKU.tier, você pode 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 ao sistema atribuída ao 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>

Identidade gerida atribuída pelo utilizador

Portal do Azure

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

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

2. Vá para o seu hub IoT, navegue até a Identidade no portal do Hub IoT.

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

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

   

Azure Resource Manager

O modelo de exemplo a seguir pode ser usado para criar um hub com identidade gerenciada atribuída pelo usuário. Este modelo cria uma identidade atribuída ao usuário com o nome [iothub-name-provided]-identity e atribuída 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ê poderá recuperar a identidade gerenciada atribuída pelo 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 qual 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 do barramento de serviço.

Nota

Apenas a identidade gerida atribuída pelo sistema dá ao Hub IoT acesso a recursos privados. Se você quiser usar a identidade gerenciada atribuída pelo usuário, o acesso público nesses recursos privados precisa ser habilitado para permitir a conectividade.

Configurar o roteamento de mensagens com identidades gerenciadas

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

1. Aceda ao seu hub de eventos no portal do Azure para atribuir à identidade gerida o acesso certo.

2. Selecione Controlo de acesso (IAM) .

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

   

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

   Nota

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

5. No separador Membros, selecione Identidade gerida e, em seguida, selecione Selecionar membros.

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

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

8. No separador Rever + atribuir, selecione Rever + atribuir para atribuir a função.

   Para obter mais informações sobre atribuições de função, consulte 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, precisará ativar a exceção de primeira parte 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 do hub de eventos, navegue até a guia Firewalls e redes virtuais no 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 Guardar. Isso também se aplica à conta de armazenamento e ao barramento de serviço. Saiba mais sobre o suporte do Hub IoT para redes virtuais.

   Nota

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

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

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

    Parâmetro	Value
    Tipo de ponto final	Selecione Hubs de Eventos.
    Nome do ponto final	Forneça um nome exclusivo para um novo ponto de extremidade ou selecione Selecionar existente para escolher um ponto de extremidade de Hubs de Eventos existente.
    Namespace de Hubs de Eventos	Use o menu suspenso para selecionar um namespace de Hubs de Eventos existente 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 Usuário atribuído e use o menu suspenso para selecionar a identidade atribuída ao usuário que você criou no hub de eventos.

    

12. Selecione Criar + avançar. Você pode continuar através do assistente para criar uma rota que aponte para esse ponto de extremidade, ou você pode fechar o assistente.

Você pode alterar o tipo de autenticação de um ponto de extremidade personalizado existente. Use as seguintes etapas 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 este ponto de extremidade e selecione Salvar.

Configurar o carregamento de arquivos com identidades gerenciadas

O recurso de upload de arquivos do Hub IoT permite que os dispositivos carreguem arquivos para uma conta de armazenamento de propriedade do cliente. Para permitir que o upload de arquivos funcione, o Hub IoT precisa ter conectividade com a conta de armazenamento. Semelhante ao roteamento de mensagens, você pode escolher o tipo de autenticação preferencial e a identidade gerenciada para a conectividade de saída do Hub IoT para sua conta de Armazenamento do Azure.

1. No portal do Azure, navegue para a sua conta de armazenamento.

2. Selecione Controlo de acesso (IAM) .

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

   

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

5. No separador Membros, selecione Identidade gerida e, em seguida, selecione Selecionar membros.

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

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

8. No separador Rever + atribuir, selecione Rever + atribuir para atribuir a função.

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

   Se você precisar restringir a conectividade à sua conta de armazenamento por meio de uma rede virtual, precisará ativar a exceção de primeira parte confiável da Microsoft para conceder ao seu hub IoT acesso à conta de armazenamento. Na página de recursos da conta de armazenamento, navegue até a guia Firewalls e redes virtuais 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 essa conta de armazenamento. Clique no botão Guardar. Saiba mais sobre o suporte do Hub IoT para redes virtuais.

   Nota

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

9. Na página de recursos do seu hub IoT, navegue até a guia Carregamento de arquivo.

10. Na página exibida, selecione o contêiner que você pretende usar em seu armazenamento de blobs, defina as configurações de notificação de arquivo, TTL SAS, TTL padrão e Contagem máxima de entrega conforme desejado. Escolha o tipo de autenticação preferido e clique em Salvar. Se você receber um erro nesta etapa, defina temporariamente sua conta de armazenamento para permitir o acesso de Todas as redes e tente novamente. Você pode configurar o firewall na conta de armazenamento assim que a configuração de carregamento de arquivo estiver concluída.

    

    Nota

    No cenário de carregamento de arquivos, tanto o hub quanto o dispositivo precisam se conectar à sua conta de armazenamento. As etapas acima são para conectar seu hub IoT à sua conta de armazenamento com o tipo de autenticação desejado. Você ainda precisa conectar seu dispositivo ao armazenamento usando o URI SAS. Hoje o URI SAS é gerado usando a cadeia de conexão. Adicionaremos suporte para gerar URI SAS com identidade gerenciada em breve. Siga os passos indicados no carregamento de ficheiros.

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

O Hub IoT suporta a funcionalidade de importar/exportar informações do dispositivo em massa de ou para um blob de armazenamento fornecido pelo cliente. Essa funcionalidade requer conectividade do Hub IoT com a conta de armazenamento.

1. No portal do Azure, navegue para a sua conta de armazenamento.

2. Selecione Controlo de acesso (IAM) .

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

   

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

5. No separador Membros, selecione Identidade gerida e, em seguida, selecione Selecionar membros.

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

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

8. No separador Rever + atribuir, selecione Rever + atribuir para atribuir a função.

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

Usando a API REST ou SDK para trabalhos de importação e exportação

Agora você pode usar as APIs REST do Azure IoT 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 esta propriedade somente no trabalho de importação.
• outputBlobContainerUri: defina esta propriedade para os trabalhos de importação e exportação.
• identity: defina 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 trecho de código a seguir mostra como iniciar um trabalho de importação ou exportação usando o SDK do C#.

Trecho 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
        });

Trecho 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>"
    ) 
))

Nota

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

Exemplos de SDK

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

Próximos passos

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

• Encaminhamento de mensagens
• Upload de arquivo
• Importação/exportação de dispositivos em massa