Criar e provisionar um dispositivo IoT Edge no Windows usando certificados X.509

Aplica-se a: IoT Edge 1.1

Este artigo fornece instruções de ponta a ponta para registrar e provisionar um dispositivo Windows IoT Edge.

Cada dispositivo que se conecta a um hub IoT tem uma identidade do dispositivo que é usada para controlar as comunicações da nuvem para dispositivo ou do dispositivo para nuvem. Você configura um dispositivo com suas informações de conexão, o que inclui o nome do host do hub IoT, a identidade do dispositivo e as informações que o dispositivo usa para autenticar no Hub IoT.

As etapas deste artigo percorrem um processo chamado provisionamento manual, onde você conecta um único dispositivo ao seu hub IoT. No provisionamento manual, você tem duas opções para autenticar dispositivos do IoT Edge:

• Chaves simétricas: quando você cria uma identidade do dispositivo no Hub IoT, o serviço cria duas chaves. Você coloca uma das chaves no dispositivo e apresenta a chave para o Hub IoT durante a autenticação.

  Esse método de autenticação é mais rápido para começar a usar, mas não tão seguro.

• X.509 autoassinado: você cria dois certificados de identidade X.509 e os coloca no dispositivo. Ao criar uma nova identidade do dispositivo no Hub IoT, você fornece impressões digitais de ambos os certificados. Quando o dispositivo é autenticado no Hub IoT, ele apresenta um certificado e o Hub IoT verifica se o certificado corresponde à sua impressão digital.

  Esse método de autenticação é mais seguro e recomendado para cenários de produção.

Este artigo aborda o uso de certificados X.509 como seu método de autenticação. Se você quiser usar chaves simétricas, consulte Criar e provisionar um dispositivo IoT Edge no Windows usando chaves simétricas.

Pré-requisitos

Este artigo aborda o registro do dispositivo do IoT Edge e a instalação do IoT Edge nesse dispositivo. Essas tarefas têm diferentes pré-requisitos e utilitários usados para realizá-las. Certifique-se de que você tenha todos os pré-requisitos listados antes de continuar.

Ferramentas de gerenciamento de dispositivo

Você pode usar o portal do Azure, o Visual Studio Code ou a CLI do Azure nas etapas para registrar o dispositivo. Cada ferramenta tem seus próprios pré-requisitos.

Requisitos do dispositivo

Um dispositivo Windows.

O IoT Edge com contêineres do Windows requer o Windows versão 1809/build 17763, que é o mais recente build de suporte de longo prazo do Windows. Certifique-se de examinar a lista de sistemas com suporte para ver os SKUs com suporte.

Gerar certificados de identidade do dispositivo

O provisionamento manual com certificados X.509 requer IoT Edge versão 1.0.10 ou mais recente.

Ao provisionar um dispositivo IoT Edge com certificados X.509, você usa um certificado de identidade do dispositivo chamado de . Estes certificados são usados apenas para provisionar um dispositivo do IoT Edge e autenticar o dispositivo com o Hub IoT do Azure. É um certificado folha que não assina outros certificados. O certificado de identidade do dispositivo é separado dos certificados de autoridades de certificação que o dispositivo IoT Edge apresenta aos módulos ou dispositivos downstream para verificação.

Para a autenticação de certificado X.509, as informações de autenticação de cada dispositivo são fornecidas na forma de impressões digitais obtidas dos certificados de identidade do dispositivo. Essas impressões digitais são fornecidas ao Hub IoT no registro do dispositivo para que o serviço possa reconhecer o dispositivo quando ele se conectar.

Para obter mais informações sobre como os certificados AC são usados nos dispositivos do IoT Edge, consulte Entenda como o Azure IoT Edge usa certificados.

Você precisa dos seguintes arquivos para o provisionamento manual com X.509:

• Dois dos certificados de identidade do dispositivo com seus certificados de chave privada correspondentes em formatos .cer ou .pem.

  Um conjunto de arquivos de certificado/chave é fornecido para o runtime do IoT Edge. Ao criar certificados de identidade do dispositivo, defina o CN (nome comum) do certificado com a identidade do dispositivo que você deseja que o dispositivo tenha no hub IoT.

