Compartilhar via

Introdução à integração da ADR e ao gerenciamento de certificados X.509 com suporte da Microsoft no Hub IoT (versão prévia)

Este artigo explica como criar um novo Hub IoT com a integração do Registro de Dispositivos do Azure (ADR) e o gerenciamento de certificados X.509 com suporte da Microsoft.

Importante

O Hub IoT do Azure com integração a ADR e o gerenciamento de certificados X.509 com suporte da Microsoft estão em versão prévia pública e não são recomendados para cargas de trabalho de produção. Para obter mais informações, consulte as perguntas frequentes: o que há de novo no Hub IoT?.

Pré-requisitos

  • Uma assinatura ativa do Azure. Caso não tenha uma assinatura do Azure, crie uma conta gratuita.

  • Se você não tiver a CLI do Azure instalada, siga as etapas para instalar a CLI do Azure.

  • Instale a extensão da CLI IoT do Azure com visualizações habilitadas para acessar as funcionalidades de integração de ADR e gerenciamento de certificados para o Hub IoT:

    1. Verifique se há instalações de extensão da CLI do Azure existentes.

      az extension list

    2. Remova as instalações existentes do azure-iot.

      az extension remove --name azure-iot

    3. Instale a extensão azure-iot do índice com visualizações habilitadas,

      az extension add --name azure-iot --allow-preview

      ou baixe o arquivo .whl na página de versões do GitHub para instalar a extensão manualmente.

      az extension add --upgrade --source https://github.com/Azure/azure-iot-cli-extension/releases/download/v0.30.0b1/azure_iot-0.30.0b1-py3-none-any.whl

    4. Após a instalação, valide se a versão da extensão azure-iot é maior que 0.30.0b1.

      az extension list

  • Certifique-se de ter o privilégio de executar atribuições de função no escopo de destino. Executar atribuições de função no Azure requer uma função privilegiada, como Proprietário ou Administrador de Acesso de Usuário no escopo apropriado.

Escolher um método de implantação

Para usar o gerenciamento de certificados, você também deve configurar o Hub IoT, a ADR e o DPS (Serviço de Provisionamento de Dispositivos). Se preferir, você pode optar por não habilitar o gerenciamento de certificados e configurar apenas o Hub IoT com a ADR.

Para configurar seu Hub IoT com integração de ADR e gerenciamento de certificados, você pode usar a CLI do Azure ou um script que automatiza o processo de instalação.

Método de implantação Description
Selecione a CLI do Azure na parte superior da página Use a CLI do Azure para criar um novo Hub IoT, uma instância de DPS e um namespace de ADR e definir todas as configurações necessárias.
Selecione o script do PowerShell na parte superior da página Use um script do PowerShell (somente Windows) para automatizar a criação de um novo Hub IoT, uma instância de DPS e um namespace ADR e definir todas as configurações necessárias.

Visão geral

Use os comandos da CLI do Azure para criar um Hub IoT com integração de ADR e gerenciamento de certificados.

O processo de instalação neste artigo inclui as seguintes etapas:

  1. Criar um grupo de recursos
  2. Configurar os privilégios de aplicativo necessários
  3. Criar uma identidade gerenciada atribuída ao usuário
  4. Criar um namespace ADR com a identidade gerenciada atribuída pelo sistema
  5. Criar uma credencial (AC raiz) e uma política (AC emissora) com escopo para esse namespace
  6. Criar um Hub IoT (versão prévia) com namespace vinculado e identidade gerenciada
  7. Criar um DPS com IoT Hub vinculado e namespace
  8. Sincronizar suas credenciais e políticas (certificados de AC) com o namespace da ADR
  9. Criar um grupo de registro e vincular à sua política para habilitar o provisionamento de certificados

Importante

Durante o período de visualização, o Hub IoT com recursos de integração de ADR e gerenciamento de certificados habilitados na parte superior do Hub IoT estão disponíveis gratuitamente. O DPS (Serviço de Provisionamento de Dispositivos) é cobrado separadamente e não está incluído na oferta de visualização. Para obter detalhes sobre os preços do DPS, consulte os preços do Hub IoT do Azure.

