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

APLICA-SE AO: 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

• Uma conta do Azure Cosmos DB for NoSQL.
  • Se você tiver uma assinatura do Azure, crie uma nova conta.
  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
  • Como alternativa, você pode experimentar o Azure Cosmos DB gratuitamente antes de confirmar.
• Conta do GitHub.

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.

   

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

   

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.

   

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.

   

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.

   

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.

   

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.

   

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.

   

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.

    

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.

   

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.

   

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

   

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

   

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.

    

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.

    

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

    

Próximas etapas

• Para configurar um firewall para o Azure Cosmos DB, consulte o artigo suporte de firewall.
• Para configurar o ponto de extremidade de serviço de rede virtual, confira o artigo Proteger o acesso usando o ponto de extremidade de serviço da VNET.