Related Documentation
Made by
Kong Inc.
Incompatible with
konnect
Supported Gateway Topologies
hybrid db-less traditional
Compatible Protocols
grpc grpcs http https

Add authentication to a Gateway Service or Route with an access token and a secret token. Credential tokens are stored securely via Vault.

The credential lifecycle can be managed through the Admin API, or independently via Vault.

Token time-to-live (TTL)

When reading a token from Vault, Kong Gateway will search the KV value for the presence of a ttl field. When this field is present, Kong Gateway will respect the advisory value of the ttl field and store the value of the credential in the cache for only as long as the ttl field defines. This allows Kong Gateway to periodically refresh tokens created directly in Vault, outside of the Admin API.

External token pairs

Kong Gateway can read access/secret token pairs that were created directly in Vault, outside of the Kong Gateway Admin API. Vault KV secret values must contain the following fields:

{
  access_token: {your-string}
  secret_token: {your-string}
  created_at: {your-date-integer}
  updated_at: {your-date-integer}
  ttl: {your-integer} # optional
  consumer: {
    id: {consumer-uuid}
  }
}

Additional fields within the secret are ignored. The key must be the access_token value; this is the identifier by which Kong Gateway queries the Vault API to fetch the credential data.

See the Vault documentation for version 1 or version 2 for more information on the KV secrets engine.

vault-auth token pairs can be created with the Vault HTTP API or the vault write command:

vault write kong-auth/foo - <<EOF
{
  "access_token": "foo",
  "secret_token": "supersecretvalue",
  "consumer": {
    "id": "ce67c25e-2168-4a09-81e5-e06187a2384f"
  },
  "ttl": 86400
}
EOF
Something wrong?

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!