Gerenciar segredos para sua implantação das Operações do Azure IoT

As Operações do Azure IoT usam o Azure Key Vault como a solução de cofre gerenciado na nuvem e usam a extensão Repositório de segredos seguro do Azure Key Vault para Kubernetes para sincronizar os segredos da nuvem e armazená-los na borda como segredos do Kubernetes. Recursos de borda, como conectores e fluxos de dados, podem usar esses segredos para autenticação ao se conectar a sistemas externos.

Exemplos de segredos que você pode armazenar em Azure Key Vault para uso Operações do Azure IoT incluem:

Nomes de usuário e senhas para sistemas externos nos quais seus conectores ou fluxos de dados precisam se autenticar.
Certificados X.509 e chaves privadas para dispositivos ou serviços que usam TLS mútuo (mTLS).

Pré-requisitos

Para gerenciar segredos, você precisa de uma instância de Operações IoT do Azure implantada com configurações seguras. Se você implantou operações de IoT do Azure com configurações de teste, precisará primeiro habilitar as configurações seguras.

Configurar permissões do Azure Key Vault

Para usar a experiência de operações para criar segredos no cofre de chaves, o usuário requer permissões do Key Vault Secrets Officer no nível do recurso no Azure.

Em um ambiente de teste ou desenvolvimento, use as seguintes etapas para atribuir a função Key Vault Secrets Officer ao usuário no nível do grupo de recursos em que a instância de Operações IoT do Azure e a instância do Azure Key Vault são implantadas:

Para localizar o nome do grupo de recursos, acesse a interface do usuário da Web da experiência de operações , acesse a página Instâncias e localize sua instância de Operações de IoT do Azure. O nome do grupo de recursos é mostrado no campo Grupo de recursos.
Vá para o portal do Azure e vá para o grupo de recursos em que sua instância de Operações IoT do Azure e a instância do Azure Key Vault são implantadas.

Dica

Use a caixa de pesquisa na parte superior do portal do Azure para localizar rapidamente o grupo de recursos digitando o nome.
Selecione controle de acesso (IAM) no menu à esquerda. Em seguida, selecione + Adicionar > Atribuição de Função.
Na guia Função selecione Key Vault Secrets Officer na lista de papéis e depois selecione Avançar.
Na guia Membros, selecione Usuário, grupo ou entidade de serviço, selecione Selecionar membros, selecione o usuário ao qual deseja atribuir a função Responsável pelos segredos do Key Vault e selecione Avançar.
Clique em Revisar + atribuir para concluir a atribuição de função.

Em um ambiente de produção, siga as práticas recomendadas para proteger o Azure Key Vault que você usa com operações de IoT do Azure. Para obter mais informações, consulte as práticas recomendadas para usar o Azure Key Vault.

Adicionar e usar segredos

O gerenciamento de segredos para Operações do Azure IoT usa a extensão do repositório de segredos Azure Key Vault para sincronizar os segredos de um Azure Key Vault e armazená-los na periferia como segredos do Kubernetes. Quando você habilitou configurações seguras durante a implantação, selecionou um Azure Key Vault para gerenciamento de segredos. É neste Key Vault em que todos os segredos a serem usados nas Operações do Azure IoT são armazenados.

Observação

As instâncias das Operações do Azure IoT funcionam com apenas um Azure Key Vault. Não há suporte para vários cofres de chaves por instância.

Depois que as etapas de configurar o gerenciamento de segredos forem concluídas, você poderá adicionar segredos ao Azure Key Vault e sincronizá-los com o cluster do Kubernetes para serem usados em pontos de extremidade de entrada do dispositivo ou pontos de extremidade de fluxo de dados. Os segredos normalmente são nomes de usuário, senhas, certificados ou chaves privadas necessárias para autenticação em sistemas externos.

Você pode criar um segredo sincronizado no cluster usando a interface web da experiência de operações ou o CLI do Azure. Os dois fluxos se sobrepõem parcialmente: a experiência de operações pode carregar um novo valor para Azure Key Vault e sincronizá-lo com o cluster, enquanto o fluxo de CLI do Azure pressupõe que o segredo já existe no Azure Key Vault e manipula apenas a sincronização:

