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

  • Artigo

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Tabela

Importante

Recomenda-se que aceda ao Azure Cosmos DB para utilizar uma identidade gerida atribuída pelo sistema. Se a solução de identidade gerida e a solução baseada em certificados não corresponderem às suas necessidades, utilize a solução do cofre de chaves do Azure neste artigo.

Se estiver a utilizar o Azure Cosmos DB como base de dados, ligue-se a bases de dados, contentores e itens com um SDK, o ponto final da API e a chave primária ou secundária.

Não é uma boa prática armazenar o URI do ponto final e as chaves confidenciais de leitura-escrita diretamente no código da aplicação ou no ficheiro de configuração. Idealmente, estes dados são lidos a partir de variáveis de ambiente no anfitrião. No Serviço de Aplicações do Azure, as definições da aplicação permitem-lhe injetar credenciais de runtime para a sua conta do Azure Cosmos DB sem a necessidade de os programadores armazenarem estas credenciais de forma insegura e clara.

O Azure Key Vault itera ainda mais esta melhor prática ao permitir-lhe armazenar estas credenciais de forma segura, ao mesmo tempo que fornece serviços como Serviço de Aplicações do Azure acesso gerido às credenciais. Serviço de Aplicações do Azure irá ler as suas credenciais de forma segura a partir do Azure Key Vault e injetar essas credenciais na sua aplicação em execução.

Com esta melhor prática, os programadores podem armazenar as credenciais para ferramentas como o emulador do Azure Cosmos DB ou Experimentar gratuitamente o Azure Cosmos DB durante o desenvolvimento. Em seguida, a equipa de operações pode garantir que as definições de produção corretas são injetadas no runtime.

Neste tutorial, ficará a saber como:

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

Nota

Este tutorial e a aplicação de exemplo utilizam uma conta do Azure Cosmos DB para NoSQL. Pode executar muitos dos mesmos passos com outras APIs.

Pré-requisitos

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

Antes de começar, obterá as credenciais da sua conta existente.

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

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

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

  3. Registe os valores dos campos URI e CHAVE PRIMÁRIA . Irá utilizar estes valores mais adiante neste tutorial.

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

Criar um recurso do Azure Key Vault

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

  1. Inicie sessão no portal do Azure.

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

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

    Definições Descrição
    Subscrição Selecione a subscrição do Azure que pretende utilizar 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 Key Vault Introduza um nome globalmente exclusivo para o 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 restantes definições nos valores predefinidos.

  5. Selecione Rever + criar.

  6. Reveja as definições que fornece e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde até que a página do portal apresente A implementação está concluída antes de avançar.

Adicionar chaves de acesso do Azure Cosmos DB ao Key Vault

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

  1. Selecione Ir para recurso para aceder à página de recursos do Azure Key Vault.

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

  3. Selecione Gerar/Importar no menu.

    Captura de ecrã a mostrar a opção Gerar/Importar num menu do cofre de chaves.

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

    Definições Descrição
    Opções de carregamento Manual
    Nome cosmos-endpoint
    Valor secreto Introduza o URI que copiou anteriormente neste tutorial.

    Captura de ecrã a mostrar a caixa de diálogo Criar um segredo no portal do Azure com detalhes para um segredo do URI.

  5. Selecione Criar para criar o novo segredo do ponto final do cosmos .

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

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

    Captura de ecrã a mostrar a caixa de diálogo Criar um segredo no portal do Azure com detalhes para um segredo de CHAVE PRIMÁRIA.

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

  8. Depois de os segredos serem criados, veja-os na lista de segredos na página Segredos .

    Captura de ecrã a mostrar a lista de segredos de um cofre de chaves.

  9. Selecione cada chave, selecione a versão mais recente e, em seguida, copie o Identificador secreto. Irá utilizar o identificador para os segredos cosmos-endpoint e cosmos-readwrite-key mais adiante neste tutorial.

    Dica

    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 é cosmos-readwrite-key e a versão se 83b995e363d947999ac6cf487ae0e12e; em seguida, o identificador secreto seria https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e.

    Captura de ecrã de um identificador secreto de um segredo do cofre de chaves com o nome cosmos-readwrite-key.

Criar e registar uma Aplicação Web do Azure com o Azure Key Vault

