Utilizar o fornecedor de configuração do Azure Key Vault no ASP.NET Core

Este artigo explica como utilizar o provedor de configuração Azure Key Vault para carregar valores de configuração da aplicação a partir dos segredos do Key Vault. O Key Vault é um serviço baseado na cloud que ajuda a proteger chaves criptográficas e segredos usados por aplicações e serviços. Cenários comuns para usar o Key Vault com aplicações ASP.NET Core incluem:

• Controlando o acesso a dados de configuração confidenciais.
• Cumprimento do requisito de Módulos de Segurança de Hardware (HSMs) validados pelo FIPS 140-2 Nível 2 ao armazenar dados de configuração.

Packages

Adicione referências de pacote para os seguintes pacotes:

• Azure.Extensions.AspNetCore.Configuration.Secrets
• Azure.Identity

Aplicativo de exemplo

A aplicação de exemplo corre em dois modos determinados pela #define diretiva do pré-processador no topo do ficheiro Program.cs :

• Certificate: Demonstra como usar um ID de cliente Key Vault e um certificado X.509 para aceder a segredos armazenados numa key vault. Pode executar o exemplo a partir de qualquer localização, seja implementado no Serviço de Aplicações do Azure ou em qualquer host que sirva uma aplicação ASP.NET Core.

• Managed: Demonstra como usar identidades gerenciadas para recursos do Azure. A identidade gerida autentica a aplicação no Key Vault com identidades geridas para recursos Azure sem armazenar credenciais no código da aplicação ou na configuração. A Managed versão do exemplo deve ser implantada no Azure. Siga as orientações na seção Usar as identidades gerenciadas para recursos do Azure .

Para mais informações sobre a configuração de uma aplicação de exemplo usando #define, veja Diretivas de Pré-processador no código de exemplo.

Visualizar ou descarregar amostra de código (como descarregar)

Armazenamento secreto no ambiente de desenvolvimento

Defina segredos localmente usando a ferramenta Gestor de Segredos . Quando a aplicação de exemplo é executada na máquina local no ambiente Development, os segredos são carregados a partir do armazém local de segredos do utilizador.

O Secret Manager requer uma <UserSecretsId> propriedade no ficheiro do projeto da aplicação. Defina o valor da propriedade ({GUID}) para qualquer GUID exclusivo:

<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>

Os segredos são criados como pares nome-valor. Os valores hierárquicos (secções de configuração) utilizam os dois-pontos (:) como separadores nos nomes de chaves da configuração do ASP.NET Core.

O Gestor de Segredos é usado numa shell de comandos (ou terminal) aberta na raiz de conteúdo do projeto, onde {SECRET NAME} é o nome e {SECRET VALUE} é o valor:

dotnet user-secrets set "{SECRET NAME}" "{SECRET VALUE}"

Execute os seguintes comandos numa shell de comandos a partir da raiz de conteúdo do projeto. Os comandos definem os segredos para a aplicação de exemplo:

dotnet user-secrets set "SecretName" "secret_value_1_dev"
dotnet user-secrets set "Section:SecretName" "secret_value_2_dev"

Quando estes segredos são armazenados no Key Vault, conforme descrito na secção Armazenamento de segredos no ambiente de Produção com o Key Vault, o sufixo _dev passa a _prod. O sufixo fornece uma pista visual na saída da aplicação indicando a origem dos valores de configuração.

Armazenamento secreto no ambiente de Produção com Key Vault

Crie um cofre de chaves do Azure e armazene os segredos de exemplo da aplicação completando os seguintes passos. Para mais informações, consulte Quickstart: Definir e recuperar um segredo de Key Vault com a CLI do Azure.

1. Abra Azure Cloud Shell utilizando qualquer um dos seguintes métodos no portal Azure:

   • Selecione Experimentar no canto superior direito de um bloco de código. Use a cadeia de caracteres de pesquisa "CLI do Azure" na caixa de texto.
   • Abra o Cloud Shell no seu navegador com o botão Launch Cloud Shell .
   • Selecione o botão Cloud Shell no menu no canto superior direito do portal do Azure.

   Para mais informações, consulte a documentação CLI do Azure e Visão geral de Azure Cloud Shell.

2. Se ainda não estiver autenticado, inicie sessão com o az login comando.

3. Crie um grupo de recursos com o seguinte comando, onde {RESOURCE GROUP NAME} é o nome do novo grupo de recursos e {LOCATION} é a região Azure:

   az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
   

4. Crie um cofre de chaves Azure no grupo de recursos com o seguinte comando, onde {KEY VAULT NAME} é o nome do novo cofre e {LOCATION} é a região Azure:

   az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
   

5. Crie segredos no cofre como pares nome-valor.

   Key Vault nomes secretos podem consistir em caracteres alfanuméricos e traços (-). Valores hierárquicos (secções de configuração) usam dois traços ou hífens (--) como delimitador. O personagem dos dois não é permitido nos nomes secretos do Key Vault. Os dois pontos delimitam uma seção de uma subchave na configuração ASP.NET Core. A sequência de dois traços é substituída por dois pontos quando os segredos são carregados na configuração da aplicação.

   Os segredos a seguir são para uso com o aplicativo de exemplo. Os valores incluem o sufixo _prod, que os distingue dos valores com o sufixo _dev carregados no ambiente Development através do Gestor de Segredos. Substitua {KEY VAULT NAME} pelo nome do cofre de chaves que criou anteriormente:

   az keyvault secret set --vault-name {KEY VAULT NAME} --name "SecretName" --value "secret_value_1_prod"
   az keyvault secret set --vault-name {KEY VAULT NAME} --name "Section--SecretName" --value "secret_value_2_prod"
   

