Azure Key Vault
Integrates Azure Key Vault as a secrets provider, allowing your build to resolve [SecretDefinition] parameters from a
vault. Use it when your secrets live in Azure Key Vault rather than in CI secret stores or user secrets.
Package: Invex.Atom.Module.AzureKeyVault
Installation
dotnet add package Invex.Atom.Module.AzureKeyVault
Usage
[BuildDefinition]
[GenerateEntryPoint]
internal partial class Build : BuildDefinition, IAzureKeyVault
{
// All IAzureKeyVault parameters are now available.
}
Configuration Parameters
| Parameter | CLI Arg | Type | Description |
|---|---|---|---|
AzureKeyVaultAddress |
--azure-key-vault-address |
Param | URI of the Azure Key Vault |
AzureKeyVaultTenantId |
--azure-key-vault-tenant-id |
Param | Microsoft Entra tenant ID |
AzureKeyVaultClientId |
--azure-key-vault-client-id |
Param | Client ID of the app registration or managed identity |
AzureKeyVaultClientSecret |
--azure-key-vault-client-secret |
Secret | Client secret of the app registration (optional) |
AzureKeyVaultServiceConnectionId |
--azure-key-vault-service-connection-id |
Param | Azure DevOps workload identity service connection ID |
AzureKeyVaultAuthPort |
--azure-key-vault-auth-port |
Param | Local interactive login redirect port (default: 3421) |
AzureKeyVaultTimeout |
--azure-key-vault-timeout |
Param | Per-secret timeout in seconds (default: 120, 0 disables) |
These parameters can be provided via environment variables, appsettings.json, the command line or another secrets
provider (such as .NET user secrets). They are never looked up in the vault itself.
Authentication
The vault is accessed with a Microsoft Entra token credential, chosen in this order:
Client secret — tenant ID, client ID and client secret are all set.
GitHub Actions OIDC — tenant ID and client ID are set and the job can request an ID token (
ACTIONS_ID_TOKEN_REQUEST_URLis present). Add a federated credential for the repository to the app registration and grant the jobid-token: write:new(nameof(MyTarget)) { Options = [new GitHubTokenPermissionsOption(new PermissionsEvent { IdTokens = PermissionsLevel.Write })], }Azure Pipelines workload identity federation — tenant ID, client ID and service connection ID are set and
SYSTEM_OIDCREQUESTURIandSYSTEM_ACCESSTOKENare available.SYSTEM_ACCESSTOKENis not exposed to scripts by default; map it into the target step:new(nameof(MyTarget)) { Options = [ BuildOptions.Inject.EnvironmentVariable("SYSTEM_ACCESSTOKEN", Tex.Variable("System.AccessToken")), ], }DefaultAzureCredential— environment variables, workload identity (for example AKS), managed identity, Azure CLI (including afterazure/loginor theAzureCLItask), Azure Developer CLI, and so on. The tenant ID and client ID are passed on when set. When the build is not running headless, an interactive browser login follows as a last resort.
Empty values and unexpanded Azure DevOps macros (such as $(AZURE_KEY_VAULT_CLIENT_SECRET) when the variable is not
defined) are treated as unset, so the injected-but-empty client secret does not prevent OIDC from being used.
If authentication fails or a request times out, the provider logs a warning and stops querying the vault for the rest of the run, so other secrets providers and defaults are used instead.
How It Works
When IAzureKeyVault is implemented, the module registers:
- An
ISecretsProviderthat queries the vault for secret values asynchronously. Secrets used by the targets being run are prefetched before execution with the build's cancellation token; each request is also bounded byAzureKeyVaultTimeout. - An
IBuildOptionProviderthat contributes workflow options for injecting the vault connection parameters in CI.
Value Injection Customisation
Control how each vault parameter is injected in workflows:
AzureKeyVaultValueInjections AzureKeyVaultValueInjections => new(
Address: AzureKeyVaultValueInjectionType.EnvironmentVariable,
TenantId: AzureKeyVaultValueInjectionType.EnvironmentVariable,
ClientId: AzureKeyVaultValueInjectionType.EnvironmentVariable,
ClientSecret: AzureKeyVaultValueInjectionType.Secret,
ServiceConnectionId: AzureKeyVaultValueInjectionType.None);
EnvironmentVariable reads from workflow variables (vars.AZURE_KEY_VAULT_ADDRESS in GitHub Actions,
$(AZURE_KEY_VAULT_ADDRESS) in Azure DevOps); Secret reads from the platform's secret store. The values above are
the defaults. Set ClientSecret to None when you only use federated credentials, and ServiceConnectionId to
EnvironmentVariable for Azure Pipelines workload identity federation.
Workflow Option
Enable vault integration at the build level:
public override IReadOnlyList<IBuildOption> Options =>
[
BuildOptions.AzureKeyVault.UseAzureKeyVault,
];
See also
- Secrets: how secrets are declared and resolved.
- Azure Storage: uses the same credential selection for artifact storage.
- IAzureKeyVault
- AzureKeyVaultValueInjections