Partilhar via

Comece com a integração ADR e a gestão de certificados X.509 apoiada pela Microsoft no IoT Hub (pré-visualização)

Este artigo explica como criar um novo IoT Hub com integração Azure Device Registry (ADR) e gestão de certificados X.509 apoiada pela Microsoft.

Importante

O Azure IoT Hub, com integração ADR e gestão de certificados X.509 apoiada pela Microsoft, está em pré-visualização pública e não é recomendado para cargas de trabalho de produção. Para mais informações, consulte o FAQ: O que há de novo no IoT Hub?.

Pré-requisitos

  • Uma assinatura ativa do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita.

  • Se não tiver a CLI do Azure instalada, siga os passos para instalar a CLI do Azure.

  • Instale a extensão Azure IoT CLI com pré-visualizações ativadas para aceder às funcionalidades de integração ADR e gestão de certificados para o IoT Hub:

    1. Verifique as instalações existentes de extensões de CLI do Azure.

      az extension list

    2. Remova quaisquer instalações Azure-IoT existentes.

      az extension remove --name azure-iot

    3. Instale a extensão Azure-IoT a partir do índice com pré-visualizações ativadas,

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

      ou descarregar o ficheiro .whl da página de lançamentos 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 que a sua versão da extensão Azure-IoT é superior a 0.30.0b1.

      az extension list

  • Assegure-se de que tem o privilégio de desempenhar atribuições de funções dentro do âmbito de destino. A realização de atribuições de funções no Azure requer um papel privilegiado, como Proprietário ou Administrador de Acesso ao Utilizador no âmbito apropriado.

Escolher um método de implementação

Para usar a gestão de certificados, deve também configurar o IoT Hub, ADR e o Device Provisioning Service (DPS). Se preferires, podes optar por não ativar a gestão de certificados e configurar apenas o IoT Hub com ADR.

Para configurar o seu IoT Hub com integração ADR e gestão de certificados, pode usar Azure CLI ou um script que automatize o processo de configuração.

Método de implantação Description
Selecione Azure CLI no topo da página Use o Azure CLI para criar um novo Hub IoT, uma instância DPS e um namespace ADR e configure todas as definições necessárias.
Selecione o script PowerShell no topo da página Use um script PowerShell (apenas para Windows) para automatizar a criação de um novo Hub IoT, instância DPS e namespace ADR e configure todas as definições necessárias.

Visão geral

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

O processo de configuração neste artigo inclui os seguintes passos:

  1. Criar um grupo de recursos
  2. Configure os privilégios necessários da aplicação
  3. Criar uma identidade gerenciada atribuída pelo usuário
  4. Crie um namespace ADR com identidade gerida atribuída pelo sistema
  5. Crie uma credencial (CA raiz) e uma política (CA emissora) com âmbito desse espaço de nomes
  6. Crie um IoT Hub (pré-visualização) com namespace ligado e identidade gerida
  7. Crie um DPS com IoT Hub e namespace ligados
  8. Sincronize as suas credenciais e políticas (certificados CA) com o espaço de nomes ADR
  9. Crie um grupo de inscrição e ligue à sua apólice para permitir a disponibilização de certificados

Importante

Durante o período de pré-visualização, o IoT Hub com integração ADR e funcionalidades de gestão de certificados ativadas por cima do IoT Hub está disponível gratuitamente. O Serviço de Provisionamento de Dispositivos (DPS) é faturado separadamente e não está incluído na oferta de pré-visualização. Para detalhes sobre preços DPS, consulte preços Azure IoT Hub.

Prepare seu ambiente