Usar a ID do Aplicativo e o certificado X.509 para aplicativos não hospedados no Azure

Configure o Key Vault e a aplicação para utilizarem um ID de Aplicação do Microsoft Entra ID e um certificado X.509 para se autenticarem num cofre quando a aplicação estiver alojada fora do Azure. Para obter mais informações, consulte Sobre chaves, segredos e certificados.

A aplicação de exemplo utiliza um ID de Aplicação e um certificado X.509 quando a #define diretiva do pré-processador no topo do ficheiro Program.cs está definida como Certificate.

1. Crie um certificado PKCS#12 archive (.pfx). As opções para criar certificados incluem New-SelfSignedCertificate no Windows e OpenSSL.

2. Instale o certificado no armazenamento de certificados pessoais do usuário atual. Marcar a chave como exportável é opcional. Observe a impressão digital do certificado, que é usada posteriormente neste processo.

3. Exporte o certificado de arquivo PKCS#12 (.pfx) como um certificado codificado por DER (.cer).

4. Registe a aplicação com o Microsoft Entra ID (Registos de aplicações).

5. Carregar o certificado codificado em DER (.cer) para Microsoft Entra ID:

   1. Selecione o aplicativo no Microsoft Entra ID.
   2. Vai a Certificados e Segredos.
   3. Selecione Carregar certificado para carregar o certificado, que contém a chave pública. Um certificado .cer, .pem ou .crt é aceitável.

6. Armazene o nome do cofre de chaves, o ID da aplicação e a impressão digital do certificado no ficheiro appsettings.json da aplicação.

7. No portal do Azure, aceda a Key Vaults.

8. Selecione o cofre de chaves que criou na secção Armazenamento de segredos no ambiente de Produção com o Azure Key Vault.

9. Selecione políticas de acesso e depois selecione Adicionar Política de Acesso.

10. Abra as permissões Secreto e forneça ao aplicativo as permissões Obter e Listar .

11. Escolha Selecionar principal. Selecione a aplicação registada pelo nome e depois selecione Selecionar.

12. Selecione OK e, em seguida, selecione Guardar.

13. Implante o aplicativo.

A Certificate aplicação de exemplo obtém os valores de configuração de IConfigurationRoot com o mesmo nome do nome secreto:

• Valores não hierárquicos: O valor para SecretName é obtido com config["SecretName"].
• Valores hierárquicos (secções): Utilize a notação de dois-pontos (:) ou o método GetSection. Use uma das seguintes abordagens para obter o valor de configuração:
  • config["Section:SecretName"]
  • config.GetSection("Section")["SecretName"]

O sistema operativo gere o certificado X.509. A aplicação chama o método AddAzureKeyVault com valores fornecidos pelo ficheiro appsettings.json:

using System.Security.Cryptography.X509Certificates;
using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsProduction())
{
    using var x509Store = new X509Store(StoreLocation.CurrentUser);

    x509Store.Open(OpenFlags.ReadOnly);

    var x509Certificate = x509Store.Certificates
        .Find(
            X509FindType.FindByThumbprint,
            builder.Configuration["AzureADCertThumbprint"],
            validOnly: false)
        .OfType<X509Certificate2>()
        .Single();

    builder.Configuration.AddAzureKeyVault(
        new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
        new ClientCertificateCredential(
            builder.Configuration["AzureADDirectoryId"],
            builder.Configuration["AzureADApplicationId"],
            x509Certificate));
}

var app = builder.Build();

Exemplos de valores:

• Nome do Key Vault: contosovault
• ID do aplicativo: 00001111-aaaa-2222-bbbb-3333cccc4444
• Impressão digital do certificado: fe14593dd66b2406c5269d742d04b6e1ab03adb1

Os valores no ficheiro appsettings.json:

{
  "KeyVaultName": "Key Vault Name",
  "AzureADApplicationId": "Azure AD Application ID",
  "AzureADCertThumbprint": "Azure AD Certificate Thumbprint",
  "AzureADDirectoryId": "Azure AD Directory ID"
}

Quando você executa o aplicativo, uma página da Web mostra os valores secretos carregados. No ambiente Development, os valores secretos são carregados com o sufixo _dev. No Production ambiente, os valores carregam com o _prod sufixo.

Usar identidades gerenciadas para recursos do Azure

Um aplicativo implantado no Azure pode aproveitar as identidades gerenciadas para recursos do Azure. Uma identidade gerida permite que a aplicação se autentique com o Azure Key Vault utilizando autenticação Microsoft Entra ID sem armazenar credenciais no código ou configuração da aplicação.

A aplicação de exemplo utiliza uma identidade gerida atribuída pelo sistema quando a #define diretiva do pré-processador no topo do ficheiro de Program.cs está definida como Managed. Para criar uma identidade gerenciada para um aplicativo do Serviço de Aplicativo do Azure, consulte Como usar identidades gerenciadas para o Serviço de Aplicativo e o Funções do Azure. Depois de criada a identidade gerida, tome nota do ID do objeto da aplicação apresentado no painel Identity do App Service no portal do Azure.

Introduza o nome do cofre de chaves no ficheiroappsettings.json da aplicação. O aplicativo de exemplo não requer uma ID de Aplicativo e Senha (Segredo do Cliente) quando definido para a Managed versão, portanto, você pode ignorar essas entradas de configuração. A aplicação é implementada para Azure e Azure autentica a aplicação para aceder a Key Vault apenas usando o nome do cofre armazenado no ficheiro appsettings.json.

