Azure Key Vault

Uses: Kong Gateway Admin API deck KIC Konnect API Terraform

Azure Key Vault authentication

Kong Gateway uses a key to automatically authenticate with the Azure Key Vaults API and grant you access. If you’re using a client secret for authentication, set the following environment variable on your data plane to connect with an Azure Key Vault:

export AZURE_CLIENT_SECRET='YOUR_CLIENT_SECRET'

Copied!

If you’re using an Instance Managed Identity Token, you don’t need to set the client secret env variable.

Dedicated Cloud Gateway limitations:

Azure Key Vault is not supported as a Vault backend on Dedicated Cloud Gateways: Since the client secret has no Vault entity equivalent, it can only be set through this environment variable (or the credentials_prefix variant). Dedicated Cloud Gateways only accept KONG_ and OTEL_ prefixed environment variables, so AZURE_CLIENT_SECRET can’t be set.

Azure managed identity is not supported on Dedicated Cloud Gateways.

At minimum, you’ll also need to set the following values on your data plane.

export KONG_VAULT_AZURE_VAULT_URI='https://your-vault.vault.azure.com'
export KONG_VAULT_AZURE_TENANT_ID='YOUR_TENANT_ID'
export KONG_VAULT_AZURE_CLIENT_ID='YOUR_CLIENT_ID'

Copied!

Create an Azure Key Vault

The following example creates an azure Vault entity in the Azure region eastus2. The Vault name must be azure. The vault.prefix value can be your own custom prefix:

kong.yaml

Copied!

_format_version: "3.0"
vaults:
  - name: azure
    prefix: azure-vault
    description: Storing secrets in Azure Key Vaults
    config:
      type: secrets
      vault_uri: https://azure.example.com
      location: eastus2
      tenant_id: example-tenant
      client_id: example-client

curl -i -X POST http://localhost:8001/vaults/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "azure",
      "prefix": "azure-vault",
      "description": "Storing secrets in Azure Key Vaults",
      "config": {
        "type": "secrets",
        "vault_uri": "https://azure.example.com",
        "location": "eastus2",
        "tenant_id": "example-tenant",
        "client_id": "example-client"
      }
    }
    '

Copied!

To create a Vault entity, call the Konnect control plane config API’s /vaults endpoint.

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/vaults/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "azure",
      "prefix": "azure-vault",
      "description": "Storing secrets in Azure Key Vaults",
      "config": {
        "type": "secrets",
        "vault_uri": "https://azure.example.com",
        "location": "eastus2",
        "tenant_id": "example-tenant",
        "client_id": "example-client"
      }
    }
    '

Copied!

echo "
apiVersion: configuration.konghq.com/v1alpha1
kind: KongVault
metadata:
  name: azure-vault
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
spec:
  backend: azure
  prefix: azure-vault
  description: Storing secrets in Azure Key Vaults
  config:
    type: secrets
    vault_uri: https://azure.example.com
    location: eastus2
    tenant_id: example-tenant
    client_id: example-client
" | kubectl apply -f -

Copied!

resource "konnect_gateway_vault" "my_vault" {
  prefix = "azure-vault"
  description = "Storing secrets in Azure Key Vaults"
  config = {
    type = "secrets"
    vault_uri = "https://azure.example.com"
    location = "eastus2"
    tenant_id = "example-tenant"
    client_id = "example-client"
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied!

Vault configuration options

The following table lists all of the available configuration parameters for an Azure Key Vault:

Field name	Parameter format	Description
Vault URI	Vault entity: `vaults.config.vault_uri` kong.conf parameter: `vault_azure_vault_uri` Environment variable: `KONG_VAULT_AZURE_VAULT_URI`	The URI from which the vault is reachable. This value can be found in your Azure Key Vault Dashboard under the Vault URI entry.
Client ID	Vault entity: `vaults.config.client_id` kong.conf parameter: `vault_azure_client_id` Environment variable: `KONG_VAULT_AZURE_CLIENT_ID`	The client ID for your registered application. You can find this in the Azure Dashboard under App Registrations.
Tenant ID	Vault entity: `vaults.config.tenant_id` kong.conf parameter: `vault_azure_tenant_id` Environment variable: `KONG_VAULT_AZURE_TENANT_ID`	The `DirectoryId` and `TenantId` are the same: both refer to the GUID representing your Azure Entra tenant. Microsoft documentation and products may use either term depending on context.
Location	Vault entity: `vaults.config.location` kong.conf parameter: `vault_azure_location` Environment variable: `KONG_VAULT_AZURE_LOCATION`	Each Azure geography includes one or more regions that meet specific data residency and compliance requirements.
Type	Vault entity: `vaults.config.type` kong.conf parameter: `vault_azure_type` Environment variable: `KONG_VAULT_AZURE_TYPE`	Azure Key Vault supports different data types such as keys, secrets, and certificates. Kong currently supports only `secrets`.
TTL	Vault entity: `vaults.config.ttl` kong.conf parameter: `vault_azure_ttl` Environment variable: `KONG_VAULT_AZURE_TTL`	Time-to-live (in seconds) for a cached secret. A value of 0 (default) means no rotation. For non-zero values, it is recommended to use intervals of at least 60 seconds.
Negative TTL	Vault entity: `vaults.config.neg_ttl` kong.conf parameter: `vault_azure_neg_ttl` Environment variable: `KONG_VAULT_AZURE_NEG_TTL`	Time-to-live (in seconds) for caching failed secret lookups. A value of 0 (default) disables negative caching. After `neg_ttl` expires, Kong retries fetching the secret.
Resurrect TTL	Vault entity: `vaults.config.resurrect_ttl` kong.conf parameter: `vault_azure_resurrect_ttl` Environment variable: `KONG_VAULT_AZURE_RESURRECT_TTL`	Duration (in seconds) that secrets remain usable after expiration (`config.ttl` limit). Useful when the vault is unreachable or a secret is deleted. Kong retries refreshing the secret for this duration. Afterward, it stops. The default is 1e8 seconds (~3 years) to ensure resiliency during issues.
Base64 Decode v3.11+	Vault entity: `vaults.config.base64_decode` kong.conf parameter: `vault_azure_decode_base64` Environment variable: `KONG_VAULT_AZURE_DECODE_BASE64`	Decode all secrets in this vault as base64. Useful for binary data. If some of the secrets are not base64-encoded, an error will occur when using them. We recommend creating a separate vault for base64 secrets.
Credentials prefix	Vault entity: `vaults.config.credentials_prefix`	The prefix for environment variables used for authentication. The vault reads `{prefix}_CLIENT_SECRET` from the environment. Defaults to `AZURE`. This can only be set using the Vault entity.

Azure Key Vault

Azure Key Vault authentication

Create an Azure Key Vault

Vault configuration options

Help us make these docs great!

Still need help?