Para preparar o seu ambiente para usar o Azure Device Registry, complete os seguintes passos:

  1. Abra uma janela do terminal.

  2. Para iniciar sessão na sua conta Azure, execute az login.

  3. Para listar todas as subscrições e inquilinos a que tem acesso, execute az account list.

  4. Se tiver acesso a várias subscrições Azure, defina a sua subscrição ativa onde os seus dispositivos IoT são criados, executando o seguinte comando.

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

  5. Para mostrar os dados atuais da sua conta, execute az account show. Copie ambos os valores seguintes da saída do comando e guarde-os num local seguro.

    • O id GUID. Utiliza este valor para fornecer o seu ID de Subscrição.
    • O tenantId GUID. Usa este valor para atualizar as suas permissões usando o ID do Inquilino.

Configure o seu grupo de recursos, permissões e identidade gerida

Para criar um grupo de recursos, função e permissões para a sua solução IoT, complete os seguintes passos:

  1. Crie um grupo de recursos para o seu ambiente.

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

  2. Atribuir uma função de Contribuidor ao IoT Hub ao nível do grupo de recursos. O AppId valor, que é o principal ID do IoT Hub, é 89d10474-74af-4874-99a7-c23c2f643083 e é o mesmo para todas as aplicações do 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 identidade gerida pelo utilizador (UAMI).

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

  4. Recuperar o ID de recurso da identidade gerida. Precisa do ID de recurso para atribuir papéis, configurar políticas de acesso ou ligar 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 espaço de nomes ADR

Nesta secção, cria um novo espaço de nomes ADR com uma identidade gerida atribuída pelo sistema. Este processo gera automaticamente uma credencial de CA raiz e uma política de CA emissora para o namespace. Para mais informações sobre a forma como credenciais e políticas são usadas para assinar certificados de dispositivo de folha no provisionamento, consulte Gestão de Certificados.

Observação

As credenciais são opcionais. Também pode criar um namespace sem uma identidade gerida, omitindo as flags --enable-credential-policy e --policy-name.

  1. Crie um novo espaço de nomes ADR. O seu espaço name de nomes pode conter apenas letras minúsculas e hífenes ('-') no meio do nome, mas não no início ou no fim. Por exemplo, o nome "msft-namespace" é válido.
    O --enable-credential-policy comando cria credenciais (CA raiz) e política padrão (CA de emissão) para este espaço de nomes. Pode configurar o nome desta política usando o --policy-name comando. Por padrão, uma política pode emitir certificados com 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>

    Sugestão

    Pode, opcionalmente, criar uma política personalizada adicionando os parâmetros --cert-subject e --cert-validity-days. Para mais informações, consulte Criar uma política personalizada.

    Observação

    A criação do espaço de nomes ADR com identidade gerida atribuída pelo sistema pode demorar até 5 minutos.

  2. Verifique se o namespace com uma identidade gerida atribuída pelo sistema, ou principal ID, foi criado.

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

  3. Verifique se uma credencial e uma política nomeadas 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 não atribuiu um nome de apólice, a política é criada com o nome "default".

Atribuir função UAMI para aceder ao espaço de nomes ADR

Nesta secção, atribui o papel de Contribuidor do Registo de Dispositivos Azure à identidade gerida e define o seu âmbito ao namespace. Este papel personalizado permite acesso total a dispositivos IoT dentro do namespace ADR.

  1. Recuperar o ID principal da Identidade Gerida Atribuída pelo Utilizador. Este ID é necessário para atribuir funções à identidade.

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

  2. Recuperar o ID de recurso do espaço de nomes ADR. Este ID é usado como escopo para a atribuição da função.

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

  3. Atribua a função de Contribuidor do Registo de Dispositivos Azure à identidade gerida. Esta função concede à identidade gerida as permissões necessárias, limitadas ao namespace.

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