• Impressões digitais coletadas de ambos os certificados de identidade do dispositivo.

  Os valores de impressão digital são caracteres 40-hex para hashes SHA-1 ou caracteres 64-hex para hashes SHA-256. As duas impressões digitais são fornecidas ao Hub IoT no momento do registro do dispositivo.

Se você não tiver certificados disponíveis, você poderá Criar certificados de demonstração para testar recursos do dispositivo do IoT Edge. Siga as instruções nesse artigo para configurar scripts de criação de certificado, criar um certificado de CA raiz e, em seguida, criar dois certificados de identidade de dispositivo IoT Edge.

Uma maneira de recuperar a impressão digital de um certificado é com o seguinte comando openssl:

openssl x509 -in <certificate filename>.pem -text -fingerprint

Registre seu dispositivo

Você pode usar o portal do Azure, o Visual Studio Code ou a CLI do Azure para registrar seu dispositivo, dependendo da preferência.

az iot hub device-identity create --device-id device_id_here --hub-name hub_name_here --edge-enabled --auth-method x509_thumbprint --primary-thumbprint primary_SHA_thumbprint_here --secondary-thumbprint secdonary_SHA_thumbprint_here

Agora que você tem um dispositivo registrado no Hub IoT, recupere as informações que você usa para concluir a instalação e o provisionamento do runtime do IoT Edge.

Exibir dispositivos registrados e recuperar informações de provisionamento

Os dispositivos que usam autenticação com certificado X.509 precisam do nome do seu hub IoT, do nome do seu dispositivo e dos seus arquivos de certificado para concluir a instalação e o provisionamento do runtime do IoT Edge.

az iot hub device-identity list --hub-name hub_name_here

Instalar o IoT Edge

Nesta seção, você prepara sua VM do Windows ou dispositivo físico para o IoT Edge. Em seguida, você instalará o IoT Edge.

O Azure IoT Edge depende de um runtime de contentor compatível com o OCI. Moby, um mecanismo baseado em Moby, está incluído no script de instalação, o que significa que não há etapas adicionais para instalar o mecanismo.

Para instalar o runtime do IoT Edge:

1. Execute o PowerShell como administrador.

   Use uma sessão AMD64 do PowerShell, não do PowerShell(x86). Se você não tiver certeza de qual tipo de sessão está usando, execute o seguinte comando:

   (Get-Process -Id $PID).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
   

2. Execute o comando Deploy-IoTEdge, que executa as seguintes tarefas:

   • Verifica se o computador Windows está em uma versão com suporte
   • Ativa o recurso de contêineres
   • Faz o download do mecanismo moby e do ambiente de execução do IoT Edge

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Deploy-IoTEdge
   

3. Reinicie seu dispositivo se solicitado.

Ao instalar o IoT Edge em um dispositivo, você pode usar parâmetros adicionais para modificar o processo, incluindo:

• Direcionar o tráfego para percorrer um servidor proxy
• Aponte o instalador para um diretório local para instalação offline

Para obter mais informações sobre esses parâmetros adicionais, consulte scripts do PowerShell para IoT Edge com contêineres do Windows.

Provisionar o dispositivo com a identidade de nuvem dele

Agora que o mecanismo de contêiner e o runtime do IoT Edge estão instalados em seu dispositivo, você está pronto para a próxima etapa, que é configurar o dispositivo com suas informações de autenticação e identidade de nuvem.

1. No dispositivo IoT Edge, execute o PowerShell como administrador.

2. Use o comando Initialize-IoTEdge para configurar o runtime do IoT Edge em seu computador.

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Initialize-IoTEdge -ManualX509
   

   • Se você baixou o script IoTEdgeSecurityDaemon.ps1 em seu dispositivo para instalação de versão offline ou específica, lembre-se de referenciar a cópia local do script.

     . <path>/IoTEdgeSecurityDaemon.ps1
     Initialize-IoTEdge -ManualX509
     

3. Quando solicitado, forneça as seguintes informações:

   • IotHubHostName: nome do host do hub IoT ao qual o dispositivo se conectará. Por exemplo, {IoT_hub_name}.azure-devices.net.
   • DeviceId: a ID que você forneceu quando registrou o dispositivo.
   • X509IdentityCertificate: caminho absoluto para um certificado de identidade no dispositivo. Por exemplo, C:\path\identity_certificate.pem.
   • X509IdentityPrivateKey: caminho absoluto para o arquivo de chave privada para o certificado de identidade fornecido. Por exemplo, C:\path\identity_key.pem.

