Tutorial: Armazenar e usar credenciais do Azure Cosmos DB com o Azure Key Vault

  • Artigo

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Table

Importante

É recomendável acessar o Azure Cosmos DB é usar uma identidade gerenciada atribuída ao sistema. Se a solução de identidade gerenciada e a solução baseada em certificado não atenderem às suas necessidades, use a solução Azure Key Vault neste artigo.

Se você estiver usando o Azure Cosmos DB como banco de dados, conecta-se a bancos de dados, contêiner e itens usando um SDK, o ponto de extremidade da API e a chave primária ou secundária.

Não é uma boa prática armazenar o URI do ponto de extremidade e as chaves de leitura/gravação confidenciais diretamente no código do aplicativo ou no arquivo de configuração. O ideal é que esses dados sejam lidos de variáveis de ambiente dentro do host. No Serviço de Aplicativo do Azure, as configurações do aplicativo permitem injetar credenciais de runtime para sua conta do Azure Cosmos DB sem a necessidade de os desenvolvedores armazenarem essas credenciais de modo inseguro como texto não criptografado.

O Azure Key Vault itera ainda mais essa prática recomendada, permitindo que você armazene essas credenciais com segurança, fornecendo serviços como acesso gerenciado do Serviço de Aplicativo do Azure às credenciais. O Serviço de Aplicativo do Azure lerá com segurança suas credenciais do Azure Key Vault e injetará essas credenciais em seu aplicativo em execução.

Com essa prática recomendada, os desenvolvedores podem armazenar as credenciais para ferramentas como o emulador do Azure Cosmos DB ou Experimente o Azure Cosmos DB gratuitamente durante o desenvolvimento. Em seguida, a equipe de operações pode garantir que as configurações de produção corretas sejam injetadas em runtime.

Neste tutorial, você aprenderá como:

  • Criar uma instância do Azure Key Vault
  • Adicionar credenciais do Azure Cosmos DB como segredos ao cofre de chaves
  • Criar e registrar um recurso Serviço de Aplicativo do Azure e conceder permissões de "chave de leitura"
  • Injetar segredos do cofre de chaves no recurso Serviço de Aplicativo

Observação

Este tutorial e o aplicativo de exemplo usam uma conta do Azure Cosmos DB for NoSQL. Você pode executar muitas das mesmas etapas usando outras APIs.

Pré-requisitos

Antes de começar: Obter credenciais do Azure Cosmos DB

Antes de começar, você obterá as credenciais para sua conta existente.

  1. Navegue até a página portal do Azure da conta existente do Azure Cosmos DB for NoSQL.

  2. Na página da conta do Azure Cosmos DB for NoSQL, selecione a opção de menu de navegação Chaves.

    Captura de tela da página de uma conta da API de SQL do Azure Cosmos DB. A opção Chaves é realçada no menu de navegação.

  3. Registre os valores dos campos do URI e da PRIMARY KEY. Você usará esses valores mais adiante neste tutorial.

    Captura de tela da página Chaves com várias credenciais para uma conta da API de SQL do Azure Cosmos DB.

Criamos um recurso do Azure Key Vault

Primeiro, crie um novo cofre de chaves para armazenar suas credenciais de API para NoSQL.

  1. Entre no portal do Azure.

  2. Selecione Criar um recurso >Segurança > Key Vault.

  3. Na página Criar cofre de chaves, insira as seguintes informações:

    Configuração Descrição
    Assinatura Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos.
    Grupo de recursos Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.
    Nome do cofre de chaves Insira um nome exclusivo globalmente para o seu cofre de chaves.
    Região Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.
    Tipo de preços Selecione Padrão.

  4. Deixe as outras configurações com seus valores padrão.

  5. Selecione Examinar + criar.

  6. Examine as configurações fornecidas e selecione Criar. São necessários alguns minutos para criar a conta. Aguarde até que a página do portal exiba Sua implantação está concluída antes de continuar.

Adicionar chaves de acesso do Azure Cosmos DB no Key Vault