Implante o aplicativo de exemplo no Serviço de Aplicativo do Azure.

Usando o CLI do Azure e o ID de Objeto da aplicação, forneça à aplicação permissões list e get para aceder ao cofre de chaves:

az keyvault set-policy --name {KEY VAULT NAME} --object-id {OBJECT ID} --secret-permissions get list

Reinicie a aplicação utilizando a CLI do Azure, o Azure PowerShell ou o portal do Azure.

O aplicativo de exemplo cria uma instância da DefaultAzureCredential classe. A credencial tenta obter um token de acesso do ambiente para recursos do Azure:

using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsProduction())
{
    builder.Configuration.AddAzureKeyVault(
        new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
        new DefaultAzureCredential());
}

Nome de exemplo para o cofre de chaves: contosovault

O valor de nome no ficheiro appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Para aplicações que utilizam uma identidade gerida atribuída pelo utilizador, configure o ID do Cliente da identidade gerida utilizando uma das seguintes abordagens:

• Defina a variável de ambiente AZURE_CLIENT_ID.

• Defina a DefaultAzureCredentialOptions.ManagedIdentityClientId propriedade ao chamar o AddAzureKeyVault método:

  builder.Configuration.AddAzureKeyVault(
      new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
      new DefaultAzureCredential(new DefaultAzureCredentialOptions
      {
          ManagedIdentityClientId = builder.Configuration["AzureADManagedIdentityClientId"]
      }));
  

Quando você executa o aplicativo, uma página da Web mostra os valores secretos carregados. No Development ambiente, os valores secretos têm o _dev sufixo porque são fornecidos pelo Secret Manager. No Production ambiente, os valores são carregados com o sufixo _prod porque são fornecidos pelo Azure Key Vault.

Se receber um erro Access denied, confirme que a aplicação está registada na Microsoft Entra ID e tem acesso ao cofre. Confirma que reiniciaste o serviço no Azure.

Para obter informações sobre como utilizar o provedor com uma identidade gerida e o Azure Pipelines, consulte Ligue-se ao Azure com uma ligação de serviço do Azure Resource Manager.

Opções de configuração

O AddAzureKeyVault método pode aceitar um AzureKeyVaultConfigurationOptions objeto:

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new AzureKeyVaultConfigurationOptions
    {
        // ...
    });

O AzureKeyVaultConfigurationOptions objeto contém as seguintes propriedades:

Usar um prefixo para o nome da chave

O método AddAzureKeyVault disponibiliza uma sobrecarga que aceita uma implementação de KeyVaultSecretManager, o que lhe permite controlar como os segredos do Key Vault são convertidos em chaves de configuração. Por exemplo, você pode implementar a interface para carregar valores secretos com base em um valor de prefixo fornecido na inicialização do aplicativo. Essa técnica permite, por exemplo, carregar segredos com base na versão do aplicativo.

No exemplo seguinte, um segredo é estabelecido em Key Vault (usando o Gestor de Segredos para o ambiente Development) para 5000-AppSecret (períodos não são permitidos em nomes secretos Key Vault). Esse segredo representa um segredo de aplicativo para a versão 5.0.0.0 do aplicativo. Para outra versão da aplicação, 5.1.0.0, um segredo é adicionado ao mesmo cofre de chaves (usando o Gestor de Segredos) para 5100-AppSecret. Cada versão do aplicativo carrega seu valor de segredo versionado em sua configuração como AppSecret, removendo a versão à medida que carrega o segredo.

O AddAzureKeyVault método é chamado com uma implementação personalizada KeyVaultSecretManager :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SamplePrefixKeyVaultSecretManager("5000"));

A implementação reage aos prefixos de versão de segredos para carregar o segredo adequado na configuração:

• O Load método carrega um segredo quando o nome começa com o prefixo. Outros segredos não são carregados.
• O GetKey método:
  • Remove o prefixo do nome secreto.
  • Substitui dois traços (--) em qualquer nome pelo KeyDelimiter. Este delimitador (normalmente um dois-pontos :) é utilizado na configuração porque o Key Vault não permite um dois-pontos (:) em nomes de segredos.

public class SamplePrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

    public SamplePrefixKeyVaultSecretManager(string prefix)
        => _prefix = $"{prefix}-";

    public override bool Load(SecretProperties properties)
        => properties.Name.StartsWith(_prefix);

    public override string GetKey(KeyVaultSecret secret)
        => secret.Name[_prefix.Length..].Replace("--", ConfigurationPath.KeyDelimiter);
}

Um algoritmo do fornecedor chama o método Load e percorre os segredos do cofre de chaves para encontrar os segredos prefixados com a versão. Quando um prefixo de versão é encontrado com Load, o algoritmo usa o GetKey método para retornar o nome de configuração do nome secreto. Ele remove o prefixo da versão do nome do segredo. O resto do nome do segredo é devolvido para carregamento nos pares nome-valor da configuração da aplicação.

Ao implementar esta abordagem, complete os seguintes passos:

1. Especifique a versão da aplicação no ficheiro do projeto da aplicação. No exemplo seguinte, a versão da aplicação é definida para 5.0.0.0:

   <PropertyGroup>
     <Version>5.0.0.0</Version>
   </PropertyGroup>
   

