Enable authentication with Vault in Kong Gateway

Uses: Kong Gateway decK

Deployment Platform:

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_DATA 

Once Kong Gateway is ready, you will see the following message:

 Kong Gateway Ready

decK

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial you will first need to install decK.

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
' | 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 root string as your token, which should only be used in testing and development environments.

Install HashiCorp Vault.
In a terminal, start your Vault dev server with root as your token.
```
vault server -dev -dev-root-token-id root
```
In the output from the previous command, copy the VAULT_ADDR to export.
In a new terminal window, export your VAULT_ADDR as an environment variable.
Verify that your Vault is running correctly:
```
vault status
```
Authenticate with Vault:
```
vault login root
```
Verify that you are using the v2 secrets engine:
```
vault read sys/mounts/secret
```
The options key should have the map[version:2] value.

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:

curl -X POST "http://localhost:8001/vault-auth" \
     -H "Accept: application/json" \
     --json '{
       "name": "kong-auth",
       "mount": "secret",
       "protocol": "http",
       "host": "host.docker.internal",
       "port": 8200,
       "vault_token": "root",
       "kv": "v2"
     }'

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" \
     -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 -i http://localhost:8000/anything \
     -H "access_token: $ACCESS_TOKEN"\
     -H "secret_token: $SECRET_TOKEN"

This request returns a 200 error with the message OK.

Cleanup

Clean up HashiCorp Vault

Stop the HashiCorp Vault dev server process by running the following:

pkill vault

Unset environment variables:

unset VAULT_ADDR

Clean 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