integração .NET AspireAzure Key Vault

2025-06-23

Inclui: —&— Client

Azure Key Vault é um serviço de nuvem para armazenar e acessar segredos com segurança. A integração .NET AspireAzure Key Vault permite que você se conecte a instâncias Azure Key Vault a partir de seus aplicativos .NET.

Integração de hospedagem

A integração de hospedagem Azure Key Vault modela um recurso do Key Vault como o tipo AzureKeyVaultResource. Para acessar esse tipo e as APIs para expressá-los no projeto de host do aplicativo, instale o pacote NuGet 📦Aspire.Hosting.Azure.KeyVault.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.KeyVault

<PackageReference Include="Aspire.Hosting.Azure.KeyVault"
                  Version="*" />

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

Adicionar Azure Key Vault recurso

No projeto de host do aplicativo, chame AddAzureKeyVault na instância do builder para adicionar um recurso de Azure Key Vault.

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddAzureKeyVault("key-vault");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyVault);

// After adding all resources, run the app...

O método WithReference configura uma conexão no ExampleProject denominado "key-vault".

Importante

Por padrão, AddAzureKeyVault configura uma função interna Administrador de Key Vault.

Dica

Quando você chama AddAzureKeyVault, ele chama implicitamente AddAzureProvisioning, o que adiciona suporte para gerar recursos Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Provisionamento local: Configuração.

Bicep gerado por provisionamento

Se você ainda não conhece o Bicep, trata-se de uma linguagem de domínio específico para definir recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente; as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado é exibido juntamente ao arquivo de manifesto. Quando você adiciona um recurso Azure Key Vault, o Bicep a seguir é gerado:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: take('keyvault-${uniqueString(resourceGroup().id)}', 24)
  location: location
  properties: {
    tenantId: tenant().tenantId
    sku: {
      family: 'A'
      name: 'standard'
    }
    enableRbacAuthorization: true
  }
  tags: {
    'aspire-resource-name': 'key-vault'
  }
}

output vaultUri string = key_vault.properties.vaultUri

output name string = key_vault.name

O Bicep anterior é um módulo que provisiona um recurso Azure Key Vault. Além disso, as atribuições de função são criadas para o Azure recurso em um módulo separado:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param key_vault_outputs_name string

param principalType string

param principalId string

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: key_vault_outputs_name
}

resource key_vault_KeyVaultSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
    principalType: principalType
  }
  scope: key_vault
}

O Bicep gerado é um ponto de partida e é influenciado por alterações na infraestrutura de provisionamento em C#. As personalizações feitas diretamente no arquivo Bicep serão substituídas, portanto, faça alterações por meio das APIs de provisionamento C# para garantir que elas sejam refletidas nos arquivos gerados.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Este tipo permite personalizar o Bicep gerado, fornecendo uma API fluente para configurar os recursos de Azure usando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar o sku, RBAC, tagse muito mais. O exemplo a seguir demonstra como personalizar o recurso de Azure Key Vault:

builder.AddAzureKeyVault("key-vault")
    .ConfigureInfrastructure(infra =>
    {
        var keyVault = infra.GetProvisionableResources()
                            .OfType<KeyVaultService>()
                            .Single();

        keyVault.Properties.Sku = new()
        {
            Family = KeyVaultSkuFamily.A,
            Name = KeyVaultSkuName.Premium,
        };
        keyVault.Properties.EnableRbacAuthorization = true;
        keyVault.Tags.Add("ExampleKey", "Example value");
    });

O código anterior:

Encadeia uma chamada para a API ConfigureInfrastructure:
- O parâmetro infra é uma instância do tipo AzureResourceInfrastructure.
- Os recursos provisionáveis são recuperados chamando o método GetProvisionableResources().
- O único recurso KeyVaultService é recuperado.
- A propriedade Sku é atribuída a uma nova instância de KeyVaultSku.
- A propriedade KeyVaultProperties.EnableRbacAuthorization está definida como true.
- Uma tag é adicionada ao recurso com uma chave de ExampleKey e um valor de Example value.

Há muitas outras opções de configuração disponíveis para personalizar o recurso do Key Vault. Para obter mais informações, consulte Azure.Provisioning.KeyVault e Azure. Customização de provisionamento.

Conectar-se a uma instância de Azure Key Vault existente

Você pode ter uma instância existente Azure do AI Key Vault à qual deseja se conectar. Você pode encadear uma chamada para anotar que seu AzureKeyVaultResource é um recurso existente:

var builder = DistributedApplication.CreateBuilder(args);

var existingKeyVaultName = builder.AddParameter("existingKeyVaultName");
var existingKeyVaultResourceGroup = builder.AddParameter("existingKeyVaultResourceGroup");

var keyvault = builder.AddAzureKeyVault("ke-yvault")
                    .AsExisting(existingKeyVaultName, existingKeyVaultResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyvault);

// After adding all resources, run the app...

Para obter mais informações sobre como tratar Azure Key Vault recursos como recursos existentes, consulte Usar recursos existentesAzure.

Observação

Como alternativa, em vez de representar um Azure Key Vault recurso, você pode adicionar uma cadeia de conexão ao host do aplicativo. Essa abordagem é de tipo fraco e não funciona com atribuições de função ou personalizações de infraestrutura. Para obter mais informações, consulte Adicionar recursos existentes com cadeias de conexãoAzure.

integração Client

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

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Security.KeyVault

<PackageReference Include="Aspire.Azure.Security.KeyVault"
                  Version="*" />

A integração do cliente fornece duas maneiras de acessar segredos do Azure Key Vault:

Adicione segredos à configuração do aplicativo usando a IConfiguration ou o padrão IOptions<T>.
Use um SecretClient para recuperar segredos sob demanda.