Prepare o seu ambiente

Para preparar seu ambiente para usar o Registro de Dispositivos do Azure, conclua as seguintes etapas:

  1. Abra uma janela do terminal.

  2. Para entrar em sua conta do Azure, execute az login.

  3. Para listar todas as assinaturas e locatários aos quais você tem acesso, execute az account list.

  4. Se você tiver acesso a várias assinaturas do Azure, defina sua assinatura ativa em que seus dispositivos IoT são criados executando o comando a seguir.

    az account set --subscription "<your subscription name or ID>"

  5. Para exibir os detalhes da conta atual, execute az account show. Copie os dois valores a seguir da saída do comando e salve-os em um local seguro.

    • O id GUID. Use esse valor para fornecer sua ID de Assinatura.
    • O tenantId GUID. Use esse valor para atualizar suas permissões usando a ID do Locatário.

Configurar seu grupo de recursos, permissões e identidade gerenciada

Para criar um grupo de recursos, uma função e permissões para sua solução de IoT, conclua as seguintes etapas:

  1. Crie um grupo de recursos para seu ambiente.

    az group create --name <RESOURCE_GROUP_NAME> --location <REGION>

  2. Atribua uma função de Colaborador ao Hub IoT no nível do grupo de recursos. O AppId valor, que é o ID principal do IoT Hub, é 89d10474-74af-4874-99a7-c23c2f643083 e é o mesmo para todos os aplicativos Hub.

    az role assignment create --assignee "89d10474-74af-4874-99a7-c23c2f643083" --role "Contributor" --scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>"

  3. Crie uma nova UAMI (identidade gerenciada) atribuída pelo usuário.

    az identity create --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME> --location <REGION>

  4. Recupere a ID do recurso da identidade gerenciada. Você precisa da ID do recurso para atribuir funções, configurar políticas de acesso ou vincular a identidade a outros recursos.

    UAMI_RESOURCE_ID=$(az identity show --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME> --query id -o tsv)

Criar um novo namespace de ADR

Nesta seção, você criará um novo namespace ADR com uma identidade gerenciada atribuída pelo sistema. Esse processo gera automaticamente uma credencial de AC raiz e uma política de AC emissora para o namespace. Para obter mais informações sobre como credenciais e políticas são usadas para assinar certificados de folha de dispositivo durante o provisionamento, confira Gerenciamento de Certificados.

Observação

As credenciais são opcionais. Você também pode criar um namespace sem uma identidade gerenciada omitindo os sinalizadores --enable-credential-policy e --policy-name.

  1. Crie um novo namespace de ADR. Seu namespace name pode conter apenas letras minúsculas e hifens ('-') no meio do nome, mas não no início ou no final. Por exemplo, o nome "msft-namespace" é válido.
    O --enable-credential-policy comando cria credencial (AC raiz) e política padrão (AC emissora) para esse namespace. Você pode configurar o nome dessa política usando o --policy-name comando. Por padrão, uma política pode emitir certificados com uma validade de 30 dias.

    az iot adr ns create --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --location <REGION> --enable-credential-policy true --policy-name <POLICY_NAME>

    Dica

    Opcionalmente, você pode criar uma política personalizada adicionando os parâmetros --cert-subject e --cert-validity-days. Para obter mais informações, consulte Criar uma política personalizada.

    Observação

    A criação do namespace ADR com a identidade gerenciada atribuída pelo sistema pode levar até 5 minutos.

  2. Certifique-se de que o namespace com uma identidade gerenciada atribuída pelo sistema ou ID de entidade de segurança tenha sido criado.

    az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  3. Verifique se uma credencial e uma política nomeada foram criadas.

    az iot adr ns credential show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot adr ns policy show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --name <POLICY_NAME>

    Observação

    Se você não atribuir um nome de política, a política será criada com o nome "padrão".

Atribuir função UAMI para acessar o namespace da ADR

