Partilhar via

.NET Aspire Azure Key Vault integração

  • 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 DI para conexão com Azure Key Vault. Ele também permite verificações de saúde, registro e telemetria correspondentes.

Começar

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

dotnet add package Aspire.Azure.Security.KeyVault

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

Exemplo de utilização

As seções a seguir descrevem vários exemplos de uso.

Adicionar segredos à configuração

No arquivo Program.cs do seu projeto de consumo de client, chame a extensão AddAzureKeyVaultSecrets para adicionar os segredos no Azure Key Vault à Configuração da aplicação. 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 IConfiguration normais. Por exemplo, para recuperar um segredo de um serviço:

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

Utilize SecretClient

Como alternativa, pode-se usar um SecretClient para recuperar os segredos a pedido. 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 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...
}

Utilização do anfitrião da aplicação

Para adicionar Azure Key Vault suporte de hosting ao seu IDistributedApplicationBuilder, instale o pacote NuGet 📦Aspire.Hosting.Azure.KeyVault no projeto host da aplicação .

dotnet add package Aspire.Hosting.Azure.KeyVault

Em seu projeto de host de aplicativo, registre a integração de 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 sendo executado 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 suporta Microsoft.Extensions.Configuration. Carrega o AzureSecurityKeyVaultSettings de appsettings.json ou outros ficheiros 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ê configurou suas configurações na seção Aspire:Azure:Security:KeyVault do seu arquivo appsettings.json, você pode simplesmente chamar o método AddAzureKeyVaultSecrets sem passar nenhum parâmetro.

Usar delegados embutidos

Você também pode passar o Action<AzureSecurityKeyVaultSettings> delegado 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 AddAzureKeyVaultSecrets API 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 o ID de 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 através 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 se autenticar com o Azure Key Vault.
DisableHealthChecks Um valor booleano que indica se a verificação de integridade do Cofre da Chave está desabilitada ou não.
DisableTracing Um valor booleano que indica se o rastreamento de OpenTelemetry está desabilitado ou não.

Controlos sanitários

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

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

  • Adiciona a verificação de integridade AzureKeyVaultSecretsHealthCheck, que procura conectar-se e consultar o Key Vault.
  • Integra-se com o endpoint HTTP /health, que especifica que todas as verificações de integridade registadas devem passar para que a aplicação seja considerada pronta para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na seção de configuração.

Registo

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

  • Azure.Core
  • Azure.Identity

Rastreio

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

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

Métricas

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

Ver também