Esta seção usa pontos de extremidade de entrada do dispositivo que usam o nome de usuário e a autenticação de senha como exemplo. O mesmo processo se aplica aos pontos de extremidade de fluxo de dados.

Experiência de operações
CLI do Azure

A equipe de operações pode fazer upload de um novo valor de nome de usuário ou senha no Azure Key Vault e sincronizá-lo com o cluster em uma única etapa, ou sincronizar com o cluster um segredo existente do Key Vault.

Vá para a página Pontos de extremidade de entrada do dispositivo na interface Web do painel de operações.
Para adicionar uma nova referência secreta, selecione Adicionar referência ao criar um novo ponto de extremidade de entrada do dispositivo:
- Crie um novo segredo: cria um segredo no Azure Key Vault e sincroniza o segredo até o cluster usando a extensão do repositório secreto.
- Adicionar do Azure Key Vault: sincroniza um segredo existente no cofre de chaves até o cluster se ele não foi sincronizado antes. Selecionar essa opção mostra a lista de segredos no cofre de chaves selecionado. Somente a versão mais recente do segredo é sincronizada com o cluster.
Ao adicionar as referências de nome de usuário e senha aos dispositivos ou pontos de extremidade de fluxo de dados, você precisará dar um nome ao segredo sincronizado. As referências de segredo são salvas no cluster com esse nome fornecido como um recurso de sincronização de segredo. No exemplo da captura de tela a seguir, as referências de nome de usuário e senha são salvas no cluster como edp1secrets.

O fluxo de CLI do Azure pressupõe que os valores já estão armazenados como segredos em Azure Key Vault. Para saber como adicionar segredos ao Azure Key Vault, consulte Adicionar segredos ao Azure Key Vault.

Use az iot ops secretsync secret set para criar um segredo sincronizado no cluster que mapeia um ou mais segredos do Key Vault para chaves no segredo sincronizado. O exemplo a seguir cria um segredo sincronizado chamado my-endpoint-creds que mapeia os segredos Key Vault my-kv-username e my-kv-password para as chaves username e password:

az iot ops secretsync secret set \
  --instance <your-instance-name> \
  --resource-group <your-resource-group> \
  --name my-endpoint-creds \
  --secret target=username source=my-kv-username \
  --secret target=password source=my-kv-password

Para referenciar o segredo sincronizado de um endpoint de entrada do dispositivo, use o formato <synced-secret-name>/<key>. Por exemplo:

CLI do Azure: passe --user-ref my-endpoint-creds/username e --pass-ref my-endpoint-creds/password para az iot ops ns device endpoint inbound add.
Bicep: defina usernameSecretName: 'my-endpoint-creds/username' e passwordSecretName: 'my-endpoint-creds/password' no bloco usernamePasswordCredentials.

Sincronizar um certificado do cliente e uma chave privada para TLS mútuo

Vários conectores dão suporte à autenticação mTLS para fontes de dados de direção sul. Com o mTLS, o conector apresenta um certificado de cliente e uma chave privada ao endpoint sul para se autenticar nele, além de validar o certificado TLS do servidor. Atualmente, os seguintes conectores dão suporte ao mTLS para fontes de dados de direção sul:

Outros conectores, como o conector para mídia e o conector para ONVIF, atualmente não dão suporte a mTLS para fontes de dados de direção sul.

Você configura o mTLS no ponto de extremidade de entrada do dispositivo fazendo referência a um segredo sincronizado no cluster que contém o certificado do cliente e a chave privada. Você pode criar o segredo sincronizado usando a experiência de operações ou o CLI do Azure. Selecione a guia que corresponde à ferramenta que você deseja usar.

Experiência de operações
CLI do Azure

Ao criar o ponto de extremidade de entrada e escolher o modo de autenticação por certificado X509, você pode carregar um novo certificado e uma chave privada (a experiência de operações faz o upload deles para o Azure Key Vault e os sincroniza) ou escolher segredos existentes do Key Vault para sincronizar.

O fluxo de CLI do Azure pressupõe que o certificado e a chave privada já estão armazenados como segredos em Azure Key Vault. Você usa az iot ops secretsync secret set para criar um único segredo sincronizado no cluster que mapeia os segredos do Key Vault para chaves dentro do segredo sincronizado.