Crie um Hub IoT com integração ADR

  1. Crie um novo Hub IoT ligado ao namespace ADR e com o UAMI criado 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 poderá ser descoberto publicamente como um ponto de extremidade DNS, evite inserir informações confidenciais ou pessoalmente identificáveis ao nomeá-lo.

  2. Verifique se o IoT Hub 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 de IoT Hub para o acesso ao espaço de nomes ADR

  1. Recuperar o ID principal da identidade gerida do namespace ADR. Esta identidade necessita de permissões para interagir com o IoT Hub.

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

  2. Recupere o ID do recurso do IoT Hub. Este ID é usado como 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. Atribuir a função "Contribuidor" à identidade ADR. Isto concede ao Contribuidor de identidade gerida do espaço de nomes ADR acesso ao IoT Hub. Esta função permite um acesso amplo, incluindo a gestão de recursos, mas sem atribuição de funções.

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

  4. Atribuir a função "Contribuidor do Registo do Hub IoT" à identidade ADR. Isto concede permissões mais específicas para gerir identidades de dispositivos no IoT Hub. Isto é essencial para que a ADR possa registar e gerir dispositivos no hub.

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

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

  1. Cria uma nova instância de DPS ligada ao teu namespace ADR criado nas secções anteriores. A tua instância DPS deve estar localizada na mesma região do teu espaço de nomes 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 de ADR configuradas.

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

  1. Liga o IoT Hub ao teu DPS.

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

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

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

Executar sincronização de credenciais ADR

Sincronize a sua credencial e políticas com o IoT Hub. Este passo garante que o IoT Hub regista os certificados de CA e confia em quaisquer certificados folha emitidos pelas suas políticas configuradas.

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

Valide o certificado de CA do hub

Valide que o seu IoT Hub registou o seu certificado de CA.

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

Criar uma inscrição no DPS

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

O comando seguinte cria um grupo de inscrição, usando atestação de chave simétrica por padrão:

Observação

Se criou uma política com um nome diferente de "default", certifique-se de usar esse nome de apólice depois do --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>

O seu IoT Hub com integração ADR e gestão de certificados está agora configurado e pronto a usar.

Comandos opcionais

Os seguintes comandos ajudam-no a gerir os seus namespaces ADR, desativar dispositivos, criar políticas personalizadas e eliminar recursos quando já não são necessários.

Gerir os seus namespaces

  1. Lista todos os namespaces no teu 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 no seu espaço de nomes.

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

  4. Mostre detalhes de uma apólice específica.

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

  5. Liste todas as credenciais no seu espaço de nomes.

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

Desativar dispositivos

  1. Liste todos os dispositivos no seu Hub IoT.

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

  2. Desative um dispositivo atualizando o seu estado para disabled. Certifica-te de substituir <MY_DEVICE_ID> pelo ID do dispositivo que queres desativar.

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

  3. Volte a ligar o dispositivo e verifique se não consegue ligar-se 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 apólice seguindo estas regras:

  • O valor da política name deve ser único dentro do espaço de nomes. Se tentar criar uma política com um nome que já existe, recebe uma mensagem de erro.
  • O valor do sujeito cert-subject do certificado deve ser único em todas as políticas do namespace. Se tentar criar uma política com um assunto que já existe, recebe uma mensagem de erro.
  • O valor do período cert-validity-days de validade deve ser entre 1 e 30 dias. Se tentar criar uma apólice com período de validade fora deste intervalo, recebe uma mensagem de erro.

O exemplo seguinte cria uma política chamada "custom-policy" com o sujeito "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"

Eliminar recursos

Para eliminar o seu namespace ADR, deve primeiro eliminar quaisquer Hubs IoT e instâncias DPS ligadas 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 PowerShell fornecido para automatizar a configuração do seu IoT Hub com integração com o Azure Device Registry. O script executa todos os passos necessários para criar os recursos necessários e ligá-los entre si, incluindo:

  1. Criar um grupo de recursos
  2. Configure os privilégios necessários da aplicação
  3. Criar uma identidade gerenciada atribuída pelo usuário
  4. Crie um namespace ADR com identidade gerida atribuída pelo sistema
  5. Crie uma credencial (CA raiz) e uma política (CA emissora) com âmbito desse espaço de nomes
  6. Crie um IoT Hub (pré-visualização) com namespace ligado e identidade gerida
  7. Crie um DPS com IoT Hub e namespace ligados
  8. Sincronize as suas credenciais e políticas (certificados CA) com o espaço de nomes ADR
  9. Crie um grupo de inscrição e ligue à sua apólice para permitir a disponibilização de certificados