Nesta seção, você atribuirá a função Colaborador do Registro de Dispositivo do Azure à identidade gerenciada e a abrangerá para o namespace. Essa função personalizada permite o acesso total a dispositivos IoT dentro do namespace ADR.

  1. Recupere a ID principal da Identidade Gerenciada Atribuída pelo Usuário. Essa ID é necessária para atribuir funções à identidade.

    UAMI_PRINCIPAL_ID=$(az identity show --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP> --query principalId -o tsv)

  2. Recupere o ID de recurso do namespace ADR. Este ID é utilizado como escopo para a atribuição de funções.

    NAMESPACE_RESOURCE_ID=$(az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP> --query id -o tsv)

  3. Atribua a função colaborador do Registro de Dispositivo do Azure à identidade gerenciada. Essa função concede à identidade gerenciada as permissões necessárias, com escopo definido para o namespace.

    az role assignment create --assignee $UAMI_PRINCIPAL_ID --role "a5c3590a-3a1a-4cd4-9648-ea0a32b15137" --scope $NAMESPACE_RESOURCE_ID

Criar um Hub IoT com integração a ADR

  1. Crie um novo Hub IoT vinculado ao namespace ADR e com a UAMI criada anteriormente.

    az iot hub create --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --location <HUB_LOCATION> --sku GEN2 --mi-user-assigned $UAMI_RESOURCE_ID --ns-resource-id $NAMESPACE_RESOURCE_ID --ns-identity-id $UAMI_RESOURCE_ID

    Importante

    Como o Hub IoT será publicamente detectável como um ponto de extremidade DNS, evite inserir informações de identificação pessoal ou confidenciais ao nomeá-lo.

  2. Verifique se o Hub IoT tem a identidade correta e as propriedades ADR configuradas.

    az iot hub show --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --query identity --output json

Atribuir funções do Hub IoT para acessar o namespace ADR

  1. Recupere a ID principal da identidade gerenciada do namespace de ADR. Essa identidade precisa de permissões para interagir com o Hub IoT.

    ADR_PRINCIPAL_ID=$(az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP> --query identity.principalId -o tsv)

  2. Recupere a ID do recurso do Hub IoT. Esse ID é usado como o escopo para atribuições de funções.

    HUB_RESOURCE_ID=$(az iot hub show --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --query id -o tsv)

  3. Atribua a função "Colaborador" à identidade da ADR. Isso concede acesso de Colaborador de identidade gerenciada do namespace ADR ao Hub IoT. Essa função permite acesso amplo, incluindo o gerenciamento de recursos, mas não a atribuição de funções.

    az role assignment create --assignee $ADR_PRINCIPAL_ID --role "Contributor" --scope $HUB_RESOURCE_ID

  4. Atribua a função "Colaborador do Registro do Hub IoT" à identidade da ADR. Isso concede permissões mais específicas para gerenciar identidades de dispositivo no Hub IoT. Isso é essencial para a ADR registrar e gerenciar dispositivos no hub.

    az role assignment create --assignee $ADR_PRINCIPAL_ID --role "IoT Hub Registry Contributor" --scope $HUB_RESOURCE_ID

Criar uma instância do Serviço de Provisionamento de Dispositivos com integração a ADR

  1. Crie uma nova instância de DPS vinculada ao namespace ADR criado nas seções anteriores. Sua instância DPS deve estar localizada na mesma região que o namespace da ADR.

    az iot dps create --name <DPS_NAME> --resource-group <RESOURCE_GROUP> --location <LOCATION> --mi-user-assigned $UAMI_RESOURCE_ID --ns-resource-id $NAMESPACE_RESOURCE_ID --ns-identity-id $UAMI_RESOURCE_ID

  2. Verifique se o DPS tem a identidade correta e as propriedades ADR configuradas.

    az iot dps show --name <DPS_NAME> --resource-group <RESOURCE_GROUP> --query identity --output json

  1. Vincule o Hub IoT ao seu DPS.

    az iot dps linked-hub create --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP> --hub-name <HUB_NAME>

  2. Verifique se o Hub IoT aparece na lista de hubs vinculados para o DPS.

    az iot dps linked-hub list --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP>

Executar a sincronização de credenciais de ADR

Sincronize suas credenciais e políticas com o Hub IoT. Esta etapa garante que o Hub IoT registre os certificados de AC e confie em todos os certificados folha emitidos por suas políticas configuradas.