2. Confirme que a <UserSecretsId> propriedade está definida no ficheiro do projeto da aplicação, onde {GUID} é um GUID fornecido pelo utilizador:

   <PropertyGroup>
     <UserSecretsId>{GUID}</UserSecretsId>
   </PropertyGroup>
   

   Guarde os seguintes segredos localmente usando o Secret Manager:

   dotnet user-secrets set "5000-AppSecret" "5.0.0.0_secret_value_dev"
   dotnet user-secrets set "5100-AppSecret" "5.1.0.0_secret_value_dev"
   

3. Guarde os segredos no Azure Key Vault usando os seguintes comandos do CLI do Azure:

   az keyvault secret set --vault-name {KEY VAULT NAME} --name "5000-AppSecret" --value "5.0.0.0_secret_value_prod"
   az keyvault secret set --vault-name {KEY VAULT NAME} --name "5100-AppSecret" --value "5.1.0.0_secret_value_prod"
   

O processo completa as seguintes tarefas:

• Quando a aplicação é executada, a implementação carrega os segredos do Key Vault. A cadeia secreta para 5000-AppSecret corresponde à versão da aplicação especificada no ficheiro de projeto da aplicação (5.0.0.0).

• A versão, 5000 (com o traço), é removida do nome da chave. Em todo o aplicativo, a leitura da configuração com a chave AppSecret carrega o valor secreto.

• Se a versão da aplicação for alterada no ficheiro do projeto para 5.1.0.0 e a aplicação for executada novamente, o valor secreto devolvido está 5.1.0.0_secret_value_dev no Development ambiente e 5.1.0.0_secret_value_prod em Production.

Vincular uma matriz a uma classe

O provedor pode ler valores de configuração em uma matriz para ligação a uma matriz POCO.

Ao ler a partir de uma fonte de configuração que permite que as chaves contenham separadores de dois pontos (:), é utilizado um segmento de chave numérica para distinguir as chaves que compõem uma matriz (:0:, :1:, ... :{n}:). Para obter mais informações, consulte Configuração: vincular uma matriz a uma classe.

As chaves do Key Vault não podem usar dois pontos (:) como um separador. A abordagem descrita usa, neste artigo, traços duplos (--) como separador para valores hierárquicos (seções). As chaves da matriz são armazenadas no Key Vault com traços duplos e segmentos numéricos da chave (--0--, --1--, … --{n}--).

Examine a seguinte configuração do fornecedor de registo Serilog fornecida num ficheiro JSON. Existem dois literais de objetos definidos na matriz WriteTo que correspondem a dois destinos Serilog, os quais descrevem locais para onde a saída de log é enviada.

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

A configuração no ficheiro JSON é armazenada no Key Vault, utilizando a notação com traço duplo (--) e segmentos numéricos:

Recarregar segredos

Por defeito, o fornecedor de configuração armazena em cache os segredos durante a vida útil da aplicação. A aplicação ignora segredos que mais tarde são desativados ou atualizados no cofre de chaves.

Para recarregar segredos, invoque o método IConfigurationRoot.Reload:

config.Reload();

Para recarregar segredos periodicamente, em um intervalo especificado, defina a AzureKeyVaultConfigurationOptions.ReloadInterval propriedade. Para obter mais informações, consulte Opções de configuração.

Segredos desativados e expirados

Os segredos expirados são incluídos por padrão no provedor de configuração. Para excluir valores destes segredos na configuração da aplicação, atualize o segredo expirado ou forneça a configuração usando um fornecedor de configuração personalizado:

class SampleKeyVaultSecretManager : KeyVaultSecretManager
{
  public override bool Load(SecretProperties properties) =>
    properties.ExpiresOn.HasValue &&
    properties.ExpiresOn.Value > DateTimeOffset.Now;
}

Passe este provedor personalizado KeyVaultSecretManager ao método AddAzureKeyVault:

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SampleKeyVaultSecretManager());

Segredos desativados não podem ser recuperados do Key Vault e nunca são incluídos.

Resolva problemas de carregamento da configuração

Quando a aplicação falha em carregar a configuração usando o fornecedor, é gravada uma mensagem de erro na infraestrutura de registo ASP.NET Core.

As seguintes condições podem impedir o carregamento da configuração:

• O aplicativo ou certificado não está configurado corretamente no Microsoft Entra ID.
• O cofre não existe no Azure Key Vault.
• A aplicação não está autorizada a acessar o cofre.
• A política de acesso não inclui Get e List permissões.
• No vault, os dados de configuração (par nome-valor) estão incorretamente nomeados, ausentes ou desativados.
• A aplicação tem o nome do cofre de chaves incorreto (KeyVaultName), o ID da aplicação do Microsoft Entra ID (AzureADApplicationId), a impressão digital do certificado do Microsoft Entra ID (AzureADCertThumbprint) ou o ID do diretório do Microsoft Entra ID (AzureADDirectoryId).
• Quando a política de acesso Key Vault é adicionada para a aplicação, a política é criada com sucesso, mas o utilizador não selecionou Save no diálogo Políticas de Acesso.

Conteúdo relacionado

• Visualizar ou descarregar amostra de código (como descarregar)
• Configuração no ASP.NET Core
• Documentação do Azure Key Vault
• Importar chaves protegidas por HSM para Azure Key Vault
• Quickstart: Azure Key Vault biblioteca secreta de clientes para .NET
• Tutorial: Usar o Azure Key Vault com uma máquina virtual no .NET

Este artigo explica como usar o provedor de configuração do Azure Key Vault para carregar valores de configuração de aplicativo dos segredos do Azure Key Vault. O Azure Key Vault é um serviço baseado na nuvem que ajuda a proteger chaves criptográficas e segredos usados por aplicativos e serviços. Os cenários comuns para usar o Azure Key Vault com aplicativos ASP.NET Core incluem:

