Home / How-to Guides
Edit
Report

Configure HashiCorp Vault as a vault backend with Azure managed identity authentication

Uses: Kong Gateway Admin API
Incompatible with
konnect
Related Documentation
Gateway Documentation
Tags
#secrets-management #security #hashicorp-vault #azure
Related Resources
Secrets management
Configure HashiCorp Vault as a vault backend
Configure HashiCorp Vault as a vault backend with GCP service account authentication
Configure HashiCorp Vault as a vault backend with GCP workload identity
Configure HashiCorp Vault as a vault backend with AWS IAM authentication
Configure HashiCorp Vault as a vault backend with AWS EC2 authentication
Store Keyring data in a HashiCorp Vault
HashiCorp Azure auth method reference
Minimum Version
Kong Gateway - 3.14
TL;DR

Run Kong Gateway on an Azure VM with a managed identity enabled. Enable the Azure auth method in HashiCorp Vault, configure it with your Azure AD app registration credentials, and create a role bound to your subscription and resource group.

Then in Kong Gateway:

  • Configure a Vault entity with config.auth_method set to azure.
  • Set config.azure_auth_role to the Vault role name. The Azure managed identity token is provided automatically by the Azure Instance Metadata Service — no credential files are required on the Kong Gateway side.

Prerequisites

Azure AD app registration for the Vault server

HashiCorp Vault must call Azure APIs to verify incoming managed identity tokens. You need an Azure AD app registration that Vault will use as the resource for generating MSI access tokens, with a client secret for authentication.

  1. Register an application in Microsoft Entra ID. This is the app registration Vault will use to call Azure APIs.

  2. Create a client secret for the app registration.

  3. Note the following values and export them as environment variables: 
    export VAULT_AZURE_TENANT_ID="YOUR-TENANT-ID"