Agora, armazene suas credenciais do Azure Cosmos DB como segredos no cofre de chaves.

  1. Selecione Ir para o recurso para ir para a página de recursos do Azure Key Vault.

  2. Na página de recursos do Azure Key Vault, selecione a opção do menu de navegação Segredos.

  3. Selecione Gerar/importar no menu.

    Captura de tela da opção Gerar/Importar em um menu do cofre de chaves.

  4. Na página Criar um segredo, insira as seguintes informações:

    Configuração Descrição
    Opções de upload Manual
    Nome cosmos-endpoint
    Valor do segredo Insira o URI copiado anteriormente neste tutorial.

    Captura de tela da caixa de diálogo Criar um segredo no portal do Azure com detalhes de um segredo de URI.

  5. Selecione Criar para criar o novo segredo cosmos-endpoint.

  6. Selecione Gerar/importar no menu novamente. Na página Criar um segredo, insira as seguintes informações:

    Configuração Descrição
    Opções de upload Manual
    Nome cosmos-readwrite-key
    Valor do segredo Insira a CHAVE PRIMÁRIA copiada anteriormente neste tutorial.

    Captura de tela da caixa de diálogo Criar um segredo no portal do Azure com detalhes de um segredo de CHAVE PRIMÁRIA.

  7. Selecione Criar para criar o novo segredo cosmos-readwrite-key.

  8. Depois que os segredos forem criados, exiba-os na lista de segredos na página Segredos.

    Captura de tela da lista de segredos de um cofre de chaves.

  9. Selecione cada chave, selecione a versão mais recente e copie o Identificador de Segredo. Você usará o identificador para os segredos cosmos-endpoint e cosmos-readwrite-key mais adiante neste tutorial.

    Dica

    O identificador de segredo estará nesse formato https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id>. Por exemplo, se o nome do cofre de chaves for msdocs-key-vault, o nome da chave será cosmos-readwrite-key e a versão se 83b995e363d947999ac6cf487ae0e12e; em seguida, o identificador de segredo seria https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e.

    Captura de tela de um identificador de segredo para um segredo do cofre de chaves chamado cosmos-readwrite-key.

Criar e registrar um Aplicativo Web do Azure com o Azure Key Vault

Nesta seção, crie um Aplicativo Web do Azure, implante um aplicativo de exemplo e registre a identidade gerenciada do Aplicativo Web no Azure Key Vault.

  1. Crie um repositório GitHub usando o modelo cosmos-db-nosql-dotnet-sample-web-environment-variables.

  2. No portal do Azure, selecione Criar um recurso > Web > Aplicativo Web.

  3. Na página Criar Aplicativo Web e na guia Básico, insira as seguintes informações:

    Configuração Descrição
    Assinatura Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos.
    Grupo de recursos Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.
    Nome Insira um nome exclusivo globalmente para o aplicativo Web.
    Publicar Selecione Código.
    Pilha de runtime Selecione .NET 6 (LTS).
    Sistema operacional Selecione Windows.
    Região Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.

  4. Deixe as outras configurações com seus valores padrão.

  5. Selecione Avançar: Implantação.

  6. Na guia Implantação, insira as seguintes informações:

    Configuração Descrição
    Implantação contínua Selecione Habilitar.
    Conta do GitHub Selecione Autorizar. Siga os prompts de autorização da conta do GitHub para conceder permissão ao Azure para ler o repositório GitHub recém-criado.
    Organização Selecione a organização para seu novo repositório GitHub.
    Repositório Selecione o nome do novo repositório GitHub.
    Branch Selecione main.

  7. Selecione Examinar + criar.

  8. Examine as configurações fornecidas e selecione Criar. São necessários alguns minutos para criar a conta. Aguarde até que a página do portal exiba Sua implantação está concluída antes de continuar.

  9. Talvez seja necessário aguardar alguns minutos extras para que o aplicativo Web seja implantado inicialmente no aplicativo Web. Na página de recursos do Aplicativo Web do Azure, selecione Procurar para ver o estado padrão do aplicativo.

    Captura de tela do aplicativo Web em seu estado padrão sem credenciais.

  10. Selecione a opção de menu de navegação Identidade.

  11. Na página Identidade, selecione Ativado para identidade gerenciada atribuída pelo sistema e, em seguida, selecione Salvar.

    Captura de tela da identidade gerenciada atribuída pelo sistema que está sendo habilitada na página Identidade.