Importante

Durante o período de pré-visualização, o IoT Hub com integração ADR e funcionalidades de gestão de certificados ativadas por cima do IoT Hub está disponível gratuitamente. O Serviço de Provisionamento de Dispositivos (DPS) é faturado separadamente e não está incluído na oferta de pré-visualização. Para detalhes sobre preços DPS, consulte preços Azure IoT Hub.

Prepare seu ambiente

  1. Descarregue o PowerShell 7 para Windows.
  2. Navegue até ao repositório GitHub e descarregue a pasta Scripts , que contém o ficheiro de scripts, iothub-adr-certs-setup-preview.ps1.

Personalizar as variáveis do script

Abra o ficheiro de script num editor de texto e modifique as seguintes variáveis para corresponder à configuração desejada.

  • TenantId: O seu ID de inquilino. Pode encontrar este valor executando az account show no seu terminal.
  • SubscriptionId: O seu ID de subscrição. Pode encontrar este valor executando az account show no seu terminal.
  • ResourceGroup: O nome do seu grupo de recursos.
  • Location: A região Azure onde queres criar os teus recursos. Consulte as localizações disponíveis para funcionalidades de pré-visualização na secção Regiões Suportadas .
  • NamespaceName: O nome do seu espaço de nomes pode conter apenas letras minúsculas e hífenes ('-') no meio do nome, mas não no início ou no fim. Por exemplo, "msft-namespace" é um nome válido.
  • HubName: O nome do seu hub só pode conter letras minúsculas e numerais.
  • DpsName: O nome da sua instância de Serviço de Provisionamento de Dispositivos.
  • UserIdentity: A identidade gerida atribuída pelo utilizador para os seus recursos.
  • WorkingFolder: A pasta local onde o teu script está localizado.

Importante

Como o hub IoT poderá ser descoberto publicamente como um ponto de extremidade DNS, evite inserir informações confidenciais ou pessoalmente identificáveis ao nomeá-lo.

Executa o script de forma interativa

  1. Abra o script e execute o PowerShell 7+ como administrador. Navega até à pasta que contém o teu script e executa .\iothub-adr-certs-setup-preview.ps1.

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

  3. Siga as instruções orientadas:

    • Pressione Enter para avançar com um passo
    • Pressione s ou S para saltar um passo
    • Pressione Ctrl + C para interromper

Observação

A criação do seu espaço de nomes ADR, IoT Hub, DPS e outros recursos pode demorar até 5 minutos cada.

Monitorizar a execução e validar os recursos

  1. O script continua a executar quando surgem advertências e só é interrompido se um comando retornar um código de saída diferente de zero. Monitorize a consola para mensagens vermelhas de ERRO , que indicam problemas que exigem atenção.

  2. Quando o script estiver concluído, valide a criação dos seus recursos visitando o seu novo Grupo de Recursos no portal Azure. Deverá ver os seguintes recursos criados:

    • Instância IoT Hub
    • Instância do Serviço de Provisionamento de Dispositivos (DPS)
    • Azure Device Registry (ADR) namespace
    • Identidade Gerida Atribuída pelo Utilizador (IGAU)

Próximos passos

Neste momento, o seu IoT Hub com integração ADR e gestão de certificados está configurado e pronto a usar. Agora pode começar a integrar os seus dispositivos IoT no hub usando a instância do Device Provisioning Service (DPS) e gerir os seus dispositivos IoT de forma segura usando as políticas e inscrições que configurou.

Novidade: A gestão de certificados é suportada em determinados SDKs de Dispositivos DPS. Agora pode integrar dispositivos usando a gestão de certificados X.509 apoiada pela Microsoft com os seguintes exemplos de SDK:

  • Last updated on