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

Artigo
03/15/2024

Este artigo mostra como criar programaticamente um grupo de registro no DPS (Serviço de Provisionamento de Dispositivo) do Hub IoT do Azure que usa certificados CA X.509 intermediários ou raiz. O grupo de inscrição é criado usando o SDK do serviço IoT do Azure e um aplicativo de exemplo. Um grupo de inscrição controla o acesso ao serviço de aprovisionamento de dispositivos que partilham um certificado de assinatura comum na respetiva cadeia de certificados. Para saber mais, consulte Usar certificados X.509 com DPS. Para obter mais informações sobre como utilizar a Infraestrutura de Chaves Públicas (PKI) baseada em certificados X.509 com o Hub IoT do Azure e o Serviço de Aprovisionamento de Dispositivos, veja Descrição geral da segurança do certificado de AC X.509.

Pré-requisitos

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Conclua as etapas em Configurar o Serviço de Provisionamento de Dispositivo do Hub IoT com o portal do Azure.

Instale o SDK do .NET 6.0 ou posterior ou posterior em sua máquina baseada no Windows. Você pode usar o seguinte comando para verificar sua versão.
```
dotnet --info
```

Instale Node.js v4.0 ou superior ou posterior na sua máquina.

Kit de Desenvolvimento Java SE 8. Este artigo usa o SDK do Azure IoT para Java, que funciona no Windows e no Linux. Este artigo usa o Windows.
Maven 3.

Instale a versão mais recente do Git. Certifique-se de que o Git é adicionado às variáveis de ambiente acessíveis à janela de comando. Consulte as ferramentas de cliente Git da Software Freedom Conservancy para obter a versão mais recente das ferramentas a serem instaladas, que inclui o Git Bash, o aplicativo de linha de git comando que você pode usar para interagir com seu repositório Git local.

Nota

Embora as etapas neste artigo funcionem em computadores Windows e Linux, este artigo usa um computador de desenvolvimento Windows.

Criar certificados de teste

Os grupos de inscrição que usam o atestado de 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 inscrição com um certificado intermediário. O uso de um certificado intermediário oferece mais flexibilidade, pois vários certificados intermediários podem ser gerados ou revogados pelo mesmo certificado de autoridade de certificação raiz.

Para este artigo, você precisa de um arquivo de certificado de autoridade de certificação raiz, um arquivo de certificado de autoridade de certificação intermediário ou ambos no formato .pem ou .cer . Um arquivo contém a parte pública do certificado CA X.509 raiz e o outro contém a parte pública do certificado CA 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 a Adicionar e verificar seu certificado de autoridade de certificação raiz ou intermediária.

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 depois de concluir as etapas em Criar o certificado de autoridade de certificação intermediário, pois não precisa de certificados de dispositivo para concluir as etapas neste 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ária

Os dispositivos provisionados por meio de um grupo de registro usando certificados X.509 apresentam toda a cadeia de certificados quando são autenticados com o DPS. Para que o DPS possa validar a cadeia de certificados, o certificado raiz ou intermediário configurado em um grupo de registro deve ser um certificado verificado ou deve ser acumulado para um certificado verificado na cadeia de certificados que um dispositivo apresenta quando se autentica com o serviço.

