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

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 armazenar credenciais no código ou na configuração do aplicativo. 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 usar o ID da Aplicação de Microsoft Entra ID e um certificado X.509 para autenticar num cofre quando a aplicação estiver hospedada 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.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 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 Azure Key Vault usando a autenticação do Microsoft Entra ID sem armazenar credenciais no código ou na configuração do aplicativo.

O aplicativo de exemplo usa uma identidade gerenciada atribuída ao sistema quando a #define diretiva de pré-processador na parte superior do 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 Azure Functions. Depois que a identidade gerenciada tiver sido criada, observe a ID do Objeto do aplicativo mostrada no portal do Azure no Identity painel do Serviço de Aplicativo.

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.

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:

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());
}

Valor de exemplo do nome do Cofre da Chave: contosovault

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Para aplicativos que usam uma identidade gerenciada atribuída pelo usuário, configure a ID do Cliente da identidade gerenciada usando uma das seguintes abordagens:

1. Defina a variável de ambiente AZURE_CLIENT_ID.

2. Defina a DefaultAzureCredentialOptions.ManagedIdentityClientId propriedade ao chamar AddAzureKeyVault:

   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.

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:

// 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

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 :

// 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:

• 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 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);
}

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

Por padrão, os segredos são armazenados em cache pelo provedor de configuração durante o tempo de vida do aplicativo. Os segredos que foram subsequentemente desativados ou atualizados no cofre são ignorados pela aplicação.

Para recarregar segredos, chame 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 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;

builder.Configuration.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

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 de segredos no ambiente Development

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 armazenamento 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 no serviço de armazenamento Secret do Azure Key Vault no Production ambiente com a secção 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 secreto no Production ambiente 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 sufixos _dev dos valores que são carregados no ambiente Development através do Secret Manager. 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 usar o ID da Aplicação de Microsoft Entra ID e um certificado X.509 para autenticar num cofre quando a aplicação estiver hospedada 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 Production ambiente com 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 são carregados com o sufixo _prod.

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 carregam com o _prod sufixo 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 é definido no Key Vault (e usando o Secret Manager para o ambiente Development) para 5000-AppSecret (os 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