• Controlando o acesso a dados de configuração confidenciais.
• Cumprimento do requisito de Módulos de Segurança de Hardware (HSMs) validados pelo FIPS 140-2 Nível 2 ao armazenar dados de configuração.

Packages

Adicione referências de pacote para os seguintes pacotes:

• Azure.Extensions.AspNetCore.Configuration.Secrets
• Azure.Identity

Aplicativo de exemplo

O aplicativo de exemplo é executado em qualquer um dos dois modos determinados pela #define diretiva de pré-processador na parte superior de Program.cs:

• Certificate: Demonstra o uso de uma ID do Cliente do Azure Key Vault e um certificado X.509 para acessar segredos armazenados no Azure Key Vault. Este exemplo pode ser executado a partir de qualquer local, seja implantado no Serviço de Aplicativo do Azure ou em qualquer host que possa servir um aplicativo ASP.NET Core.
• Managed: Demonstra como usar identidades gerenciadas para recursos do Azure. A identidade gerenciada autentica o aplicativo no Cofre da Chave do Azure com identidades gerenciadas para recursos do Azure sem credenciais armazenadas no código ou na configuração do aplicativo. Ao usar identidades gerenciadas para autenticar, não são necessárias identidades gerenciadas para ID e senha do aplicativo de recursos do Azure (Segredo do Cliente). A Managed versão do exemplo deve ser implantada no Azure. Siga as orientações na seção Usar as identidades gerenciadas para recursos do Azure .

Para obter mais informações sobre como configurar um aplicativo de exemplo usando diretivas de pré-processador (#define), consulte Visão geral do ASP.NET Core.

Visualizar ou descarregar amostra de código (como descarregar)

Armazenamento confidencial no Development ambiente

Defina segredos localmente usando o Gerenciador de Segredos. Quando a aplicação de exemplo é executada na máquina local no ambiente Development, os segredos são carregados a partir do armazém local de segredos do utilizador.

O Secret Manager requer uma <UserSecretsId> propriedade no arquivo de projeto do aplicativo. Defina o valor da propriedade ({GUID}) para qualquer GUID exclusivo:

<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>

Os segredos são criados como pares nome-valor. Os valores hierárquicos (seções de configuração) usam um : (dois pontos) como separador nos nomes de chave de configuração do ASP.NET Core.

O Secret Manager é usado a partir de um shell de comando aberto para a raiz de conteúdo do projeto, onde {SECRET NAME} é o nome e {SECRET VALUE} é o valor:

dotnet user-secrets set "{SECRET NAME}" "{SECRET VALUE}"

Execute os seguintes comandos num prompt de comando da raiz de conteúdo do projeto para definir os segredos para a aplicação de exemplo.

dotnet user-secrets set "SecretName" "secret_value_1_dev"
dotnet user-secrets set "Section:SecretName" "secret_value_2_dev"

Quando estes segredos são armazenados na secção de armazenamento de Segredos no Production ambiente com Azure Key Vault, o sufixo _dev é alterado para _prod. O sufixo fornece uma sugestão visual na saída do aplicativo indicando a origem dos valores de configuração.

Armazenamento de segredos no ambiente Production com Azure Key Vault

Conclua as etapas a seguir para criar um Cofre de Chaves do Azure e armazenar os segredos do aplicativo de exemplo nele. Para obter mais informações, consulte Guia de início rápido: definir e recuperar um segredo do Cofre da Chave do Azure usando a CLI do Azure.

1. Abra o Azure Cloud Shell usando qualquer um dos seguintes métodos no portal do Azure:

   • Selecione Experimentar no canto superior direito de um bloco de código. Use a cadeia de caracteres de pesquisa "CLI do Azure" na caixa de texto.
   • Abra o Cloud Shell no seu navegador com o botão Launch Cloud Shell .
   • Selecione o botão Cloud Shell no menu no canto superior direito do portal do Azure.

   Para obter mais informações, consulte CLI do Azure e Visão geral do Azure Cloud Shell.

2. Se ainda não estiver autenticado, inicie sessão com o az login comando.

3. Crie um grupo de recursos com o seguinte comando, onde {RESOURCE GROUP NAME} é o nome do novo grupo de recursos e {LOCATION} é a região do Azure:

   az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
   

4. Crie um Cofre da Chave no grupo de recursos com o seguinte comando, onde {KEY VAULT NAME} é o nome do novo cofre e {LOCATION} é a região do Azure:

   az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
   

5. Crie segredos no cofre como pares nome-valor.

   Os nomes secretos do Cofre da Chave do Azure são limitados a caracteres alfanuméricos e traços. Os valores hierárquicos (seções de configuração) usam -- (dois traços) como um delimitador, pois dois pontos não são permitidos em nomes secretos do Cofre de Chaves. Os dois pontos delimitam uma seção de uma subchave na configuração ASP.NET Core. A sequência de dois traços é substituída por dois pontos quando os segredos são carregados na configuração do aplicativo.

   Os segredos a seguir são para uso com o aplicativo de exemplo. Os valores incluem um _prod sufixo para os distinguir dos valores com _dev sufixo carregados no Development ambiente a partir do Gerenciador de Segredos. Substitua {KEY VAULT NAME} pelo nome do Cofre da Chave que você criou na etapa anterior:

   az keyvault secret set --vault-name {KEY VAULT NAME} --name "SecretName" --value "secret_value_1_prod"
   az keyvault secret set --vault-name {KEY VAULT NAME} --name "Section--SecretName" --value "secret_value_2_prod"
   

Usar a ID do Aplicativo e o certificado X.509 para aplicativos não hospedados no Azure

Configure o Azure Key Vault e a aplicação para usarem um ID de aplicação Microsoft Entra ID e certificado X.509 para autenticar num cofre quando a aplicação estiver alojada fora do Azure. Para obter mais informações, consulte Sobre chaves, segredos e certificados.

O aplicativo de exemplo usa uma ID de aplicativo e um certificado X.509 quando a #define diretiva de pré-processador na parte superior do Program.cs está definida como Certificate.

1. Crie um certificado PKCS#12 archive (.pfx). As opções para criar certificados incluem New-SelfSignedCertificate no Windows e OpenSSL.
2. Instale o certificado no armazenamento de certificados pessoais do usuário atual. Marcar a chave como exportável é opcional. Observe a impressão digital do certificado, que é usada posteriormente neste processo.
3. Exporte o certificado de arquivo PKCS#12 (.pfx) como um certificado codificado por DER (.cer).
4. Registe a aplicação com o Microsoft Entra ID (Registos de aplicações).
5. Carregue o certificado codificado por DER (.cer) para o Microsoft Entra ID:
   1. Selecione o aplicativo no Microsoft Entra ID.
   2. Navegue até Certificados & segredos.
   3. Selecione Carregar certificado para carregar o certificado, que contém a chave pública. Um certificado .cer, .pem ou .crt é aceitável.
6. Armazene o nome do Cofre de Chaves, a ID da Aplicação e a impressão digital do certificado no arquivo do appsettings.json aplicativo.
7. Aceda a Cofres de Chaves no portal do Azure.
8. Selecione o Cofre de Chaves que criou na secção Armazenamento Secreto no ambiente Production usando o Azure Key Vault.
9. Selecione Políticas de acesso.
10. Selecione Adicionar Política de Acesso.
11. Abra as permissões Secreto e forneça ao aplicativo as permissões Obter e Listar .
12. Selecione Selecionar principal e selecione a aplicação registada pelo nome. Selecione o botão Selecionar.
13. Selecione OK.
14. Selecione Guardar.
15. Implante o aplicativo.

A Certificate aplicação de exemplo obtém os valores de configuração de IConfigurationRoot com o mesmo nome do nome secreto:

• Valores não hierárquicos: O valor for SecretName é obtido com config["SecretName"].
• Valores hierárquicos (seções): Use a notação de dois pontos (:) ou o método GetSection. Use uma destas abordagens para obter o valor de configuração:
  • config["Section:SecretName"]
  • config.GetSection("Section")["SecretName"]

O certificado X.509 é gerenciado pelo sistema operacional. O aplicativo chama AddAzureKeyVault com valores fornecidos pelo appsettings.json arquivo:

// using System.Linq;
// using System.Security.Cryptography.X509Certificates;
// using Azure.Extensions.AspNetCore.Configuration.Secrets;
// using Azure.Identity;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();

                using var store = new X509Store(StoreLocation.CurrentUser);
                store.Open(OpenFlags.ReadOnly);
                var certs = store.Certificates.Find(
                    X509FindType.FindByThumbprint,
                    builtConfig["AzureADCertThumbprint"], false);

                config.AddAzureKeyVault(new Uri($"https://{builtConfig["KeyVaultName"]}.vault.azure.net/"),
                                        new ClientCertificateCredential(builtConfig["AzureADDirectoryId"], builtConfig["AzureADApplicationId"], certs.OfType<X509Certificate2>().Single()),
                                        new KeyVaultSecretManager());

                store.Close();
            }
        })
        .ConfigureWebHostDefaults(webBuilder => webBuilder.UseStartup<Startup>());