Ao provisionar um dispositivo manualmente, você pode usar parâmetros adicionais para modificar o processo, incluindo:

• Direcionar o tráfego para percorrer um servidor proxy
• Declarar uma imagem de contêiner edgeAgent específica e fornecer credenciais se ela estiver em um registro privado

Para obter mais informações sobre esses parâmetros adicionais, consulte scripts do PowerShell para IoT Edge com contêineres do Windows.

Verificar configuração bem-sucedida

Verifique se o runtime foi instalado e configurado com êxito em seu dispositivo IoT Edge.

Verifique o status do serviço do IoT Edge.

Get-Service iotedge

Examine os logs de serviço.

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog

Listar módulos em execução.

iotedge list

Instalação offline ou de versão específica (opcional)

As etapas nesta seção são destinadas a cenários não cobertos pelas etapas de instalação padrão. Isso pode incluir:

• Instale o IoT Edge enquanto estiver offline
• Instalar a versão candidato a lançamento
• Instalar uma versão diferente da mais recente

Durante a instalação, três arquivos são baixados:

• Um script do PowerShell, que contém as instruções de instalação
• Cab do Microsoft Azure IoT Edge, que contém o daemon de segurança do IoT Edge (iotedged), o mecanismo de contêiner Moby e a CLI do Moby.
• Instalador do pacote redistribuível do Visual C++ (vc runtime)

Se o dispositivo estiver offline durante a instalação ou se você quiser instalar uma versão específica do IoT Edge, poderá baixar esses arquivos com antecedência para o dispositivo. Quando for hora de instalar, aponte o script de instalação para o diretório que contém os arquivos baixados. O instalador verifica primeiro esse diretório e, em seguida, só baixa os componentes que não são encontrados. Se todos os arquivos estiverem disponíveis offline, você poderá instalar sem conexão com a Internet.

1. Para obter os arquivos de instalação mais recentes do IoT Edge, juntamente com as versões anteriores, consulte versões do Azure IoT Edge.

2. Localize a versão que você deseja instalar e, em seu dispositivo IoT, baixe os seguintes arquivos da seção Recursos das notas de versão:

   • IoTEdgeSecurityDaemon.ps1
   • Microsoft-Azure-IoTEdge-amd64.cab do canal de distribuição da versão 1.1.

   É importante usar o script do PowerShell da mesma versão do arquivo .cab que você usa porque a funcionalidade é alterada para dar suporte aos recursos em cada versão.

3. Se o arquivo .cab que você baixou tiver um sufixo de arquitetura, renomeie o arquivo para apenas Microsoft-Azure-IoTEdge.cab.

4. Se desejar, baixe um instalador para o pacote redistribuível do Visual C++. Por exemplo, o script do PowerShell usa esta versão: vc_redist.x64.exe. Salve o instalador na mesma pasta em seu dispositivo IoT que os arquivos do IoT Edge.

5. Para instalar com componentes offline, fonte de ponto a cópia local do script do PowerShell.

6. Execute o comando Deploy-IoTEdge com o parâmetro -OfflineInstallationPath. Forneça o caminho absoluto para o diretório do arquivo. Por exemplo

   . path_to_powershell_module_here\IoTEdgeSecurityDaemon.ps1
   Deploy-IoTEdge -OfflineInstallationPath path_to_file_directory_here
   

   O comando de implantação usará todos os componentes encontrados no diretório de arquivos local fornecido. Se o arquivo .cab ou o instalador do Visual C++ estiver ausente, ele tentará baixá-los.

Desinstalar o IoT Edge

Se você quiser remover a instalação do IoT Edge do seu dispositivo Windows, use o comando Uninstall-IoTEdge de uma janela administrativa do PowerShell. Esse comando remove o ambiente de execução do IoT Edge, junto com sua configuração existente e os dados do motor Moby.

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; `
Uninstall-IoTEdge

Para obter mais informações sobre opções de desinstalação, use o comando Get-Help Uninstall-IoTEdge -full.

Próximas etapas

Prossiga para implantar módulos do IoT Edge para saber como implantar módulos em seu dispositivo.