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

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Tabela

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 de cofre de chaves do Azure neste artigo.

Se você estiver usando o Azure Cosmos DB como seu banco de dados, conecte-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. Idealmente, esses dados são lidos a partir de variáveis de ambiente dentro do host. No Serviço de Aplicativo do Azure, as configurações do aplicativo permitem que você injete credenciais de tempo de execução para sua conta do Azure Cosmos DB sem a necessidade de os desenvolvedores armazenarem essas credenciais de maneira insegura de texto não criptografado.

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

Com essa prática recomendada, os desenvolvedores podem armazenar as credenciais de 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 tempo de execução.

Neste tutorial, irá aprender a:

• 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 do Serviço de Aplicativo do Azure e conceder permissões de "chave de leitura"
• Injetar segredos do cofre de chaves no recurso do Serviço de Aplicativo

Nota

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

Pré-requisitos

• Uma conta existente do Azure Cosmos DB para NoSQL.
  • Se você tiver uma assinatura do Azure, crie uma nova conta.
  • Se não tiver uma subscrição 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ê receberá as credenciais da sua conta existente.

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

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

   

3. Registre os valores dos campos URI e CHAVE PRIMÁRIA . Você usará esses valores mais adiante neste tutorial.

   

Criar um recurso do Azure Key Vault

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

1. Inicie sessão no portal do Azure.

2. Selecione Criar um recurso >Cofre da Chave de Segurança>.

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

   Definição	Descrição
   Subscrição	Selecione a assinatura do Azure que você deseja usar para esta conta do Azure Cosmos.
   Grupo de recursos	Selecione um grupo de recursos ou selecione Criar novo e, em seguida, introduza um nome exclusivo para o novo grupo de recursos.
   Nome do cofre da chave	Introduza um nome globalmente exclusivo para o seu cofre de chaves.
   Região	Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o acesso mais rápido aos dados.
   Escalão de preço	selecione Standard.

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

5. Selecione Rever + criar.

6. Reveja as definições fornecidas e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde até que a página do portal seja exibida Sua implantação foi concluída antes de prosseguir.

Adicionar chaves de acesso do Azure Cosmos DB ao Cofre da Chave

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 Cofre da Chave do Azure.

2. Na página de recursos do Cofre da Chave do Azure, 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:

   Definição	Descrição
   Opções de carregamento	Manual
   Nome	cosmos-ponto final
   Valor secreto	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:

   Definição	Descrição
   Opções de carregamento	Manual
   Nome	cosmos-readwrite-chave
   Valor secreto	Insira a CHAVE PRIMÁRIA que você copiou anteriormente neste tutorial.

   

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

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

   

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

   Gorjeta

   O identificador secreto estará neste 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 for cosmos-readwrite-key, e a versão se 83b995e363d947999ac6cf487ae0e12e, então o identificador secreto será 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 novo Aplicativo Web do Azure, implante um aplicativo de exemplo e registre a identidade gerenciada do Aplicativo Web no Cofre da Chave do Azure.

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

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

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

   Definição	Descrição
   Subscrição	Selecione a assinatura do Azure que você deseja usar para esta conta do Azure Cosmos.
   Grupo de recursos	Selecione um grupo de recursos ou selecione Criar novo e, em seguida, introduza um nome exclusivo para o novo grupo de recursos.
   Nome	Insira um nome globalmente exclusivo para seu aplicativo Web.
   Publicar	Selecione Código.
   Pilha de runtime	Selecione .NET 6 (LTS).
   Sistema operativo	Selecione Windows.
   Região	Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o acesso mais rápido aos dados.

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

5. Selecione Next: Deployment.

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

   Definição	Descrição
   Implementação contínua	Selecione Ativar.
   Conta do GitHub	Selecionar Autorizar. Siga os prompts de autorização de conta do GitHub para conceder permissão ao Azure para ler seu repositório do GitHub recém-criado.
   Organização	Selecione a organização para seu novo repositório GitHub.
   Repositório	Selecione o nome do seu novo repositório GitHub.
   Ramo	Selecione principal.

7. Selecione Rever + criar.

8. Reveja as definições fornecidas e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde até que a página do portal seja exibida Sua implantação foi concluída antes de prosseguir.

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 do menu de navegação Identidade .

11. Na página Identidade, selecione Ativado para Identidade gerenciada atribuída ao sistema e selecione Salvar.

    

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

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

1. Retorne à página do cofre de chaves no portal do Azure. Selecione 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 Seguinte.

   

4. Na guia Principal, selecione o nome do aplicativo Web criado anteriormente neste tutorial. Selecione Seguinte.

   

   Nota

   Neste exemplo de captura de tela, o aplicativo Web é chamado msdocs-dotnet-web.

5. Selecione Avançar novamente para ignorar a guia Aplicativo . No separador Rever + criar , reveja as definições fornecidas e, em seguida, selecione Criar.

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

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

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

   Gorjeta

   Certifique-se de que a variável de ambiente tenha um valor de sublinhado duplo (__) em vez de um único sublinhado. O sublinhado duplo é um delímetro chave suportado pelo .NET em todas as plataformas. Para obter mais informações, consulte Configuração de variáveis de ambiente.

   Nota

   Por exemplo, se o identificador secreto 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 manter a nova configuração do aplicativo

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

   Definição	Description
   Nome	CREDENTIALS__KEY
   Chave	Obtenha o identificador secreto para o segredo 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 até que o aplicativo Web seja reiniciado com as novas configurações do aplicativo. Neste ponto, as novas configurações do aplicativo devem indicar que são uma Referência do cofre de chaves.

    

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

    

Próximos passos

• Para configurar um firewall para o Azure Cosmos DB, consulte o artigo de suporte a firewall.
• Para configurar o ponto de extremidade do serviço de rede virtual, consulte o artigo sobre acesso seguro usando o ponto de extremidade do serviço VNet.