Exemplos de valores:

• Nome do Cofre de Chaves: contosovault
• ID do aplicativo: 00001111-aaaa-2222-bbbb-3333cccc4444
• Impressão digital do certificado: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:

{
  "KeyVaultName": "Key Vault Name",
  "AzureADApplicationId": "Azure AD Application ID",
  "AzureADCertThumbprint": "Azure AD Certificate Thumbprint",
  "AzureADDirectoryId": "Azure AD Directory ID"
}

Quando você executa o aplicativo, uma página da Web mostra os valores secretos carregados. No ambiente Development, os valores secretos são carregados com o sufixo _dev. No Production ambiente, os valores carregam com o _prod sufixo.

Usar identidades gerenciadas para recursos do Azure

Um aplicativo implantado no Azure pode aproveitar as identidades gerenciadas para recursos do Azure. Uma identidade gerenciada permite que o aplicativo se autentique com o Cofre da Chave do Azure usando a autenticação do Microsoft Entra ID sem credenciais (ID do Aplicativo e Senha/Segredo do Cliente) armazenadas no aplicativo.

O aplicativo de exemplo usa identidades gerenciadas para recursos do Azure quando a #define diretiva de pré-processador na parte superior do Program.cs está definida como Managed.

Insira o nome do cofre no ficheiro appsettings.json do aplicativo. O aplicativo de exemplo não requer uma ID de Aplicativo e Senha (Segredo do Cliente) quando definido para a Managed versão, portanto, você pode ignorar essas entradas de configuração. O aplicativo é implantado no Azure e o Azure autentica o aplicativo para acessar o Cofre da Chave do Azure somente usando o nome do cofre armazenado no appsettings.json arquivo.

Implante o aplicativo de exemplo no Serviço de Aplicativo do Azure.