az iot adr ns credential sync --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP>

Validar o certificado da Autoridade Certificadora do hub

Valide se o seu Hub IoT registrou seu certificado de autoridade certificadora.

az iot hub certificate list --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP>

Criar um registro no DPS

Para provisionar dispositivos usando certificados folha, crie um grupo de inscrição no DPS e atribua-o à política de credencial apropriada, usando o parâmetro --credential-policy.

O comando a seguir cria um grupo de registro usando o atestado de chave simétrica por padrão:

Observação

Se você criou uma política com um nome diferente de "padrão", certifique-se de usar esse nome de política após o --credential-policy parâmetro.

az iot dps enrollment-group create --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP> --enrollment-id <ENROLLMENT_ID> --credential-policy <POLICY_NAME>

Seu Hub IoT com integração de ADR e gerenciamento de certificados agora está configurado e pronto para uso.

Comandos opcionais

Os comandos a seguir ajudam você a gerenciar seus namespaces de ADR, desabilitar dispositivos, criar políticas personalizadas e excluir recursos quando eles não forem mais necessários.

Gerenciar seus namespaces

  1. Liste todos os namespaces em seu grupo de recursos.

    az iot adr ns list --resource-group <RESOURCE_GROUP_NAME>

  2. Mostrar detalhes de um namespace específico.

    az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  3. Liste todas as políticas em seu namespace.

    az iot adr ns policy list --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

  4. Mostrar detalhes de uma política específica.

    az iot adr ns policy show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --name <POLICY_NAME>

  5. Liste todas as credenciais em seu namespace.

    az iot adr ns credential list --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>

Desabilitar dispositivos

  1. Liste todos os dispositivos no Hub IoT.

    az iot hub device-identity list --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME>

  2. Desabilite um dispositivo atualizando seu status para disabled. Certifique-se de substituir <MY_DEVICE_ID> pela ID do dispositivo que você deseja desabilitar.

    az iot hub device-identity update --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME> -d <MY_DEVICE_ID> --status disabled

  3. Execute o dispositivo novamente e verifique se ele não pode se conectar a um Hub IoT.

Criar uma política personalizada

Crie uma política personalizada usando o az iot adr ns policy create comando. Defina o nome, o assunto do certificado e o período de validade da política seguindo estas regras:

  • O valor da política name deve ser exclusivo dentro do namespace. Se você tentar criar uma política com um nome que já existe, receberá uma mensagem de erro.
  • O valor do sujeito cert-subject do certificado deve ser único em todas as políticas dentro do namespace. Se você tentar criar uma política com um assunto que já existe, você receberá uma mensagem de erro.
  • O valor do período cert-validity-days de validade deve estar entre 1 e 30 dias. Se você tentar criar uma política com um período de validade fora desse intervalo, receberá uma mensagem de erro.

O exemplo a seguir cria uma política chamada "custom-policy" com um assunto de "CN=TestDevice" e um período de validade de 30 dias.

az iot adr ns policy create --name "custom-policy" --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --cert-subject "CN=TestDevice" --cert-validity-days "30"

Excluir recursos

Para excluir o namespace da ADR, primeiro você deve excluir todas as instâncias de DPS e Hubs IoT vinculadas ao namespace.

az iot hub delete --name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot adr ns delete --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot dps delete --name <DPS_NAME> --resource-group <RESOURCE_GROUP_NAME> 
az identity delete --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME>

Visão geral

Use o script fornecido do PowerShell para automatizar a instalação do Hub IoT com a integração do Registro de Dispositivos do Azure. O script executa todas as etapas necessárias para criar os recursos necessários e vinculá-los juntos, incluindo:

  1. Criar um grupo de recursos
  2. Configurar os privilégios de aplicativo necessários
  3. Criar uma identidade gerenciada atribuída ao usuário
  4. Criar um namespace ADR com a identidade gerenciada atribuída pelo sistema
  5. Criar uma credencial (AC raiz) e uma política (AC emissora) com escopo para esse namespace
  6. Criar um Hub IoT (versão prévia) com namespace vinculado e identidade gerenciada
  7. Criar um DPS com IoT Hub vinculado e namespace
  8. Sincronizar suas credenciais e políticas (certificados de AC) com o namespace da ADR
  9. Criar um grupo de registro e vincular à sua política para habilitar o provisionamento de certificados