export VAULT_AZURE_CLIENT_ID="YOUR-CLIENT-ID"
export VAULT_AZURE_CLIENT_SECRET="YOUR-CLIENT-SECRET"

    You can find the tenant ID and client ID in the Azure portal under your app registration’s Overview tab. The client secret value is only shown at creation time.

  4. Grant the app registration the following role assignment so Vault can verify VM identity during authentication. In the Azure portal, go to your subscription or resource group, select Access control (IAM), select the app you created as a member, and assign the Reader role to your app registration’s service principal:
    • Microsoft.Compute/virtualMachines/*/read

Azure VM with managed identity

To complete this tutorial, Kong Gateway must be running on an Azure VM with a system-assigned managed identity enabled. The managed identity token is automatically provided by the Azure Instance Metadata Service, so no credential files are required on the Kong Gateway side.

  1. Create an Azure VM with a system-assigned managed identity enabled. When creating the VM, go to Management > Identity and select the Enable system-assigned managed identity checkbox.

  2. Copy the following values for your VM and export them as environment variables: 
    export AZURE_SUBSCRIPTION_ID="YOUR-SUBSCRIPTION-ID"
export AZURE_RESOURCE_GROUP="YOUR-RESOURCE-GROUP"
export AZURE_VM_NAME="YOUR-VM-NAME"

    You can find these values in the Azure portal in your VM’s Overview tab.

  3. Copy the service principal ID of your VM’s managed identity and export it: 
    export AZURE_SERVICE_PRINCIPAL_ID="YOUR-SERVICE-PRINCIPAL-ID"

    You can find this in the Azure portal in your VM’s Security > Identity tab, under System assigned > Object (principal) ID.

If Kong Gateway isn’t running on an Azure VM, this auth method won’t work. The Azure Instance Metadata Service is only available from within Azure infrastructure.

HashiCorp Vault

You need HashiCorp Vault installed on your VM.

The steps in this how to assume that HashiCorp Vault and Kong Gateway are installed on the same VM. Production instances will often install HashiCorp Vault and Kong Gateway on separate VMS. If this is the case, see the HashiCorp Vault Azure authentication documentation for the configuration changes you’ll need to make.

Configure HashiCorp Vault

Before you can configure the Vault entity in Kong Gateway, you must configure HashiCorp Vault to authenticate clients using Azure managed identity tokens and store a secret.

Create configuration files

First, create the primary configuration file config.hcl for HashiCorp Vault in the ./vault directory:

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

storage "file" {
  path = "./vault/data"
}

ui = true

Then, create the HashiCorp Vault policy file rw-secrets.hcl in the ./vault directory:

path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

Configure the Vault and store a secret

  1. In a new terminal, start HashiCorp Vault: 
    vault server -config=./vault/config.hcl
  2. In your previous terminal, set the Vault address: 
    export VAULT_ADDR="http://localhost:8200"
  3. Initialize the Vault: 
    vault operator init -key-shares=1 -key-threshold=1

    This outputs your unseal key and initial root token. Export them as environment variables:

    export HCV_UNSEAL_KEY='YOUR-UNSEAL-KEY'
export DECK_HCV_TOKEN='YOUR-INITIAL-ROOT-TOKEN'
  4. Unseal your Vault: 
    vault operator unseal $HCV_UNSEAL_KEY
  5. Log in to your Vault: 
    vault login $DECK_HCV_TOKEN
  6. Write the policy to access secrets: 
    vault policy write rw-secrets ./vault/rw-secrets.hcl
  7. Enable Azure authentication: 
    vault auth enable azure
  8. Configure the Azure auth method with the Vault server’s Azure AD app registration credentials: 
    vault write auth/azure/config \
  tenant_id=$VAULT_AZURE_TENANT_ID \
  resource=https://management.azure.com/ \
  client_id=$VAULT_AZURE_CLIENT_ID \
  client_secret=$VAULT_AZURE_CLIENT_SECRET
  9. Create an Azure role that binds to Kong Gateway’s subscription, resource group, and service principal: 
    vault write auth/azure/role/kong-role \
  policies="rw-secrets" \
  bound_subscription_ids=$AZURE_SUBSCRIPTION_ID \
  bound_resource_groups=$AZURE_RESOURCE_GROUP \
  bound_service_principal_ids=$AZURE_SERVICE_PRINCIPAL_ID
  10. Enable the K/V secrets engine: 
    vault secrets enable -path=kong kv
  11. Create a secret: 
    vault kv put kong/headers/request header="x-kong:test"
  12. Confirm you can retrieve the secret through Vault: 
    vault kv get kong/headers/request

Set environment variables

Find the internal IP for your VM:

hostname -I

Export the following environment variables before creating the Vault entity:

export HCV_HOST="YOUR VM INTERNAL IP"
export AZURE_AUTH_ROLE=kong-role

Create a Vault entity for HashiCorp Vault

Create a Vault entity with the required parameters for HashiCorp Vault Azure managed identity authentication: 

curl -X POST "http://localhost:8001/vaults" \
     --no-progress-meter --fail-with-body  \
     --json '{
       "name": "hcv",
       "prefix": "hashicorp-vault",
       "description": "Storing secrets in HashiCorp Vault",
       "config": {
         "host": "'$HCV_HOST'",
         "kv": "v1",
         "mount": "kong",
         "port": 8200,
         "protocol": "http",
         "auth_method": "azure",
         "azure_auth_role": "'$AZURE_AUTH_ROLE'"
       }
     }'

Validate

To validate that the secret was stored correctly in HashiCorp Vault, call a secret from your vault using the kong vault get command:

sudo -E kong vault get {vault://hashicorp-vault/headers/request/header}

If the vault was configured correctly, this command returns the value of the secret. You can use {vault://hashicorp-vault/headers/request/header} to reference the secret in any referenceable field.

For more information about supported secret types, see What can be stored as a secret.

Cleanup

Clean up HashiCorp Vault

Stop the HashiCorp Vault process by running the following:

pkill vault

Unset environment variables:

unset VAULT_ADDR
unset VAULT_AZURE_TENANT_ID
unset VAULT_AZURE_CLIENT_ID
unset VAULT_AZURE_CLIENT_SECRET

Destroy the Kong Gateway container

 
curl -Ls https://get.konghq.com/quickstart | bash -s -- -d

FAQs

Can I use a user-assigned managed identity instead of a system-assigned managed identity?

Yes. Azure supports both system-assigned and user-assigned managed identities. For environments with high ephemeral workloads where VMs are frequently recreated, HashiCorp recommends user-assigned identities to avoid accumulating Vault entities. See Azure managed identities in the HashiCorp Vault documentation for more information.

How do I rotate my secrets in HashiCorp Vault and how does Kong Gateway pick up the new secret values?

You can rotate your secret in HashiCorp Vault by creating a new secret version with the updated value. You’ll also want to configure the ttl settings in your Kong Gateway Vault entity so that Kong Gateway pulls the rotated secret periodically.

Can I configure Vault in a different way without using the Vault entity directly?

Yes, you can also configure a Vault in one of the following ways:

  • Using environment variables, set at Kong Gateway startup
  • Using parameters in kong.conf, set at Kong Gateway startup

See the Vault reference for your provider for the available parameters and their format in each method.

Next Steps

Review the Vaults entity
What can be stored as a secret?
Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help?

Ask in our Slack Community
Contact Support