Use Azure Key Vault secrets with Liquibase

The Azure identity that runs Liquibase needs read access to the vault items you reference. Grant access with RBAC roles (recommended) or a legacy access policy. Both are supported.

RBAC roles: In the Azure portal, open your Key Vault and go to Access control (IAM) > Add > Add role assignment. Assign the role for each item type you use, scoped to the vault, to the identity that runs Liquibase. For detailed steps, see Provide access to Key Vault keys, certificates, and secrets with Azure RBAC in the Microsoft documentation.

Legacy access policies: If your vault uses the classic access policy model instead of RBAC, grant the Get permission for each item type you use. See Assign a Key Vault access policy in the Microsoft documentation.

Liquibase authenticates with the Azure SDK's DefaultAzureCredential. Credentials come from your Azure environment, never from Liquibase configuration files. Use whichever method fits where Liquibase runs:

Environment variables (CI/CD pipelines, containers):

Azure CLI (local development): If you have the Azure CLI installed, sign in with az login. Liquibase reuses your Azure CLI session automatically, so you do not need a service principal or environment variables. Your Azure account needs the vault access described in Step 1.

Managed Identity (Azure-hosted workloads such as VMs, App Service, and AKS): Enable a managed identity on the Azure resource and grant it vault access as in Step 1. Authentication happens automatically.

Replace a sensitive value with a comma-separated reference. Each reference has a prefix that selects the item type, followed by the vault URL, the item name, and an optional version. You can reference all three Azure Key Vault item types. Most users only need secrets.

Note: The azure-key-vault-key prefix returns public keys only (RSA and EC, including HSM variants). Liquibase rejects private, symmetric (oct), and other non-public key material with an error.

Be sure to:

• Replace your_vault_name with your Key Vault name. For example, my-company-vault

• Replace your_secret_name with the name of the secret in the vault. For example, db-password

Pin a specific version: Add the version identifier as an optional fourth segment. When you omit it, Liquibase retrieves the latest version.

Be sure to:

• Replace your_version_id with the version identifier of the vault item

Set a default vault URL: If most references point at one vault, set liquibase.azure.keyVault.url (environment variable: LIQUIBASE_AZURE_KEY_VAULT_URL) and leave the vault URL segment empty. An inline vault URL always takes precedence over the default.

Keys and certificates use the same format with their own prefixes.

Be sure to:

• Replace your.property with the property that receives the key's PEM value

• Replace your.other.property with the property that receives the certificate's PEM value

• Replace your_key_name with the name of the key in the vault

• Replace your_certificate_name with the name of the certificate in the vault

Run any Liquibase command that uses the configured value.

Be sure to:

• Replace your_changelog_file with the path to your changelog file. For example, changelog.sql

At the fine log level, Liquibase records the resolution without exposing the value. The log line names the configuration key the way you supplied it, such as LIQUIBASE_COMMAND_PASSWORD for an environment variable or --password for a CLI parameter:

The first vault call in a run also logs Acquiring Azure Key Vault credential… at the info level. Secret values are masked in logs and never appear in error messages.