curl -X POST "http://localhost:8001/vault-auth" \
--no-progress-meter --fail-with-body \
-H "Accept: application/json" \
--json '{
"name": "kong-auth",
"mount": "secret",
"protocol": "http",
"host": "'$VAULT_HOST'",
"port": 8200,
"vault_token": "root",
"kv": "v2"
}'Enable authentication with Vault in Kong Gateway
Incompatible with
konnect
Related Documentation
Related Resources
Minimum Version
Kong Gateway - 3.4
TL;DR
Create a HashiCorp Vault, then use the POST /vault-auth API to create a Vault object with your Vault configuration.
Enable the Vault Authentication and associate it with the Vault object. Create a Consumer and use the POST /vault-auth/$VAULT/credentials/$CONSUMER API to generate credentials for the Consumer.
Prerequisites
Kong Gateway running
This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.
-
Export your license to an environment variable:
export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE' -
Run the quickstart script:
curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATAOnce Kong Gateway is ready, you will see the following message:
Kong Gateway Ready
decK v1.66.1+
To complete this tutorial, install decK. We recommend keeping decK up to date with the latest version (1.66.1).
decK is a CLI tool for managing Kong Gateway declaratively with state files.
This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance.
You can check your current decK version with deck version.
Required entities
For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:
-
Run the following command:
echo ' _format_version: "3.0" services: - name: example-service url: http://httpbin.konghq.com/anything routes: - name: example-route paths: - "/anything" service: name: example-service protocols: - http - https ' | deck gateway apply -
To learn more about entities, you can read our entities documentation.
HashiCorp Vault
This how-to requires you to have a dev mode or self-managed HashiCorp Vault. The following instructions will guide you through configuring a HashiCorp Vault in dev mode with the resources you need to integrate it with Kong Gateway.
Important: This tutorial uses the literal
rootstring as your token, which should only be used in testing and development environments.
-
In a terminal, start your Vault dev server with
rootas your token.docker run -d \ --name vault \ --cap-add=IPC_LOCK \ -p 8200:8200 \ -e SKIP_SETCAP=1 \ -e SKIP_CHOWN=1 \ -e VAULT_DEV_ROOT_TOKEN_ID=root \ hashicorp/vault -
Export the
VAULT_ADDRandVAULT_TOKEN:export VAULT_ADDR="http://host.docker.internal:8200" export VAULT_TOKEN="root" export VAULT_HOST="host.docker.internal"
Create a Consumer
Consumers let you identify the client that’s interacting with Kong Gateway. The credentials will be generated in a later step, so we only need to specify a username.
echo '
_format_version: "3.0"
consumers:
- username: alex
' | deck gateway apply -Create a Vault object
A Vault object represents the connection between Kong Gateway and a Vault server. It defines the connection and authentication information used to communicate with the Vault API. This allows different instances of the vault-auth plugin to communicate with different Vault servers, providing a flexible deployment and consumption model.
Important: The Vault object used for Vault authentication is different from the Vault entity used for secrets management.
In this tutorial, we’re using host.docker.internal as our host instead of the localhost that HashiCorp Vault is using because Kong Gateway is running in a container that has a different localhost to you. We’ll also use the default 8200 port:
Add the value of id in the response to your environment, we’ll need it in the next step:
export DECK_VAULT_ID='YOUR_VAULT_ID_HERE'Enable the Vault Authentication plugin
Enable the Vault Authentication plugin, and use the ID of the Vault object to link it to the plugin:
echo '
_format_version: "3.0"
plugins:
- name: vault-auth
config:
vault:
id: "${{ env "DECK_VAULT_ID" }}"
' | deck gateway apply -Generate consumer credentials
Use the POST /vault-auth/{vault}/credentials/{consumer} endpoint to generate credentials for the Consumer we created:
curl -X POST "http://localhost:8001/vault-auth/kong-auth/credentials/alex" \
--no-progress-meter --fail-with-body \
-H "Accept: application/json"This request returns an access_token and secret_token. Add these to your environment:
export ACCESS_TOKEN='YOUR_CONSUMER_ACCESS_TOKEN'
export SECRET_TOKEN='YOUR_CONSUMER_SECRET_TOKEN'Validate
To validate that the authentication is working as expected, send a request to the Route we created in the prerequisites using the credentials we generated:
curl "http://localhost:8000/anything" \
--no-progress-meter --fail-with-body \
-H "access_token: $ACCESS_TOKEN"\
-H "secret_token: $SECRET_TOKEN"You should see the following response:
OKCleanup
Clean up HashiCorp Vault
Stop the HashiCorp Vault dev server container by running the following:
docker rm -f vaultClean up Konnect environment
If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.
Destroy the Kong Gateway container
curl -Ls https://get.konghq.com/quickstart | bash -s -- -d