Nesta secção, crie uma nova Aplicação Web do Azure, implemente uma aplicação de exemplo e, em seguida, registe a identidade gerida da Aplicação Web com o Azure Key Vault.

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

  2. No portal do Azure, selecione Criar uma Aplicação Web > de recurso>.

  3. No separador Criar Aplicação Web e Noções Básicas , introduza as seguintes informações:

    Definições Descrição
    Subscrição Selecione a subscrição do Azure que pretende utilizar 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 Introduza um nome globalmente exclusivo para a sua aplicação 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 restantes definições nos valores predefinidos.

  5. Selecione Seguinte: Implementação.

  6. No separador Implementação , introduza as seguintes informações:

    Definições Descrição
    Implementação contínua Selecione Ativar.
    Conta do GitHub Selecione Autorizar. Siga os pedidos de autorização da conta do GitHub para conceder permissão ao Azure para ler o repositório do GitHub recentemente criado.
    Organização Selecione a organização para o seu novo repositório do GitHub.
    Repositório Selecione o nome do seu novo repositório do GitHub.
    Ramo Selecione principal.

  7. Selecione Rever + criar.

  8. Reveja as definições que fornece e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde até que a página do portal apresente A implementação está concluída antes de avançar.

  9. Poderá ter de aguardar alguns minutos adicionais para que a aplicação Web seja implementada inicialmente na aplicação Web. Na página de recursos da Aplicação Web do Azure, selecione Procurar para ver o estado predefinido da aplicação.

    Captura de ecrã a mostrar a aplicação Web no estado predefinido sem credenciais.

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

  11. Na página Identidade , selecione Ativado para Identidade gerida atribuída pelo sistema e, em seguida, selecione Guardar.

    Captura de ecrã a mostrar a identidade gerida atribuída pelo sistema a ser ativada a partir da página Identidade.

Injetar segredos do Azure Key Vault como definições da aplicação Web do Azure

Por fim, injete os segredos armazenados no cofre de chaves como definições de aplicação na aplicação Web. As definições da aplicação irão, por sua vez, injetar as credenciais na aplicação no runtime sem armazenar as credenciais em texto claro.

  1. Regresse à 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.

    Captura de ecrã a mostrar a opção Criar no menu Políticas de acesso.

  3. No separador Permissões da página Criar uma política de acesso , selecione a opção Obter na secção Permissões do segredo . Selecione Seguinte.

    Captura de ecrã a mostrar a permissão Obter ativada para permissões secretas.

  4. No separador Principal , selecione o nome da aplicação Web que criou anteriormente neste tutorial. Selecione Seguinte.

    Captura de ecrã a mostrar uma identidade gerida de uma aplicação Web atribuída a uma permissão.

    Nota

    Neste exemplo, captura de ecrã, a aplicação Web tem o nome msdocs-dotnet-web.

  5. Selecione Seguinte novamente para ignorar o separador Aplicação . No separador Rever + criar , reveja as definições que fornecer e, em seguida, selecione Criar.

  6. Regresse à página da aplicação Web no portal do Azure. Selecione Configuração no menu de navegação.

  7. Na página Configuração , selecione Nova definição da aplicação. Na caixa de diálogo Adicionar/Editar definição da aplicação , introduza as seguintes informações:

    Definições Descrição
    Nome CREDENTIALS__ENDPOINT
    Chave Obtenha o identificador secreto para o segredo do ponto final do cosmos no cofre de chaves que criou anteriormente neste tutorial. Introduza o identificador no seguinte formato: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

    Dica

    Certifique-se de que a variável de ambiente tem um valor de sublinhado duplo (__) em vez de um único caráter de sublinhado. O sublinhado duplo é um delimetrador chave suportado pelo .NET em todas as plataformas. Para obter mais informações, veja 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).

    Captura de ecrã a mostrar a caixa de diálogo Adicionar/Editar definição da aplicação com uma nova definição de aplicação que referencia um segredo do cofre de chaves.

  8. Selecione OK para manter a nova definição da aplicação

  9. Selecione Nova definição da aplicação novamente. Na caixa de diálogo Adicionar/Editar definição da aplicação , introduza as seguintes informações e, em seguida, selecione OK:

    Definições Descrição
    Nome CREDENTIALS__KEY
    Chave Obtenha o identificador secreto para o segredo cosmos-readwrite-key no seu cofre de chaves que criou anteriormente neste tutorial. Introduza o identificador no seguinte formato: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

  10. Novamente na página Configuração , selecione Guardar para atualizar as definições da aplicação para a aplicação Web.

    Captura de ecrã a mostrar a opção Guardar no menu da página Configuração.

  11. Aguarde alguns minutos para que a aplicação Web seja reiniciada com as novas definições da aplicação. Neste momento, as novas definições da aplicação devem indicar que são uma Referência do Cofre de Chaves.

    Captura de ecrã a mostrar a designação Referência do Cofre de chaves em duas definições de aplicação numa aplicação Web.

  12. Selecione Descrição geral no menu de navegação. Selecione Procurar para ver a aplicação com credenciais preenchidas.

    Captura de ecrã da aplicação Web com credenciais válidas do Azure Cosmos DB para conta NoSQL.

Passos seguintes