Criar programaticamente um grupo de registro do Serviço de Provisionamento de Dispositivos para atestado do certificado X.509
Este artigo mostra como criar programaticamente um grupo de inscrição no Serviço de Provisionamento de Dispositivos no Hub IoT (DPS) que utiliza certificados X.509 intermediários ou de autoridade raiz. O grupo de registro é criado usando o SDK do serviço IoT do Azure e um aplicativo de exemplo. Um grupo de registros controla o acesso ao serviço de provisionamento para dispositivos que compartilham um certificado de autenticação comum em sua cadeia de certificados. Para saber mais, confira Usar certificados X.509 com DPS. Para obter mais informações sobre como usar a Infraestrutura de Chave Pública (PKI) do X.509 baseada em certificado com o Hub IoT do Azure e o Serviço de Provisionamento do Dispositivo, confira Visão geral de segurança do certificado de Autoridade de Certificação do X.509.
Pré-requisitos
Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Conclua as etapas em Configurar o Serviço de Provisionamento de Dispositivos no Hub IoT com o portal do Azure.
Instale o SDK do .NET 6.0 ou posterior no computador baseado no Windows. Use o comando a seguir para verificar a versão.
dotnet --info
- Instale o Node.js v4.0 ou superior ou posterior no seu computador.
Java SE Development Kit 8. Este artigo usa o SDK da Internet das Coisas do Azure para Java, que funciona tanto no Windows quanto no Linux. Este artigo usa Windows.
- Instale a versão mais recente do Git. Verifique se o Git foi adicionado às variáveis de ambiente que podem ser acessadas pela janela de comando. Confira Ferramentas de cliente Git do Software Freedom Conservancy para obter a versão mais recente das ferramentas
git
a serem instaladas, que inclui o Git Bash, o aplicativo de linha de comando que você pode usar para interagir com seu repositório Git local.
Observação
Embora as etapas deste artigo funcionem em computadores Windows e Linux, este artigo usa um computador de desenvolvimento do Windows.
Criar certificados de teste
Os grupos de registro que usam o atestado do certificado X.509 podem ser configurados para usar um Certificado de Autoridade de Certificação raiz ou um certificado intermediário. O caso mais comum é configurar o grupo de registro com um certificado intermediário. O uso de um certificado intermediário fornece mais flexibilidade, já que vários certificados intermediários podem ser gerados ou revogados pelo mesmo Certificado de AC raiz.
Neste artigo, você vai precisar de um arquivo de Certificado de AC raiz, um arquivo de Certificado de AC intermediário ou ambos, nos formatos .pem ou .cer. Um arquivo contém a parte pública do Certificado de Autoridade de Certificação X.509 raiz e o outro contém a parte pública do Certificado de Autoridade de Certificação X.509 intermediário.
Se você já tiver um arquivo de Autoridade de Certificação raiz e/ou um arquivo de Autoridade de Certificação intermediário, poderá continuar para Adicionar e verificar seu Certificado de Autoridade de Certificação raiz ou intermediário.
Se você não tiver um arquivo de Autoridade de Certificação raiz e/ou um arquivo de Autoridade de Certificação intermediário, siga as etapas em Criar uma cadeia de certificados X.509 para criá-los. Você pode parar após concluir as etapas de Criar o Certificado de AC intermediário, já que não vai precisar de certificados de dispositivo para executar as etapas deste artigo. Quando terminar, você terá dois arquivos de certificado X.509: ./certs/azure-iot-test-only.root.ca.cert.pem e ./certs/azure-iot-test-only.intermediate.cert.pem.
Adicionar e verificar seu Certificado de Autoridade de Certificação raiz ou intermediário
Os dispositivos provisionados por um grupo de registro usando certificados X.509 apresentam toda a cadeia de certificados quando eles se autenticam com o DPS. Por que o DPS possa validar a cadeia de certificados, a raiz ou certificado intermediário configurado em um grupo de registro deve ser um certificado verificado ou um dispositivo presente na autenticação com o serviço deve ser acumulado em certificado verificado na cadeia de certificados.
Neste artigo, supondo que você tenha um Certificado de Autoridade de Certificação raiz e um Certificado de Autoridade de Certificação intermediário assinado pela Autoridade de Certificação raiz:
Se estiver planejando criar o grupo de registro com o Certificado de AC raiz, você precisará carregar e verificar o Certificado de AC raiz.
Se você planeja criar o grupo de registro com o Certificado de Autoridade de Certificação intermediário, é possível carregar e verificar o Certificado de Autoridade de Certificação raiz ou o Certificado de Autoridade de Certificação intermediário. (Se você tiver vários Certificados de Autoridade de Certificação intermediários na cadeia de certificados, será possível, como alternativa, carregar e verificar qualquer certificado intermediário que esteja entre o Certificado de Autoridade de Certificação raiz e o certificado intermediário com o qual você cria o grupo de registro.)
Para adicionar e verificar seu Certificado de Autoridade de Certificação raiz ou intermediário ao Serviço de Provisionamento de Dispositivos:
Entre no portal do Azure.
No menu à esquerda ou na página do portal, selecione Todos os recursos.
Selecione o seu Serviço de Provisionamento de Dispositivos.
No menu Configurações, selecione Certificados.
No menu superior, selecione + Adicionar:.
Insira um nome para o Certificado de Autoridade de Certificação raiz ou intermediário e carregue o arquivo .pem ou .cer.
Selecione Definir status do certificado para verificado no upload.
Selecione Salvar.
Obter a cadeia de conexão do serviço de provisionamento
Para a amostra incluída neste artigo, você precisa da cadeia de conexão do seu serviço de provisionamento. Use as etapas a seguir para recuperá-lo.
Entre no portal do Azure.
No menu à esquerda ou na página do portal, selecione Todos os recursos.
Selecione o seu Serviço de Provisionamento de Dispositivos.
No menu Configurações, selecione Políticas de acesso compartilhado.
Selecione a política de acesso que você deseja usar.
No painel Política de Acesso, copie e salve a cadeia de conexão da chave primária.
Criar exemplo de grupo de registros
Esta seção mostra como criar um aplicativo de console .NET Core que adiciona um grupo de registro ao serviço de provisionamento.
Abra o prompt de comando do Windows e acesse a pasta na qual o aplicativo será criado.
Para criar um projeto de console, execute o comando a seguir:
dotnet new console --framework net6.0 --use-program-main
Para adicionar uma referência ao SDK do serviço de DPS, execute o seguinte comando:
dotnet add package Microsoft.Azure.Devices.Provisioning.Service
Esta etapa baixa, instala e adiciona uma referência ao pacote NuGet do cliente do serviço DPS em IoT do Azure e suas dependências. Esse pacote inclui os binários do SDK do serviço .NET.
Abra o arquivo Program.cs em um editor.
Substitua a instrução de namespace na parte superior do arquivo pela seguinte linha:
namespace CreateEnrollmentGroup;
Adicione as instruções
using
a seguir à parte superior do arquivo acima da instruçãonamespace
:using System.Security.Cryptography.X509Certificates; using System.Threading.Tasks; using Microsoft.Azure.Devices.Provisioning.Service;
Adicione os campos a seguir à classe
Program
e faça as alterações indicadas.private static string ProvisioningConnectionString = "{ProvisioningServiceConnectionString}"; private static string EnrollmentGroupId = "enrollmentgrouptest"; private static string X509RootCertPath = @"{Path to a .cer or .pem file for a verified root CA or intermediate CA X.509 certificate}";
Substitua o valor de espaço reservado
ProvisioningServiceConnectionString
pela cadeia de conexão do serviço de provisionamento que você copiou na seção anterior.Substitua o valor de espaço reservado
X509RootCertPath
pelo caminho para um arquivo .pem ou .cer. Esse arquivo representa a parte pública de um certificado X.509 de uma autoridade certificadora raiz que foi previamente carregado e verificado com seu serviço de provisionamento, ou de um certificado intermediário que foi carregado e verificado ou teve um certificado em sua cadeia de assinatura carregado e verificado.Opcionalmente, você pode alterar o valor
EnrollmentGroupId
. A cadeia de caracteres pode conter apenas letras minúsculas e hifens.
Importante
No código de produção, esteja ciente das seguintes considerações de segurança:
- Codificar a cadeia de conexão para o administrador de serviço de provisionamento é contra as práticas recomendadas de segurança. Em vez disso, a cadeia de conexão deve ser mantida de uma maneira segura, como em um arquivo de configuração seguro ou no registro.
- Verifique se você carregou somente a parte pública do certificado de autenticação. Nunca carregue arquivos .pfx (PKCS12) ou .pem que contenham as chaves privadas para o serviço de provisionamento.
Adicione o método a seguir à classe
Program
. Esse código cria uma entradaEnrollmentGroup
e, em seguida, chama o métodoProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync
para adicionar o grupo de registro ao serviço de provisionamento.public static async Task RunSample() { Console.WriteLine("Starting sample..."); using (ProvisioningServiceClient provisioningServiceClient = ProvisioningServiceClient.CreateFromConnectionString(ProvisioningConnectionString)) { #region Create a new enrollmentGroup config Console.WriteLine("\nCreating a new enrollmentGroup..."); var certificate = new X509Certificate2(X509RootCertPath); Attestation attestation = X509Attestation.CreateFromRootCertificates(certificate); EnrollmentGroup enrollmentGroup = new EnrollmentGroup( EnrollmentGroupId, attestation) { ProvisioningStatus = ProvisioningStatus.Enabled }; Console.WriteLine(enrollmentGroup); #endregion #region Create the enrollmentGroup Console.WriteLine("\nAdding new enrollmentGroup..."); EnrollmentGroup enrollmentGroupResult = await provisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync(enrollmentGroup).ConfigureAwait(false); Console.WriteLine("\nEnrollmentGroup created with success."); Console.WriteLine(enrollmentGroupResult); #endregion } }
Por fim, substitua o método
Main
pelas seguintes linhas:static async Task Main(string[] args) { await RunSample(); Console.WriteLine("\nHit <Enter> to exit ..."); Console.ReadLine(); }
Salve suas alterações.
Esta seção mostra como criar um script Node.js que adiciona um grupo de registro ao serviço de provisionamento.
Dica
Para simplificar, este exemplo usa a autenticação SAS para se conectar à API do serviço DPS. Uma abordagem mais segura é usar credenciais de token do Azure. Para obter um exemplo desse método de autenticação, consulte o exemplo create_tpm_enrollment_with_token_credentials.js no SDK do Node.js.
Em uma janela de comando na sua pasta de trabalho, execute:
npm install azure-iot-provisioning-service
Esta etapa baixa, instala e adiciona uma referência ao pacote do cliente do serviço DPS em IoT do Azure e suas dependências. Esse pacote inclui os binários do SDK do serviço Node.js.
Usando um editor de texto, crie um arquivo create_enrollment_group.js em sua pasta de trabalho. Adicione o seguinte código ao arquivo e salve:
'use strict'; var fs = require('fs'); var provisioningServiceClient = require('azure-iot-provisioning-service').ProvisioningServiceClient; var serviceClient = provisioningServiceClient.fromConnectionString(process.argv[2]); var enrollment = { enrollmentGroupId: 'first', attestation: { type: 'x509', x509: { signingCertificates: { primary: { certificate: fs.readFileSync(process.argv[3], 'utf-8').toString() } } } }, provisioningStatus: 'disabled' }; serviceClient.createOrUpdateEnrollmentGroup(enrollment, function(err, enrollmentResponse) { if (err) { console.log('error creating the group enrollment: ' + err); } else { console.log("enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2)); enrollmentResponse.provisioningStatus = 'enabled'; serviceClient.createOrUpdateEnrollmentGroup(enrollmentResponse, function(err, enrollmentResponse) { if (err) { console.log('error updating the group enrollment: ' + err); } else { console.log("updated enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2)); } }); } });
Abra um prompt de comando do Windows.
Clone o repositório GitHub para o exemplo de código de registro do dispositivo usando o SDK do Serviço Java:
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
No local em que você baixou o repositório, acesse a pasta de exemplo:
cd azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample
Abra o arquivo /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java em um editor de sua escolha.
Substitua
[Provisioning Connection String]
pela cadeia de conexão que você copiou em Obter a cadeia de conexão do serviço de provisionamento.Substitua a cadeia de caracteres constante
PUBLIC_KEY_CERTIFICATE_STRING
pelo valor do arquivo.pem
do Certificado de Autoridade de Certificação raiz ou intermediário. Esse arquivo representa a parte pública de um certificado X.509 de uma autoridade certificadora raiz que foi previamente carregado e verificado com seu serviço de provisionamento, ou de um certificado intermediário que foi carregado e verificado ou teve um certificado em sua cadeia de assinatura carregado e verificado.A sintaxe do texto do certificado precisa seguir esse padrão sem espaços extras nem caracteres:
private static final String PUBLIC_KEY_CERTIFICATE_STRING = "-----BEGIN CERTIFICATE-----\n" + "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" + ... "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" + "-----END CERTIFICATE-----";
Atualizar esse valor da cadeia de caracteres manualmente pode ser propenso a erros. Para gerar a sintaxe adequada, você pode copiar e colar o seguinte comando em um prompt do Git Bash, substituir
your-cert.pem
pelo local do arquivo do certificado e pressionar ENTER. Esse comando vai gerar a sintaxe para o valor da constante da cadeia de caracteresPUBLIC_KEY_CERTIFICATE_STRING
e gravá-la na saída.sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' your-cert.pem
Copie e cole o texto do certificado de saída para o valor da constante.
Importante
No código de produção, esteja ciente das seguintes considerações de segurança:
- Codificar a cadeia de conexão para o administrador de serviço de provisionamento é contra as práticas recomendadas de segurança. Em vez disso, a cadeia de conexão deve ser mantida de uma maneira segura, como em um arquivo de configuração seguro ou no registro.
- Verifique se você carregou somente a parte pública do certificado de autenticação. Nunca carregue arquivos .pfx (PKCS12) ou .pem que contenham as chaves privadas para o serviço de provisionamento.
O exemplo permite que você defina um hub IoT no grupo de registro para o qual o dispositivo será provisionado. Esse hub IoT já deve ter sido vinculado anteriormente ao serviço de provisionamento. Neste artigo, permitimos que o DPS escolha entre os hubs vinculados de acordo com a política de alocação padrão, com uma distribuição ponderada uniformemente. Comente a seguinte instrução no arquivo:
enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME); // Optional parameter.
O código de exemplo cria, atualiza, consulta e exclui um grupo de registro para dispositivos X.509. Para verificar a criação bem-sucedida do grupo de registro no portal do Azure, comente as seguintes linhas de código perto do final do arquivo:
// ************************************** Delete info of enrollmentGroup *************************************** System.out.println("\nDelete the enrollmentGroup..."); provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);
Salve o arquivo ServiceEnrollmentGroupSample.java.
Executar exemplo de grupo de registros
Execute o exemplo:
dotnet run
Após a criação bem-sucedida, a janela de comandos exibe as propriedades do novo grupo de registros.
Execute o seguinte comando em seu prompt de comando. Inclua aspas nos argumentos de comando e substitua
<connection string>
pela cadeia de conexão que você copiou na seção anterior e<certificate .pem file>
pelo caminho do arquivo.pem
do certificado. Esse arquivo representa a parte pública de um certificado X.509 de uma autoridade certificadora raiz que foi previamente carregado e verificado com seu serviço de provisionamento, ou de um certificado intermediário que foi carregado e verificado ou teve um certificado em sua cadeia de assinatura carregado e verificado.node create_enrollment_group.js "<connection string>" "<certificate .pem file>"
Após a criação bem-sucedida, a janela de comandos exibe as propriedades do novo grupo de registros.
Na pasta azure-iot-sdk-java\provisioning\provisioning-samples\service-enrollment-group-sample no seu prompt de comando, execute o seguinte comando para compilar a amostra:
mvn install -DskipTests
Esse comando baixa o pacote Maven do cliente do serviço DPS em IoT do Azure para seu computador e compila o exemplo. Esse pacote inclui os binários do SDK do serviço Java.
Alterne para a pasta de destino e execute o exemplo. A compilação na etapa anterior gera o arquivo .jar na pasta de destino com o seguinte formato de arquivo:
provisioning-x509-sample-{version}-with-deps.jar
; por exemplo,provisioning-x509-sample-1.8.1-with-deps.jar
. Talvez seja necessário substituir a versão no comando a seguir.cd target java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar
Após a criação bem-sucedida, a janela de comandos exibe as propriedades do novo grupo de registros.
Para verificar se o grupo de registro foi criado:
No portal do Azure, navegue até sua instância do Serviço de Provisionamento de Dispositivos.
No menu Configurações, selecione Gerenciar registros.
Selecione a guia Grupos de registro. Você deverá ver uma nova entrada de registro que corresponde à ID do grupo de registro usada no exemplo.
Limpar os recursos
Se você planeja explorar os tutoriais do Serviço de Provisionamento de Dispositivos no Hub IoT do Azure, não limpe os recursos criados neste artigo. Caso contrário, use as seguintes etapas para excluir todos os recursos criados por este artigo.
Feche a janela de saída de exemplo no computador.
No menu à esquerda no portal do Azure, selecione Todos os recursos.
Selecione o seu Serviço de Provisionamento de Dispositivos.
No menu à esquerda, em Configurações, selecione Gerenciar registros.
Selecione a guia Grupos de registro.
Selecione a caixa de seleção ao lado do nome de grupo do grupo de registro que você criou neste artigo.
Na parte superior da página, selecione Excluir.
No Serviço de Provisionamento de Dispositivos no portal do Azure, selecione Certificados em Configurações no menu à esquerda.
Selecione o certificado que você carregou para este artigo.
Na parte superior da guia Detalhes do certificado, selecione Excluir.
Ferramentas de certificado
O SDK da Internet das Coisas do Azure em C tem scripts que podem ajudar você a criar e gerenciar certificados. Para saber mais, consulte Gerenciar certificados de Autoridade de Certificação de teste para exemplos e tutoriais.
O SDK Node.js da Internet das Coisas do Azure tem scripts que podem ajudar você a criar e gerenciar certificados. Para saber mais, consulte Ferramentas para o SDK do Dispositivo de Provisionamento de Dispositivos do IoT do Azure para Node.js.
Você também pode usar ferramentas disponíveis no SDK do IoT do Azure C. Para saber mais, consulte Gerenciar certificados de Autoridade de Certificação de teste para exemplos e tutoriais.
O SDK da Internet das Coisas do Azure em Java contém ferramentas de teste que podem ajudar você a criar e gerenciar certificados. Para saber mais, confira o gerador de certificados X509 usando o emulador DICE.
Próximas etapas
Neste artigo, você criou um grupo de registro para um Certificado de Autoridade de Certificação X.509 raiz ou intermediária usando o Serviço de Provisionamento de Dispositivos no Hub IoT do Azure. Para explorar mais, confira os links a seguir:
Para obter mais informações sobre o atestado de certificado X.509 com DPS, consulte atestado de certificado X.509.
Para obter um exemplo de ponta a ponta de dispositivos de provisionamento por meio de um grupo de registro usando certificados X.509, consulte o tutorial Provisionar vários dispositivos X.509 usando grupos de registro.
Para saber mais sobre como gerenciar registros individuais e grupos de registro usando portal do Azure, consulte Como gerenciar registros de dispositivo com o portal do Azure.