Adicionar segredos à configuração

No arquivo Program.cs do projeto consumidor do cliente, chame o método de extensão AddAzureKeyVaultSecrets no IConfiguration para adicionar os segredos como parte da configuração do aplicativo. O método usa um parâmetro de nome de conexão.

builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault");

Observação

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

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Azure Key Vault no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar recurso Azure Key Vault.

Em seguida, você pode recuperar um valor de configuração baseado em segredo por meio das APIs IConfiguration normais ou até mesmo fazendo a vinculação a classes fortemente tipadas com o padrão de opções. Para recuperar um segredo de uma classe de serviço de exemplo que foi registrada com o contêiner de injeção de dependência, considere os trechos de código a seguir:

Recuperar a instância de `IConfiguration`

public class ExampleService(IConfiguration configuration)
{
    // Use configuration...
    private string _secretValue = configuration["SecretKey"];
}

O exemplo anterior pressupõe que você tenha também registrado a instância de IConfiguration para injeção de dependência. Para obter mais informações, consulte Injeção de dependência em .NET.

Recuperar a instância de `IOptions<T>`

public class ExampleService(IOptions<SecretOptions> options)
{
    // Use options...
    private string _secretValue = options.Value.SecretKey;
}

O exemplo anterior pressupõe que você configurou uma classe SecretOptions para uso com o padrão de opções. Para obter mais informações, consulte Padrão de opções em .NET.

Os parâmetros de API de AddAzureKeyVaultSecrets adicionais estão disponíveis opcionalmente para os seguintes cenários:

Action<AzureSecurityKeyVaultSettings>? configureSettings: para configurar algumas ou todas as opções em linha.
Action<SecretClientOptions>? configureClientOptions: para configurar o SecretClientOptions em linha.
AzureKeyVaultConfigurationOptions? options: para configurar o AzureKeyVaultConfigurationOptions em linha.

Adicionar um cliente Azure Secret

Como alternativa, você pode usar o SecretClient diretamente para recuperar os segredos sob demanda. Isso requer uma API de registro ligeiramente diferente.

No arquivo Program.cs do projeto que consome o cliente, chame a extensão AddAzureKeyVaultClient na instância de IHostApplicationBuilder para registrar um SecretClient para que possa ser usado por meio do contêiner de injeção de dependência.

builder.AddAzureKeyVaultClient(connectionName: "key-vault");

Dica

Depois de adicionar o SecretClient ao construtor, você pode obter a instância SecretClient usando a injeção de dependência. Por exemplo, para recuperar o cliente de um serviço de exemplo, defina-o como um parâmetro de construtor e verifique se a classe ExampleService está registrada com o contêiner de injeção de dependência:

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

Para obter mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar cliente com chave Azure Key Vault

Pode haver situações em que você deseja registrar várias instâncias de SecretClient com nomes de conexão diferentes. Para registrar clientes Azure Key Vault com chave, chame o método AddKeyedAzureKeyVaultClient:

builder.AddKeyedAzureKeyVaultClient(name: "feature-toggles");
builder.AddKeyedAzureKeyVaultClient(name: "admin-portal");

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

public class ExampleService(
    [FromKeyedServices("feature-toggles")] SecretClient featureTogglesClient,
    [FromKeyedServices("admin-portal")] SecretClient adminPortalClient)
{
    // Use clients...
}

Para obter mais informações sobre serviços com chave, consulte a seção .NET injeção de dependência: serviços com chave.

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": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Para obter o esquema de integração completa do cliente Azure Key VaultJSON, consulte Aspire.Azure.Security.KeyVault/ConfigurationSchema.json.

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 em linha

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

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureSettings: settings => settings.VaultUri = new Uri("KEY_VAULT_URI"));

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

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureClientOptions: 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
AzureSecurityKeyVaultSettings.Credential	A credencial usada para autenticar para o Azure Key Vault.
AzureSecurityKeyVaultSettings.DisableHealthChecks	Um valor booliano que indica se a verificação de integridade do Key Vault está desabilitada ou não.
AzureSecurityKeyVaultSettings.DisableTracing	Um valor booliano que indica se o rastreamento de OpenTelemetry está desabilitado ou não.
AzureSecurityKeyVaultSettings.VaultUri	Um URI para o cofre no qual o cliente opera. Aparece como "Nome DNS" no portal Azure.

Client verificações de integridade de integração

Por padrão, .NET.NET Aspireintegrações de cliente têm verificações de integridade habilitadas para todos os serviços. Da mesma forma, muitas integrações de hospedagem .NET.NET Aspire também habilitam endpoints para verificação de saúde. Para obter mais informações, consulte:

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 em log

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

Azure Key Vault documentos
vídeo : Introdução ao Azure Key Vault e ao .NET Aspire
visão geral das integrações .NET AspireAzure
visão geral das integrações .NET.NET Aspire
.NET AspireGitHub Repo

Compartilhar via

integração .NET AspireAzure Key Vault

Integração de hospedagem

Adicionar Azure Key Vault recurso

Bicep gerado por provisionamento

Personalizar a infraestrutura de provisionamento

Conectar-se a uma instância de Azure Key Vault existente

integração Client

Adicionar segredos à configuração

Recuperar a instância de IConfiguration

Recuperar a instância de IOptions<T>

Adicionar um cliente Azure Secret

Adicionar cliente com chave Azure Key Vault

Configuração

Usar provedores de configuração

Usar delegados em linha

Opções de configuração

Client verificações de integridade de integração

Observabilidade e telemetria

Registro em log

Rastreamento

Métricas

Consulte também

Comentários

Recursos adicionais

Recuperar a instância de `IConfiguration`

Recuperar a instância de `IOptions<T>`