Injetar segredos de Azure Key Vault como configurações de aplicativo Web do Azure

Por fim, injete os segredos armazenados no cofre de chaves como configurações de aplicativo no aplicativo Web. As configurações do aplicativo, por sua vez, injetarão as credenciais no aplicativo em runtime sem armazenar as credenciais em texto não criptografado.

  1. Retorne à página do cofre de chaves no portal do Azure. Escolha Políticas de acesso no menu de navegação.

  2. Na página Políticas de acesso, selecione Criar no menu.

    Captura de tela da opção Criar no menu Políticas de acesso.

  3. Na guia Permissões da página Criar uma política de acesso, selecione a opção Obter na seção Permissões secretas. Selecione Avançar.

    Captura de tela da permissão Obter habilitada para permissões de Segredo.

  4. Na guia Entidade de segurança, selecione o nome do aplicativo Web criado anteriormente neste tutorial. Selecione Avançar.

    Captura de tela de uma identidade gerenciada de aplicativo Web atribuída a uma permissão.

    Observação

    Nesta captura de tela de exemplo, o aplicativo Web é denominado msdocs-dotnet-web.

  5. Selecione Avançar novamente para ignorar a guia Aplicativo. Na guia Examinar + criar, examine as configurações fornecidas e selecione Criar.

  6. Retorne à página de aplicativo Web no portal do Azure. Selecione Configuração no menu de navegação.

  7. Na página Configuração, selecione Nova configuração de aplicativo. Na caixa de diálogo Adicionar/Editar configuração do aplicativo, insira as seguintes informações:

    Configuração Descrição
    Nome CREDENTIALS__ENDPOINT
    Chave Obtenha o identificador de segredo para o segredo do cosmos-endpoint no cofre de chaves que você criou anteriormente neste tutorial. Insira o identificador no seguinte formato: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

    Dica

    Verifique se a variável de ambiente tem um valor de sublinhado duplo (__) em vez de um único sublinhado. O sublinhado duplo é um delimitador de chave compatível com o .NET em todas as plataformas. Para saber mais, confira Configurações de variáveis do ambiente.

    Observação

    Por exemplo, se o identificador de segredo for https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07, a referência será @Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07).

    Captura de tela da caixa de diálogo Adicionar/Editar configuração do aplicativo com uma nova configuração de aplicativo referenciando um segredo do cofre de chaves.

  8. Selecione OK para persistir a nova configuração de aplicativo

  9. Selecione Nova configuração de aplicativo novamente. Na caixa de diálogo Adicionar/Editar configuração do aplicativo, insira as seguintes informações e selecione OK:

    Configuração Descrição
    Nome CREDENTIALS__KEY
    Chave Obtenha o identificador de segredo para o segredo do cosmos-readwrite-key no cofre de chaves que você criou anteriormente neste tutorial. Insira o identificador no seguinte formato: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

  10. De volta à página Configuração, selecione Salvar para atualizar as configurações do aplicativo Web.

    Captura de tela da opção Salvar no menu da página Configuração.

  11. Aguarde alguns minutos para que o aplicativo Web seja reiniciado com as novas configurações do aplicativo. Neste ponto, as novas configurações de aplicativo devem indicar que elas são uma Referência do cofre de chaves.

    Captura de tela da designação de Referência do cofre de chaves em duas configurações de aplicativo em um aplicativo Web.

  12. No menu de navegação, selecione Visão geral. Selecione Procurar para ver o aplicativo com credenciais preenchidas.

    Captura de tela do aplicativo Web com credenciais válidas da conta do Azure Cosmos DB for NoSQL.

Próximas etapas