Partilhar via

.NET Aspire Azure Key Vault integração

  • Artigo

Inclui: integração de alojamento e Client integração

Azure Key Vault é um serviço de nuvem para armazenar e acessar segredos com segurança. A integração .NET AspireAzure Key Vault permite conectar-se a instâncias Azure Key Vault a partir das suas aplicações .NET.

Integração de hospedagem

A integração de hospedagem Azure Key Vault modela um recurso do Cofre da Chave como o tipo AzureKeyVaultResource. Para aceder a este tipo e às APIs para expressá-los na sua aplicação anfitriã do projeto , instale o pacote NuGet 📦Aspire.Hosting.Azure.KeyVault:

dotnet add package Aspire.Hosting.Azure.KeyVault

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

Adicionar Azure Key Vault recurso

Em seu projeto de host de aplicativo, chame AddAzureKeyVault na instância do construtor para adicionar um recurso 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 chamado "key-vault".

Importante

Por padrão, o AddAzureKeyVault configura a função embutida de Administrador do Cofre de Chaves do .

Dica

Quando você chama AddAzureKeyVault, ele chama implicitamente AddAzureProvisioning, que adiciona suporte para gerar recursos de 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.

Provisionamento automatizado com Bicep

Se és novo no Bicep, é uma linguagem de domínio específico para a definição de recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, em vez disso, as APIs de provisionamento geram Bicep para você. Ao publicares a tua aplicação, o Bicep gerado é exibido juntamente com o ficheiro de manifesto. Quando você adiciona um recurso Azure Key Vault, o seguinte Bicep é gerado:

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

param principalType string

param principalId string

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'
  }
}

resource key_vault_KeyVaultAdministrator 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '00482a5a-887f-4fb3-b363-3b7fe8e74483'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '00482a5a-887f-4fb3-b363-3b7fe8e74483')
    principalType: principalType
  }
  scope: key_vault
}

output vaultUri string = key_vault.properties.vaultUri

O Bicep anterior é um módulo que provisiona um recurso Azure Key Vault com os seguintes padrões:

  • location: A localização do grupo de recursos.
  • principalId: O ID principal do usuário ou entidade de serviço.
  • principalType: O tipo principal do usuário ou entidade de serviço.
  • key_vault: O recurso Azure Key Vault:
    • name: Um nome exclusivo para o Azure Key Vault.
    • properties: As Azure Key Vault propriedades:
      • tenantId: O ID do locatário do Azure Key Vault.
      • sku: Azure Key Vault SKU:
        • family: A família SKU.
        • name: O nome SKU.
      • enableRbacAuthorization: Um valor booleano que indica se o Azure Key Vault tem autorização RBAC (controle de acesso baseado em função) habilitada.
    • tags: As Azure Key Vault etiquetas.
  • key_vault_KeyVaultAdministrator: A atribuição da função de administrador Azure Key Vault:
    • name: Um nome exclusivo para a atribuição de função.
    • properties: As propriedades da atribuição de função:
      • principalId: O ID principal do usuário ou entidade de serviço.
      • roleDefinitionId: O ID de definição de função da função de administrador do Azure Key Vault.
      • principalType: O tipo principal do usuário ou entidade de serviço.
    • scope: O escopo da atribuição de função.
  • output: O Azure Key Vault URI.

O Bíceps gerado é um ponto de partida e pode ser personalizado para atender às suas necessidades específicas.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite a personalização do Bicep gerado ao fornecer uma API fluente para configurar os recursos Azure através da 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 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:

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

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

Você pode ter uma instância de Azure Key Vault existente à qual deseja se conectar. Em vez de representar um novo recurso Azure Key Vault, você pode adicionar uma cadeia de conexão ao host do aplicativo. Para adicionar uma conexão a um recurso Azure Key Vault existente, chame o método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(keyVault);

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

Observação

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Na nomenclatura .NET.NET Aspire, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host da aplicação, normalmente sob a seção Segredos do Utilizador, na secção ConnectionStrings. O host do aplicativo injeta essa cadeia de conexão como uma variável de ambiente em todos os recursos dependentes, por exemplo:

{
  "ConnectionStrings": {
    "key-vault": "https://{account_name}.vault.azure.net/"
  }
}

O recurso dependente pode acessar a cadeia de conexão injetada chamando o método GetConnectionString e passando o nome da conexão como parâmetro, neste caso "key-vault". A API GetConnectionString é uma abreviação de IConfiguration.GetSection("ConnectionStrings")[name].

Client integração

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

dotnet add package Aspire.Azure.Security.KeyVault

A integração do cliente fornece duas maneiras de aceder a informações confidenciais de Azure Key Vault:

  • Adicione segredos à configuração do aplicativo, usando o padrão IConfiguration ou IOptions<T>.
  • Utilize um SecretClient para recuperar segredos a pedido.

Adicionar segredos à configuração

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

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

Observação

O nome AddAzureKeyVaultSecrets API 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 Azure Key Vault recurso.

Em seguida, você pode recuperar um valor de configuração baseado em segredo por meio das APIs de IConfiguration normais ou até mesmo vinculando-se 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 registada no contêiner de injeção de dependência, considere os seguintes trechos:

Recuperar a instância IConfiguration

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

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

Recuperar instância 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 options. Para obter mais informações, consulte o padrão de Opções em .NET.

Parâmetros adicionais da API AddAzureKeyVaultSecrets 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 seu projeto cliente, chame a extensão AddAzureKeyVaultClient na instância IHostApplicationBuilder para registar um SecretClient através do contentor de injeção de dependência.

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

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 Azure Key Vault recurso.

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 do construtor e verifique se a classe ExampleService está registrada no 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 Azure Key Vault com chave

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

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

Em seguida, pode-se recuperar as instâncias SecretClient usando a 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 identificados por chave, consulte a seção .NET sobre injeção de dependência: Serviços identificados por 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 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": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Para obter o esquema completo de integração JSONAzure Key Vault cliente, consulte Aspire.Azure. Security.KeyVault/ConfigurationSchema.json.

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> delegate para configurar algumas ou todas as opções de forma imediata, 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 delegate Action<SecretClientOptions>, que é um parâmetro opcional do método AddAzureKeyVaultSecrets. Por exemplo, para definir o ID de 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 através da classe AzureSecurityKeyVaultSettings:

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

Client verificações de saúde de integração

Por padrão, .NET.NET Aspireintegrações de cliente têm verificações de saúde habilitadas para todos os serviços. Da mesma forma, muitas .NET.NET Aspireintegrações de hospedagem também habilitam endpoints de verificação de saúde. Para 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 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