Um aplicativo implantado no Serviço de Aplicativo do Azure é registrado automaticamente com a ID do Microsoft Entra quando o serviço é criado. Obtenha a ID do objeto da implantação para uso no comando a seguir. A ID do Objeto é mostrada no portal do Azure no Identity painel do Serviço de Aplicativo.

Usando a CLI do Azure e o ID do Objeto da Aplicação, atribua ao aplicativo as permissões list e get para aceder ao cofre:

az keyvault set-policy --name {KEY VAULT NAME} --object-id {OBJECT ID} --secret-permissions get list

Reinicie o aplicativo usando a CLI do Azure, o PowerShell ou o portal do Azure.

O aplicativo de exemplo:

• Cria uma instância da DefaultAzureCredential classe. A credencial tenta obter um token de acesso do ambiente para recursos do Azure.
• Um novo SecretClient é criado com a DefaultAzureCredential instância.
• Uma instância SecretClient é usada com uma instância KeyVaultSecretManager, que carrega valores secretos e substitui traços duplos (--) por dois pontos (:) nos nomes de chave.

// using Azure.Security.KeyVault.Secrets;
// using Azure.Identity;
// using Azure.Extensions.AspNetCore.Configuration.Secrets;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();
                var secretClient = new SecretClient(
                    new Uri($"https://{builtConfig["KeyVaultName"]}.vault.azure.net/"),
                    new DefaultAzureCredential());
                config.AddAzureKeyVault(secretClient, new KeyVaultSecretManager());
            }
        })
        .ConfigureWebHostDefaults(webBuilder => webBuilder.UseStartup<Startup>());

Valor de exemplo do nome do Cofre da Chave: contosovault

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Quando você executa o aplicativo, uma página da Web mostra os valores secretos carregados. No Development ambiente, os valores secretos têm o _dev sufixo porque são fornecidos pelo Secret Manager. No Production ambiente, os valores são carregados com o sufixo _prod porque são fornecidos pelo Azure Key Vault.

Caso recebas um Access denied erro, confirma se a app está registada com a Microsoft Entra ID e possui acesso ao repositório seguro. Confirme que reiniciou o serviço no Azure.

Para obter informações sobre como usar o provedor com uma identidade gerenciada e os Pipelines do Azure, consulte Criar uma conexão de serviço do Azure Resource Manager com uma VM com uma identidade de serviço gerenciado.

Opções de configuração

AddAzureKeyVault pode aceitar um AzureKeyVaultConfigurationOptions objeto:

config.AddAzureKeyVault(
    new SecretClient(
        new Uri("Your Key Vault Endpoint"),
        new DefaultAzureCredential(),
        new AzureKeyVaultConfigurationOptions())
    {
        ...
    });

O AzureKeyVaultConfigurationOptions objeto contém as seguintes propriedades.

Usar um prefixo para o nome da chave

AddAzureKeyVault fornece uma sobrecarga que aceita uma implementação de KeyVaultSecretManager, o que permite controlar como os segredos do Key Vault são convertidos em chaves de configuração. Por exemplo, você pode implementar a interface para carregar valores secretos com base em um valor de prefixo fornecido na inicialização do aplicativo. Essa técnica permite, por exemplo, carregar segredos com base na versão do aplicativo.

No exemplo seguinte, um segredo é estabelecido no Key Vault, usando o Secret Manager para o ambiente Development para 5000-AppSecret (períodos não são permitidos nos nomes de segredos do Key Vault). Esse segredo representa um segredo de aplicativo para a versão 5.0.0.0 do aplicativo. Para outra versão da aplicação, 5.1.0.0, um segredo é incluído no cofre (utilizando o Gerenciador de Segredos) para 5100-AppSecret. Cada versão do aplicativo carrega seu valor de segredo versionado em sua configuração como AppSecret, removendo a versão à medida que carrega o segredo.

AddAzureKeyVault é chamado com uma implementação personalizada KeyVaultSecretManager :

config.AddAzureKeyVault(
    $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
    builtConfig["AzureADApplicationId"],
    certs.OfType<X509Certificate2>().Single(),
    new PrefixKeyVaultSecretManager(versionPrefix));

A implementação reage aos prefixos de versão de segredos para carregar o segredo adequado na configuração:

• Load carrega um segredo quando seu nome começa com o prefixo. Outros segredos não são carregados.
• GetKey:
  • Remove o prefixo do nome secreto.
  • Substitui dois traços em qualquer nome pelo KeyDelimiter, que é o delimitador usado na configuração (geralmente dois pontos). O Azure Key Vault não permite dois pontos em nomes secretos.

public class PrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

    public PrefixKeyVaultSecretManager(string prefix)
    {
        _prefix = $"{prefix}-";
    }

    public override bool Load(SecretProperties secret)
    {
        return secret.Name.StartsWith(_prefix);
    }

    public override string GetKey(KeyVaultSecret secret)
    {
        return secret.Name
            .Substring(_prefix.Length)
            .Replace("--", ConfigurationPath.KeyDelimiter);
    }
}

O Load método é chamado por um algoritmo de provedor que itera através dos segredos do vault para encontrar os segredos prefixados da versão. Quando um prefixo de versão é encontrado com Load, o algoritmo usa o GetKey método para retornar o nome de configuração do nome secreto. Ele remove o prefixo da versão do nome do segredo. O restante do nome secreto é retornado para ser integrado nos pares nome-valor de configuração da aplicação.

Quando esta abordagem é implementada:

