Vault Authentication

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.

The plugin stores Consumer credentials in HashiCorp Vault and reads them from there to authenticate requests. To connect to a Vault server, it uses a Vault object:

• Vault object: A resource managed through the /vault-auth endpoint. It holds the connection and authentication details for a HashiCorp Vault server. Different plugin instances can reference different Vault objects, so they can authenticate against different Vault servers.

  Important: The Vault object is not the same as a Vault entity. The Vault object is introduced by the Vault Authentication plugin and used only by that plugin. The Vault entity is a standalone entity in Kong Gateway for managing secrets.

• Consumer: Represents the client. Each Consumer has an access_token and secret_token pair, generated with the POST /vault-auth/{vault}/credentials/{consumer} endpoint and stored in HashiCorp Vault.

The plugin links to a Vault object through config.vault.id.

When a client sends a request with its access_token and secret_token, the plugin uses the Vault object to look up the credentials in HashiCorp Vault. If they match, Kong Gateway identifies the Consumer and proxies the request.

For a full walkthrough, see Enable authentication with Vault in Kong Gateway.

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.

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