Compartilhar via

integração .NET AspireAzure Key Vault

  • Artigo

Neste artigo, você aprenderá a usar a integração .NET AspireAzure Key Vault. A biblioteca de integração Aspire.Azure.Key.Vault é usada para registrar um SecretClient no contêiner de DI para se conectar ao Azure Key Vault. Ele também permite verificações de integridade correspondentes, registro em log e telemetria.

Começar

Para começar a usar a integração .NET AspireAzure Key Vault, instale o pacote NuGet 📦Aspire.Azure. Security.KeyVault no projeto que consome o client, ou seja, o projeto do aplicativo que usa o Azure Key Vaultclient.

dotnet add package Aspire.Azure.Security.KeyVault

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em aplicativos .NET.

Exemplo de uso

As seções a seguir descrevem vários usos de exemplo.

Adicionar segredos à configuração

No arquivo Program.cs do projeto que consome client, chame a extensão AddAzureKeyVaultSecrets para adicionar os segredos no Azure Key Vault à Configuração do aplicativo. O método usa um parâmetro de nome de conexão.

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

Em seguida, você pode recuperar um segredo por meio de APIs de IConfiguration normais. Por exemplo, para recuperar um segredo de um serviço:

public class ExampleService(IConfiguration configuration)
{
    string secretValue = configuration["secretKey"];
    // Use secretValue ...
}

Usar SecretClient

Como alternativa, você pode usar o SecretClient para recuperar os segredos sob demanda. No arquivo Program.cs do seu projeto de consumo de client, chame a extensão AddAzureKeyVaultClient para registrar um SecretClient para uso por meio do contêiner de injeção de dependência.

builder.AddAzureKeyVaultClient("secrets");

Em seguida, você pode recuperar a instância de SecretClient usando a injeção de dependência. Por exemplo, para recuperar o client de um serviço:

public class ExampleService(SecretClient client)
{
    // Use client...
}

Uso do host do aplicativo

Para adicionar Azure Key Vault suporte de hospedagem ao seu IDistributedApplicationBuilder, instale o 📦Aspire.Hosting.Azure.KeyVault pacote NuGet no projeto de host do app .

dotnet add package Aspire.Hosting.Azure.KeyVault

No projeto de host do aplicativo, registre a integração Azure Key Vault e consuma o serviço usando os seguintes métodos:

var builder = DistributedApplication.CreateBuilder(args);

var secrets = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureKeyVault("secrets")
    : builder.AddConnectionString("secrets");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(secrets)

O código anterior adiciona condicionalmente o recurso Azure Key Vault ao projeto com base no contexto de execução. Se o host do aplicativo estiver em execução no modo de publicação, o recurso será adicionado caso contrário, a cadeia de conexão a um recurso existente será adicionada.

Configuração

A integração .NET AspireAzure Key Vault fornece várias opções para configurar o SecretClient com base nos requisitos e convenções do seu projeto.

Usar provedores de configuração

A integração .NET AspireAzure Key Vault dá suporte a Microsoft.Extensions.Configuration. Ele carrega o AzureSecurityKeyVaultSettings de appsettings.json ou de outros arquivos de configuração usando a chave Aspire:Azure:Security:KeyVault.

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "VaultUri": "YOUR_VAULT_URI",
          "DisableHealthChecks": false,
          "DisableTracing": true,
          "ClientOptions": {
            "DisableChallengeResourceVerification": true
          }
        }
      }
    }
  }
}

Se você tiver configurado suas configurações na seção Aspire:Azure:Security:KeyVault do arquivo appsettings.json, basta chamar o método AddAzureKeyVaultSecrets sem passar parâmetros.

Usar delegados embutidos

Você também pode passar o delegado Action<AzureSecurityKeyVaultSettings> para configurar algumas ou todas as opções diretamente, por exemplo, para definir o VaultUri:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static settings => settings.VaultUri = new Uri("YOUR_VAULTURI"));

Dica

O nome da API AddAzureKeyVaultSecrets causou um pouco de confusão. O método é usado para configurar o SecretClient e não para adicionar segredos à configuração.

Você também pode configurar o SecretClientOptions usando o delegado Action<IAzureClientBuilder<SecretClient, SecretClientOptions>>, o segundo parâmetro do método AddAzureKeyVaultSecrets. Por exemplo, para definir a ID do KeyClientOptions.DisableChallengeResourceVerification para identificar o client:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.DisableChallengeResourceVerification = true))

Opções de configuração

As seguintes opções configuráveis são expostas por meio da classe AzureSecurityKeyVaultSettings:

Nome Descrição
VaultUri Um URI para o cofre no qual o client opera. Aparece como "Nome DNS" no portal Azure.
Credential A credencial usada para autenticar no Azure Key Vault.
DisableHealthChecks Um valor booliano que indica se a verificação de integridade do Key Vault está desabilitada ou não.
DisableTracing Um valor booliano que indica se o rastreamento de OpenTelemetry está desabilitado ou não.

Verificações de saúde

Por padrão, as integrações .NET.NET Aspire habilitam verificações de saúde para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.

A integração .NET AspireAzure Key Vault inclui as seguintes verificações de integridade:

  • Adiciona a verificação de integridade AzureKeyVaultSecretsHealthCheck, que tenta se conectar e consultar o Key Vault
  • Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade registradas devem ser aprovadas para que o aplicativo esteja pronto para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente ajustes de log, rastreamento e métricas, que às vezes são conhecidos como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração .NET AspireAzure Key Vault usa as seguintes categorias de log:

  • Azure.Core
  • Azure.Identity

Rastreamento

A integração .NET AspireAzure Key Vault emitirá as seguintes atividades de rastreamento usando OpenTelemetry:

  • "Azure.Security.KeyVault.Secrets.SecretClient"

Métricas

A integração .NET AspireAzure Key Vault atualmente não dá suporte a métricas por padrão devido a limitações com o SDK de Azure.

Consulte também