You are browsing documentation for an older version. See the latest documentation here.

Azure Key Vaults

The current version of Kong Gateway’s implementation supports configuring Azure Key Vaults in two ways:

  • Environment variables
  • Managed identity authentication

Kong Gateway only supports the Secrets Azure vault type. It doesn’t support the Keys and Certificates vault types.

Configure Azure Key Vaults

Kong Gateway uses a key to automatically authenticate with the Azure Key Vaults API and grant you access.

You need to specify the following values:

  • Azure ActiveDirectory Tenant ID
  • Azure Client ID
  • vault_URI
  • Azure Client Secret: This value can only be configured as an environment variable.

You can configure these values with environment variables before starting Kong Gateway:

  1. export KONG_VAULT_AZURE_VAULT_URI=https://my-vault.vault.azure.com
  2. export KONG_VAULT_AZURE_TENANT_ID=tenant_id
  3. export KONG_VAULT_AZURE_CLIENT_ID=client_id
  4. export AZURE_CLIENT_SECRET=client_secret

With Instance Managed Identity Token, setting the environment variables isn’t necessary.

Examples

To use a Secret with the name secret-name, create a JSON object in Azure Key Vault that contains one or more properties:

  1. {
  2. "foo": "bar",
  3. "snip": "snap"
  4. }

The Azure AD tenant ID, client ID, vault_uri, and client secret must be specified. You can configure these values with environment variables before starting Kong Gateway:

  1. export KONG_VAULT_AZURE_VAULT_URI=https://my-vault.vault.azure.com
  2. export KONG_VAULT_AZURE_TENANT_ID=tenant_id
  3. export KONG_VAULT_AZURE_CLIENT_ID=client_id
  4. export AZURE_CLIENT_SECRET=client_secret
  1. {vault://azure/secret-name/foo}
  2. {vault://azure/secret-name/snip}

Alternatively, you can configure the vault via the vaults entity.

Configuration via vaults entity

Once the database is initialized, a vault entity can be created to encapsulate the provider and the required Azure Key Vault information:

Admin API

Declarative configuration

  1. curl -i -X PUT http://localhost:8001/vaults/azure-key-vault \
  2. --data name=azure \
  3. --data description="Storing secrets in Azure Key Vault (Secrets)" \
  4. --data config.type="secrets" \
  5. --data config.location="us-east" \
  6. --data config.vault_uri="http://my-vault-uri.azure.com"

Result:

  1. {
  2. "config": {
  3. "client_id": null,
  4. "credentials_prefix": "AZURE",
  5. "vault_uri": "http://my-vault-uri.azure.com",
  6. "location": "us-east",
  7. "neg_ttl": null,
  8. "resurrect_ttl": null,
  9. "tenant_id": null,
  10. "ttl": null,
  11. "type": "secrets",
  12. "vault_uri": null
  13. },
  14. "created_at": 1696235611,
  15. "description": "Storing secrets in Azure Key Vault (Secrets)",
  16. "id": "7c9287c1-2cbc-406b-a013-843fe54dc0b6",
  17. "name": "azure",
  18. "prefix": "azure-key-vault",
  19. "tags": null,
  20. "updated_at": 1696235611
  21. }

Secrets management is only supported in decK 1.16 and later.

Add the following snippet to your declarative configuration file:

  1. _format_version: "3.0"
  2. vaults:
  3. - config:
  4. type: secrets
  5. vault_uri: http://my-vault-uri.azure.com
  6. location: us-east
  7. description: Storing secrets in Azure Key Vaults
  8. name: azure
  9. prefix: azure-key-vault

With the Vault entity in place, you can reference the Azure secrets through it:

  1. {vault://azure-key-vault/secret-name/foo}
  2. {vault://azure-key-vault/secret-name/snip}

Vault entity configuration options

Use the following configuration options to configure the vaults entity through any of the supported tools:

  • Kong Manager
  • Konnect
  • Admin API
  • Declarative configuration

Configuration options for a Azure Key Vault in Kong Gateway:

ParameterField nameDescription
vaults.config.vault_uriVault URIThe URI the vault is reachable from. You can find this value in your Azure Key Vault Dashboard under Vault URI entry.
vaults.config.client_idClient IDThe client ID for your registered application. Visit the Azure Dashboard and select App Registrations to find your client ID.
vaults.config.tenant_idTenant IDThe DirectoryId and TenantId both equate to the GUID representing the ActiveDirectory Tenant. In other words, the “Tenant ID” IS the “Directory ID”. Depending on context, both term may be used Microsoft documentation and products.
vaults.config.locationLocationEach Azure geography contains one or more regions and meets specific data residency and compliance requirements.
vaults.config.typeTypeAzure Key Vault enables Microsoft Azure applications and users to store and use several types of secret or key data: keys, secrets, and certificates. Kong currently only supports secrets.
vaults.config.ttlTTLTime-to-live (in seconds) of a secret from the vault when it’s cached. The special value of 0 means “no rotation” and is the default. When using non-zero values, it is recommended that they are in increments of at least 1 minute.
vaults.config.neg_ttlNegative TTLTime-to-live (in seconds) of a vault miss (no secret). Negatively cached secrets will remain valid until the neg_ttl is reached, after which Kong will attempt to refresh the secret again. The default value for neg_ttl is 0, meaning no negative caching occurs.
vaults.config.resurrect_ttlResurrect TTLTime (in seconds) for how long secrets will remain in use after they are expired (config.ttl is over). This is useful when a vault becomes unreachable, or when a secret is deleted from the Vault and isn’t replaced immediately. On this both cases, the gateway will keep trying to refresh the secret for resurrect_ttl seconds. After that, it will stop refreshing. You should set a high value for this configuration option to ensure a seamless transition in case there are unexpected issues with the Vault. The default value for resurrect_ttl is 1^e8 seconds, which is about 3 years.

Common options:

ParameterField nameDescription
vaults.description
optional
DescriptionAn optional description for your vault.
vaults.nameNameThe type of vault. Accepts one of: env, gcp, azure, aws, or hcv. Set azure for Azure Key Vaults
vaults.prefixPrefixThe reference prefix. You need this prefix to access secrets stored in this vault. For example, {vault://gcp-sm-vault/<some-secret>}.