Criar programaticamente um grupo de registro do Serviço de Provisionamento de Dispositivos para atestado do certificado X.509

  • Artigo

Este artigo mostra como criar programaticamente um grupo de registro que usa Certificados de Autoridade de Certificação X.509 raiz ou intermediários. O grupo de registro é criado usando o SDK do serviço de DPS no Hub 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 Como controlar o acesso ao dispositivo para o serviço de provisionamento com certificados X.509. 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

  • 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:

  1. Entre no portal do Azure.

  2. No menu à esquerda ou na página do portal, selecione Todos os recursos.

  3. Selecione o seu Serviço de Provisionamento de Dispositivos.

  4. No menu Configurações, selecione Certificados.

  5. No menu superior, selecione + Adicionar:.

  6. Insira um nome para o Certificado de Autoridade de Certificação raiz ou intermediário e carregue o arquivo .pem ou .cer.

  7. Selecione Definir status do certificado para verificado no upload.

    Screenshot that shows adding the root CA certificate to a DPS instance.

  8. 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.

  1. Entre no portal do Azure.

  2. No menu à esquerda ou na página do portal, selecione Todos os recursos.

  3. Selecione o seu Serviço de Provisionamento de Dispositivos.

  4. No menu Configurações, selecione Políticas de acesso compartilhado.

  5. Selecione a política de acesso que você deseja usar.

  6. No painel Política de Acesso, copie e salve a cadeia de conexão da chave primária.

    Screenshot that shows the location of the provisioning service connection string in the portal.

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.

  1. Abra o prompt de comando do Windows e acesse a pasta na qual o aplicativo será criado.

  2. Para criar um projeto de console, execute o comando a seguir:

    dotnet new console --framework net6.0 --use-program-main

  3. 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.

  4. Abra o arquivo Program.cs em um editor.

  5. Substitua a instrução de namespace na parte superior do arquivo pela seguinte linha:

    namespace CreateEnrollmentGroup;

  6. Adicione as instruções using a seguir à parte superior do arquivo acima da instrução namespace:

    using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using Microsoft.Azure.Devices.Provisioning.Service;

  7. 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 de Autoridade de Certificação X.509 raiz que foi carregado e verificado anteriormente com o serviço de provisionamento ou 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.

  8. Adicione o método a seguir à classe Program. Esse código cria uma entrada EnrollmentGroup e, em seguida, chama o método ProvisioningServiceClient.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

    }
}

  9. 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();
}

  10. 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.

  1. 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.

  2. 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));
          }
        });
      }
    });

  1. Abra um prompt de comando do Windows.

  2. 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

  3. 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

  4. Abra o arquivo /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java em um editor de sua escolha.

  5. Substitua [Provisioning Connection String] pela cadeia de conexão que você copiou em Obter a cadeia de conexão do serviço de provisionamento.

  6. 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 de Autoridade de Certificação X.509 raiz que foi carregado e verificado anteriormente com o serviço de provisionamento ou 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 o padrão abaixo 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 caracteres PUBLIC_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.

  7. 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.

  8. 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);

  9. Salve o arquivo ServiceEnrollmentGroupSample.java.

Executar exemplo de grupo de registros

  1. Execute o exemplo:

    dotnet run

  2. Após a criação bem-sucedida, a janela de comandos exibe as propriedades do novo grupo de registros.

  1. 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 de Autoridade de Certificação X.509 raiz que foi carregado e verificado anteriormente com o serviço de provisionamento ou 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>"

  2. Após a criação bem-sucedida, a janela de comandos exibe as propriedades do novo grupo de registros.

  1. 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.

  2. 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 abaixo.

    cd target
java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar

  3. 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 registros foi criado:

  1. No portal do Azure, navegue até sua instância do Serviço de Provisionamento de Dispositivos.

  2. No menu Configurações, selecione Gerenciar registros.

  3. Selecione a guia Grupos de registro. Você deverá ver uma nova entrada de registro que corresponde à ID do grupo de registro usada no exemplo.

Screenshot that shows the newly created enrollment group in the portal.

Screenshot that shows the newly created enrollment group in the portal.

Screenshot that shows the newly created enrollment group in the portal.

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.

  1. Feche a janela de saída de exemplo no computador.

  2. No menu à esquerda no portal do Azure, selecione Todos os recursos.

  3. Selecione o seu Serviço de Provisionamento de Dispositivos.

  4. No menu à esquerda, em Configurações, selecione Gerenciar registros.

  5. Selecione a guia Grupos de registro.

  6. Selecione a caixa de seleção ao lado do nome de grupo do grupo de registro que você criou neste artigo.

  7. Na parte superior da página, selecione Excluir.

  8. No Serviço de Provisionamento de Dispositivos no portal do Azure, selecione Certificados em Configurações no menu à esquerda.

  9. Selecione o certificado que você carregou para este artigo.

  10. 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: