Home / How-to Guides
Edit
Report

Configure HashiCorp Vault as a vault backend with GCP service account authentication

Uses: Kong Gateway Admin API
Incompatible with
konnect
Related Documentation
Gateway Documentation
Tags
#secrets-management #security #hashicorp-vault
Related Resources
Secrets management
Configure HashiCorp Vault as a vault backend
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 Google Cloud auth method reference
Minimum Version
Kong Gateway - 3.14
TL;DR

Run Kong Gateway in a Google Cloud VM instance. Enable the GCP auth method in HashiCorp Vault and configure it with your Vault server’s GCP service account credentials, the IAM role bound to Kong Gateway’s service account, and store a secret.

Then in Kong Gateway, configure a Vault entity with the following:

  • Set config.auth_method set to gcp_iam.
  • Set config.gcp_auth_role to the Vault role name.
  • Set config.gcp_service_account to the GCP service account email that Kong Gateway will authenticate as.
  • Set config.gcp_jwt_exp to the JWT expiration time in seconds (maximum 900).

Retrieve the secret with {vault://hashicorp-vault/headers/request/header}.

Prerequisites

GCP service account for Kong Gateway

To complete this tutorial, you need a GCP project with the iam.googleapis.com API enabled and a GCP service account that Kong Gateway will use to authenticate to HashiCorp Vault.

  1. In the Google Cloud console, create a service account key and grant IAM permissions:
    1. In the Service Account settings, click your project.
    2. Click Create service account.
    3. Enter a name for your service account.
    4. Copy and export the service account email: 
      export GCP_SERVICE_ACCOUNT_EMAIL="kong@YOUR-PROJECT.iam.gserviceaccount.com"
    5. Click Create and continue.
    6. From the Select a role dropdown menu, select “Service Account Token Creator” and “Service Account Key Admin”. For more information about this role, see Roles for service account authentication.
    7. Click Continue.
    8. In the Service account users role field, enter your service account email.

    9. In the Service account admins role field, enter your service account email.

      Scope the role to the service account only: You must scope the Service Account Token Creator to the service account itself instead of project-wide. HashiCorp explicitly warns that a project-wide grant allows the service account to impersonate any other service account in the project.

    10. Click Done.

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 GCP 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 GCP service account JWTs 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 GCP authentication: 
    vault auth enable gcp
  8. Create an IAM role that binds to Kong Gateway’s GCP service account: 
    vault write auth/gcp/role/kong-role \
  type="iam" \
  bound_service_accounts="$GCP_SERVICE_ACCOUNT_EMAIL" \
  token_policies="rw-secrets"
  9. Enable the K/V secrets engine: 
    vault secrets enable -path=kong kv
  10. Create a secret: 
    vault kv put kong/headers/request header="x-kong:test"
  11. 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 GCP_AUTH_ROLE=kong-role

Create a Vault entity for HashiCorp Vault

Using decK, create a Vault entity in the kong.yaml file with the required parameters for HashiCorp Vault GCP IAM authentication: 

curl -X POST "http://localhost:8001/vaults" \
     --no-progress-meter --fail-with-body  \
     -H "Content-Type: application/json" \
     --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": "gcp_iam",
         "gcp_auth_role": "'$GCP_AUTH_ROLE'",
         "gcp_service_account": "'$GCP_SERVICE_ACCOUNT_EMAIL'",
         "gcp_jwt_exp": 900
       }
     }'

Validate

To validate that the secret was stored correctly in HashiCorp Vault, call a secret from your vault using the kong vault get command within the Data Plane container.

docker exec kong-quickstart-gateway 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_GCP_CREDENTIALS_FILE
unset DECK_GCP_SERVICE_ACCOUNT

Destroy the Kong Gateway container

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

FAQs

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