Para adicionar os arquivos de certificado e de chave privada como segredos para Azure Key Vault antes de sincronizá-los, consulte Dados segredos para Azure Key Vault.

O exemplo a seguir cria um segredo sincronizado chamado my-endpoint-cert que mapeia os segredos Key Vault my-kv-client-cert e my-kv-client-key para as chaves certificate e privateKey:

az iot ops secretsync secret set \
  --instance <your-instance-name> \
  --resource-group <your-resource-group> \
  --name my-endpoint-cert \
  --secret target=certificate source=my-kv-client-cert \
  --secret target=privateKey source=my-kv-client-key

Se o ponto de extremidade de direção sul exigir certificados intermediários, adicione um terceiro --secret target=intermediateCerts source=<my-kv-intermediate-certs> mapeamento.

Para referenciar o segredo sincronizado a partir do endpoint de entrada do dispositivo, use a forma <synced-secret-name>/<key>. Por exemplo:

CLI do Azure: passe --cert-ref my-endpoint-cert/certificate e --key-ref my-endpoint-cert/privateKey para az iot ops ns device endpoint inbound add. Para incluir certificados intermediários, também passe --icr my-endpoint-cert/intermediateCerts.

Bicep: defina method: 'Certificate' e referencie o segredo sincronizado no bloco x509Credentials:

authentication: {
    method: 'Certificate'
        x509Credentials: {
            certificateSecretName: 'my-endpoint-cert/certificate'
            keySecretName: 'my-endpoint-cert/privateKey'
        }
}

Gerenciar segredos sincronizados

Esta seção usa pontos de extremidade de entrada do dispositivo como exemplo. O mesmo processo pode ser aplicado a terminais de fluxo de dados.

Acesse a página Dispositivos na interface do usuário da Web da experiência de operações.
Para exibir a lista de segredos, selecione Gerenciar certificados e segredos e, em seguida, Segredos:

Você pode usar a página Segredos para exibir segredos sincronizados em seus dispositivos e pontos de extremidade de fluxo de dados. A página de segredos mostra a lista de todos os segredos sincronizados atuais na borda do recurso que você está exibindo. Um segredo sincronizado representa uma ou várias referências de segredo, dependendo do recurso que o usa. Qualquer operação aplicada a um segredo sincronizado se aplica a todas as referências secretas contidas no segredo sincronizado.

Você pode excluir segredos sincronizados da página Segredos . Quando você exclui um segredo sincronizado, ele exclui apenas o segredo sincronizado do cluster kubernetes e não exclui a referência secreta contida do Azure Key Vault. Você deve excluir o segredo do certificado manualmente do cofre de chaves.

Você também pode usar o CLI do Azure para exibir segredos sincronizados no cluster:

Para listar os recursos secretos sincronizados no cluster, use az iot ops secretsync list.
Para listar as referências individuais a segredos do Key Vault em um segredo sincronizado, use az iot ops secretsync secret list.

Aviso

A edição direta dos recursos personalizados SecretProviderClass e SecretSync no cluster do Kubernetes pode interromper o fluxo de segredos nas Operações do Azure IoT. Para quaisquer operações relacionadas a informações confidenciais, use a interface web de operações.

Antes de excluir um segredo sincronizado, verifique se todas as referências ao segredo dos componentes das Operações do Azure IoT foram removidas.

Adicionar segredos ao Azure Key Vault

Se você usar a experiência de operações para selecionar os segredos existentes que foram adicionados anteriormente ao Azure Key Vault, verifique se os segredos estão em um formato e codificação com suporte nas Operações de IoT do Azure.

Para adicionar um segredo de certificado PEM ao Azure Key Vault, você pode usar um comando como o seguinte exemplo:

az keyvault secret set \
  --vault-name <your-key-vault-name> \
  --name client-cert-pem \
  --file ./client-cert.pem \
  --encoding hex \
  --content-type 'application/x-pem-file'

Para adicionar um segredo de certificado DER binário ao Azure Key Vault, você pode usar um comando como o seguinte exemplo:

az keyvault secret set \
  --vault-name <your-key-vault-name> \
  --name cert-file-der \
  --file ./cert-file.der \
  --encoding hex \
  --content-type 'application/pkix-cert'

Comentários

Esta página foi útil?

Last updated on 2026-05-20