Importante

Durante o período de visualização, o Hub IoT com recursos de integração de ADR e gerenciamento de certificados habilitados na parte superior do Hub IoT estão disponíveis gratuitamente. O DPS (Serviço de Provisionamento de Dispositivos) é cobrado separadamente e não está incluído na oferta de visualização. Para obter detalhes sobre os preços do DPS, consulte os preços do Hub IoT do Azure.

Prepare o seu ambiente

  1. Baixe o PowerShell 7 para Windows.
  2. Navegue até o repositório GitHub e baixe a pasta Scripts, que contém o arquivo de script. iothub-adr-certs-setup-preview.ps1

Personalizar as variáveis de script

Abra o arquivo de script em um editor de texto e modifique as variáveis a seguir para corresponder à configuração desejada.

  • TenantId: a sua ID de locatário. Você pode encontrar esse valor executando az account show em seu terminal.
  • SubscriptionId: sua ID de assinatura. Você pode encontrar esse valor executando az account show em seu terminal.
  • ResourceGroup: O nome do seu grupo de recursos.
  • Location: a região do Azure em que você deseja criar seus recursos. Confira os locais disponíveis para ver os recursos de visualização na seção regiões com suporte .
  • NamespaceName: o nome do namespace pode conter apenas letras minúsculas e hifens ('-') no meio do nome, mas não no início ou no final. Por exemplo, "msft-namespace" é um nome válido.
  • HubName: o nome do hub só pode conter letras minúsculas e numerais.
  • DpsName: o nome da instância do Serviço de Provisionamento de Dispositivos.
  • UserIdentity: a identidade gerenciada atribuída pelo usuário para seus recursos.
  • WorkingFolder: a pasta local em que o script está localizado.

Importante

Como o Hub IoT será publicamente detectável como um ponto de extremidade DNS, evite inserir informações de identificação pessoal ou confidenciais ao nomeá-lo.

Executar o script interativamente

  1. Abra o script e execute no PowerShell 7+ como administrador. Navegue até a pasta que contém o script e execute .\iothub-adr-certs-setup-preview.ps1.

  2. Se você encontrar um problema de política de execução, tente executar powershell -ExecutionPolicy Bypass -File .\iothub-adr-certs-setup-preview.ps1.

  3. Siga as instruções guiadas.

    • Pressione Enter para continuar com uma etapa
    • Pressione s ou S para ignorar uma etapa
    • Pressione Ctrl + C para anular

Observação

A criação do namespace da ADR, do Hub IoT, do DPS e de outros recursos pode levar até 5 minutos cada.

Monitorar a execução e validar os recursos

  1. O script continua a execução quando os avisos são encontrados e só é interrompido se um comando retorna um código de saída diferente de zero. Monitore o console para mensagens ERROR vermelhas, que indicam problemas que exigem atenção.

  2. Depois que o script for concluído, valide a criação de seus recursos visitando seu novo Grupo de Recursos no portal do Azure. Você deverá ver os seguintes recursos criados:

    • Instância do Hub IoT
    • Instância do DPS (Serviço de Provisionamento de Dispositivos)
    • Namespace do Registro de Dispositivo do Azure (ADR)
    • Identidade Gerenciada Atribuída pelo Usuário (UAMI)

Próximas etapas

Neste ponto, seu Hub IoT com integração de ADR e gerenciamento de certificados está configurado e pronto para uso. Agora você pode começar a integrar seus dispositivos IoT ao hub usando a instância do DPS (Serviço de Provisionamento de Dispositivos) e gerenciar seus dispositivos IoT com segurança usando as políticas e registros que você configurou.

Novo: há suporte para o gerenciamento de certificados em SDKs de Dispositivo DPS selecionados. Agora você pode integrar dispositivos usando o gerenciamento de certificados X.509 com suporte da Microsoft com os seguintes exemplos de SDK:

  • Last updated on