Para este 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 você planeja criar o grupo de inscrição com o certificado de autoridade de certificação raiz, precisará carregar e verificar o certificado de autoridade de certificação raiz.
Se você planeja criar o grupo de inscrição com o certificado de autoridade de certificação intermediário, poderá carregar e verificar o certificado de autoridade de certificação raiz ou o certificado de autoridade de certificação intermediária. (Se você tiver vários certificados de CA intermediários na cadeia de certificados, poderá, alternativamente, carregar e verificar qualquer certificado intermediário que fique 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 CA raiz ou intermediário ao Serviço de Provisionamento de Dispositivo:

Inicie sessão no portal do Azure.
No menu à esquerda ou na página do portal, selecione Todos os recursos.
Selecione o Serviço de Provisionamento de Dispositivo.
No menu Configurações, selecione Certificados.
No menu superior, selecione + Adicionar:.
Insira um nome para seu certificado de autoridade de certificação raiz ou intermediária e carregue o arquivo .pem ou .cer .
Selecione Definir status do certificado como verificado ao carregar.
Selecione Guardar.

Obter a cadeia de ligação para o serviço de aprovisionamento

Para o exemplo neste artigo, você precisa da cadeia de conexão para seu serviço de provisionamento. Use as etapas a seguir para recuperá-lo.

Inicie sessão no portal do Azure.
No menu à esquerda ou na página do portal, selecione Todos os recursos.
Selecione o Serviço de Provisionamento de Dispositivo.
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 de chave primária.

Criar o exemplo do grupo de inscrição

Esta seção mostra como criar um aplicativo de console .NET Core que adiciona um grupo de registro ao seu serviço de provisionamento.

Abra um prompt de comando do Windows e navegue até uma pasta onde você deseja criar seu aplicativo.
Para criar um projeto de console, execute o seguinte comando:
```
dotnet new console --framework net6.0 --use-program-main 
```
Para adicionar uma referência ao SDK do serviço 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 de serviço do Azure IoT DPS e suas dependências. Este pacote inclui os binários para o SDK do serviço .NET.
Abra Program.cs arquivo em um editor.
Substitua a instrução namespace na parte superior do arquivo pela seguinte linha:
```
namespace CreateEnrollmentGroup;
```

Adicione as seguintes using instruções na parte superior do arquivo acima da namespace instrução:

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

Adicione os seguintes campos à Program classe 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 ProvisioningServiceConnectionString valor do espaço reservado pela cadeia de conexão do serviço de provisionamento copiado na seção anterior.
- Substitua o X509RootCertPath valor de espaço reservado pelo caminho para um arquivo .pem ou .cer. Esse arquivo representa a parte pública de um certificado raiz da CA X.509 que foi carregado e verificado anteriormente com seu 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 EnrollmentGroupId valor. A cadeia só pode conter carateres minúsculos e hífenes.
Importante

No código de produção, tenha em atenção as seguintes considerações de segurança:
- A pré-programação da cadeia de ligação para o administrador do serviço de aprovisionamento vai contra as melhores práticas de segurança. Em vez disso, a cadeia de ligação deve ser mantida de forma segura, tal como num ficheiro de configuração seguro ou no registo.
- Carregue apenas a parte pública do certificado de assinatura. Nunca carregue ficheiros .pfx (PKCS12) ou .pem que contêm chaves privadas para o serviço de aprovisionamento.

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

    }
}

Finalmente, substitua o Main método pelas seguintes linhas:

static async Task Main(string[] args)
{
    await RunSample();
    Console.WriteLine("\nHit <Enter> to exit ...");
    Console.ReadLine();
}

Guardar as suas alterações.

Esta seção mostra como criar um script de Node.js que adiciona um grupo de registro ao seu serviço de provisionamento.

Gorjeta

Para simplificar, este exemplo usa a autenticação SAS para se conectar à API de 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 de create_tpm_enrollment_with_token_credentials.js no Node.js SDK.

A partir de 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 de serviço do Azure IoT DPS e suas dependências. Este pacote inclui os binários para o SDK do serviço Node.js.

Com um editor de texto, crie um ficheiro create_enrollment_group.js na sua pasta de trabalho. Adicione o seguinte código ao ficheiro e guarde:

    '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 uma linha de comandos do Windows.
Clone o exemplo de código de repositório GitHub para registro de dispositivo usando o Java Service SDK:
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```

No local onde você baixou o repositório, vá para 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 copiada em Obter a cadeia de conexão para seu serviço de provisionamento.
Substitua a PUBLIC_KEY_CERTIFICATE_STRING cadeia de caracteres constante pelo valor do arquivo de certificado .pem de autoridade de certificação raiz ou intermediária. Esse arquivo representa a parte pública de um certificado raiz da CA X.509 que foi carregado e verificado anteriormente com seu 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 deve seguir este padrão sem espaços ou caracteres extras:
```
private static final String PUBLIC_KEY_CERTIFICATE_STRING = 
        "-----BEGIN CERTIFICATE-----\n" +
        "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
            ...
        "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
        "-----END CERTIFICATE-----";
```
Atualizar esse valor de 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 de certificado e pressionar ENTER. Este comando gera a sintaxe para o valor da PUBLIC_KEY_CERTIFICATE_STRING constante de cadeia de caracteres e grava-a na saída.
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' your-cert.pem
```
Copie e cole o texto do certificado de saída para o valor constante.
Importante