1. A versão do aplicativo especificada no arquivo de projeto do aplicativo. No exemplo a seguir, a versão do aplicativo é definida como 5.0.0.0:

   <PropertyGroup>
     <Version>5.0.0.0</Version>
   </PropertyGroup>
   

2. Confirme se uma <UserSecretsId> propriedade está presente no arquivo de projeto do aplicativo, onde {GUID} é um GUID fornecido pelo usuário:

   <PropertyGroup>
     <UserSecretsId>{GUID}</UserSecretsId>
   </PropertyGroup>
   

   Salve os seguintes segredos localmente com o Secret Manager:

   dotnet user-secrets set "5000-AppSecret" "5.0.0.0_secret_value_dev"
   dotnet user-secrets set "5100-AppSecret" "5.1.0.0_secret_value_dev"
   

3. Os segredos são salvos no Cofre da Chave do Azure usando os seguintes comandos da CLI do Azure:

   az keyvault secret set --vault-name {KEY VAULT NAME} --name "5000-AppSecret" --value "5.0.0.0_secret_value_prod"
   az keyvault secret set --vault-name {KEY VAULT NAME} --name "5100-AppSecret" --value "5.1.0.0_secret_value_prod"
   

4. Quando o aplicativo é executado, os segredos do Cofre da Chave são carregados. O segredo da cadeia de caracteres para 5000-AppSecret corresponde à versão do aplicativo especificada no arquivo de projeto do aplicativo (5.0.0.0).

5. A versão, 5000 (com o traço), é removida do nome da chave. Em todo o aplicativo, a leitura da configuração com a chave AppSecret carrega o valor secreto.

6. Se a versão da aplicação for alterada no ficheiro do projeto para 5.1.0.0 e a aplicação for executada novamente, o valor secreto devolvido está 5.1.0.0_secret_value_dev no Development ambiente e 5.1.0.0_secret_value_prod em Production.

Vincular uma matriz a uma classe

O provedor pode ler valores de configuração em uma matriz para ligação a uma matriz POCO.

Ao ler a partir de uma fonte de configuração que permite que as chaves contenham separadores de dois pontos (:), é utilizado um segmento de chave numérica para distinguir as chaves que compõem uma matriz (:0:, :1:, ... :{n}:). Para obter mais informações, consulte Configuração: vincular uma matriz a uma classe.

As chaves do Cofre de Chaves do Azure não podem utilizar dois pontos como separador. A abordagem descrita usa, neste artigo, traços duplos (--) como separador para valores hierárquicos (seções). As chaves da matriz são armazenadas no Azure Key Vault com dois traços e segmentos numéricos de chave (--0--, --1--, ... --{n}--).

Examine a seguinte configuração do provedor de log Serilog fornecida por um arquivo JSON. Existem dois literais de objetos definidos na matriz WriteTo que correspondem a dois destinos Serilog, os quais descrevem locais para onde a saída de log é enviada.

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

A configuração mostrada no arquivo JSON anterior é armazenada no Azure Key Vault usando notação de traço duplo (--) e segmentos numéricos:

Recarregar segredos

Os segredos são armazenados em cache até que o IConfigurationRoot.Reload seja chamado. Posteriormente, segredos desativados ou atualizados no cofre não são respeitados pela aplicação até executar Reload.

Configuration.Reload();

Segredos desativados e expirados

Os segredos expirados são incluídos por padrão no provedor de configuração. Para excluir valores para esses segredos na configuração do aplicativo, atualize o segredo expirado ou forneça a configuração usando um provedor de configuração personalizado:

class SampleKeyVaultSecretManager : KeyVaultSecretManager
{
  public override bool Load(SecretProperties properties) =>
    properties.ExpiresOn.HasValue &&
    properties.ExpiresOn.Value > DateTimeOffset.Now;
}

Passe esta personalização KeyVaultSecretManager para AddAzureKeyVault:

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

config.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SampleKeyVaultSecretManager());

Os segredos desativados não podem ser recuperados do Cofre da Chave e nunca são incluídos.

Troubleshoot

Quando o aplicativo não consegue carregar a configuração usando o provedor, uma mensagem de erro é gravada na infraestrutura de log principal do ASP.NET. As seguintes condições impedirão o carregamento da configuração:

• O aplicativo ou certificado não está configurado corretamente no Microsoft Entra ID.
• O cofre não existe no Azure Key Vault.
• A aplicação não está autorizada a acessar o cofre.
• A política de acesso não inclui Get e List permissões.
• No vault, os dados de configuração (par nome-valor) estão incorretamente nomeados, ausentes ou desativados.
• O aplicativo tem o nome errado do Cofre de Chaves (KeyVaultName), ID da Aplicação do Microsoft Entra (AzureADApplicationId), impressão digital do certificado do Microsoft Entra (AzureADCertThumbprint) ou ID do Diretório do Microsoft Entra (AzureADDirectoryId).
• Ao adicionar a política de acesso do Cofre de Chaves ao aplicativo, a política foi criada, mas o botão Salvar não foi selecionado na interface de Políticas de Acesso.

Recursos adicionais

• Visualizar ou descarregar amostra de código (como descarregar)
• Configuração no ASP.NET Core
• Microsoft Azure: Documentação do Key Vault
• Como gerar e transferir chaves protegidas por HSM para o Azure Key Vault
• Guia de início rápido: definir e recuperar um segredo do Cofre da Chave do Azure usando um aplicativo Web .NET
• Tutorial: Como usar o Azure Key Vault com a Máquina Virtual do Windows do Azure no .NET