No código de produção, tenha em atenção as seguintes considerações de segurança:
- A pré-programação da cadeia de ligação para o administrador do serviço de aprovisionamento vai contra as melhores práticas de segurança. Em vez disso, a cadeia de ligação deve ser mantida de forma segura, tal como num ficheiro de configuração seguro ou no registo.
- Carregue apenas a parte pública do certificado de assinatura. Nunca carregue ficheiros .pfx (PKCS12) ou .pem que contêm chaves privadas para o serviço de aprovisionamento.
O exemplo permite definir um hub IoT no grupo de registro para provisionar o dispositivo. Esse deve ser um hub IoT que foi vinculado anteriormente ao serviço de provisionamento. Para este artigo, permitimos que o DPS escolha entre os hubs vinculados de acordo com a política de alocação padrão, distribuição ponderada uniformemente. Comente a seguinte declaraçã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 inscrição 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 o exemplo do grupo de inscrição

Execute o exemplo:
```
dotnet run
```
Após a criação bem-sucedida, a janela de comando exibe as propriedades do novo grupo de registro.

Execute o seguinte comando no prompt de comando. Inclua as aspas ao redor dos argumentos do comando e substitua <connection string> pela cadeia de conexão copiada na seção anterior e <certificate .pem file> pelo caminho para o arquivo de certificado .pem . Esse arquivo representa a parte pública de um certificado raiz da CA X.509 que foi carregado e verificado anteriormente com seu 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>"
```
Após a criação bem-sucedida, a janela de comando exibe as propriedades do novo grupo de registro.

Na pasta azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample no prompt de comando, execute o seguinte comando para criar o exemplo:
```
mvn install -DskipTests
```
Este comando baixa o pacote Maven do cliente de serviço do Azure IoT DPS para sua máquina e cria o exemplo. Este pacote inclui os binários para o SDK do serviço Java.
Alterne para a pasta de destino e execute o exemplo. A compilação na etapa anterior produz .jar arquivo 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 comando exibe as propriedades do novo grupo de registro.

Para verificar se o grupo de inscrição foi criado:

No portal do Azure, navegue até sua instância do Serviço de Provisionamento de Dispositivo.
No menu Configurações, selecione Gerenciar inscrições.
Selecione a guia Grupos de inscrição. Você verá uma nova entrada de inscrição que corresponde à ID do grupo de inscrição que você usou no exemplo.

Clean up resources (Limpar recursos)

Se você planeja explorar os tutoriais do Serviço de Provisionamento de Dispositivo do Hub IoT do Azure, não limpe os recursos criados neste artigo. Caso contrário, use as etapas a seguir para excluir todos os recursos criados por este artigo.

Feche a janela de saída de exemplo no seu computador.
No menu à esquerda no portal do Azure, selecione Todos os recursos.
Selecione o Serviço de Provisionamento de Dispositivo.
No menu à esquerda, em Configurações, selecione Gerenciar inscrições.
Selecione a guia Grupos de inscrição.
Marque a caixa de seleção ao lado do nome do grupo de inscrição criado neste artigo.
Na parte superior da página, selecione Eliminar.
No seu Serviço de Provisionamento de Dispositivo no portal do Azure, selecione Certificados em Configurações no menu à esquerda.
Selecione o certificado que carregou para este artigo.
Na parte superior de Detalhes do certificado, selecione Excluir.

Ferramentas de certificado

O Azure IoT C SDK tem scripts que podem ajudá-lo a criar e gerenciar certificados. Para saber mais, consulte Gerenciando certificados de CA de teste para exemplos e tutoriais.

O SDK do Node.js do Azure IoT tem scripts que podem ajudá-lo a criar e gerenciar certificados. Para saber mais, consulte Ferramentas para o SDK do Dispositivo de Provisionamento de Dispositivo IoT do Azure para Node.js.

Você também pode usar as ferramentas disponíveis no SDK do Azure IoT C. Para saber mais, consulte Gerenciando certificados de CA de teste para exemplos e tutoriais.

O SDK Java do Azure IoT contém ferramentas de teste que podem ajudá-lo a criar e gerenciar certificados. Para saber mais, consulte Gerador de certificados X509 usando emulador DICE.

Próximos passos

Neste artigo, você criou um grupo de registro para um certificado de CA intermediário ou raiz X.509 usando o Serviço de Provisionamento de Dispositivo do Hub IoT do Azure. Para explorar mais, confira os seguintes links:

Para obter mais informações sobre o atestado de certificado X.509 com DPS, consulte Atestado de certificado X.509.
Para obter um exemplo completo de provisionamento de dispositivos 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 inscrições individuais e grupos de inscrição usando o portal do Azure, consulte Como gerenciar inscrições de dispositivo com o portal do Azure.

Partilhar via