Today we’re excited to show how Kong Enterprise customers can utilize our new plugin for HashiCorp Vault for authentication and secrets management. Like the Terraform integration released last year, this new integration with Vault represents another step towards allowing Kong Enterprise customers to leverage HashiCorp’s suite of cloud infrastructure automation tools.

The Vault plugin will allow KE customers to add authentication to a Service or Route with an access token and secret token, with credential tokens being stored securely via Vault. Credential lifecycles can be managed through the Kong Admin API, or independently via Vault. Read below for a simple 5-step guide on how to get started using Vault with Kong Enterprise.

Getting Started with Kong and Vault

1. Create a Vault Object

To start, we’ll need to create a Vault to store our tokens. A Vault object represents the connection between Kong 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.

Vault objects can be created via the following HTTP request:

$ curl -X POST http://kong:8001/vaults \
--data name=kong-auth \
--data mount=kong-auth \
--data protocol=http \
--data host=127.0.0.1 \
--data port=8200
--data token=s.m3w9gdV0uMDYFpMgEWSB2mtM
HTTP/1.1 201 Created{
“created_at”: 1550538643,
“host”: “127.0.0.1”,
“id”: “d3da058d-0acb-49c2-b7fe-72b3e9fd4b0a”,
“mount”: “kong-auth”,
“name”: “kong-auth”,
“port”: 8200,
“protocol”: “http”,
“token”: “s.m3w9gdV0uMDYFpMgEWSB2mtM”,
“updated_at”: 1550538643
}

This assumes a Vault server is accessible via 127.0.0.1:8200, and that a version 1 KV secrets engine has been enabled at kong-auth. The provided Vault token should have at least ‘read' and ‘list' permissions on the given Vault mount path, as well as ‘write' and ‘delete' permissions if you wish to manage credentials via the Kong Admin API. Vault KV secrets engine documentation is available via the Vault documentation.

2. Create a Consumer

To actually use our Vault plugin, we’ll next need to create a Consumer to associate with one or more credentials. The Consumer represents a developer using the upstream service. The Vault object we created in the previous step will represent the connection Kong will use to communicate with the Vault server where access and secret tokens will be stored.

We’ll need to associate a credential to an existing Consumer object. To create a Consumer, you can execute the following request:

First, we’ll need to associate a credential to an existing Consumer object. To create a Consumer, you can execute the following request:

$ curl -X POST http://kong:8001/consumers/ \
--data "username=<USERNAME>" \
--data "custom_id=<CUSTOM_ID>"
HTTP/1.1 201 Created{
“username”:“<USERNAME>”,
“custom_id”: “<CUSTOM_ID>”,
“created_at”: 1472604384000,
“id”: “7f853474-7b70-439d-ad59-2481a0a9a904”
}

• username(semi-optional)
  • The username of the Consumer. Either this field or custom_id must be specified.
• custom_id(semi-optional)
  • A custom identifier used to map the Consumer to another database. Either this field or username must be specified.

If you are also using the ACL plugin and whitelists with this service, you must add the new consumer to a whitelisted group. See ACL: Associating Consumers for details. A Consumer can have many credentials.

3. Create an Access/Secret Token Pair

Next, we’ll need to create a pair of tokens that function as our vault-auth credentials. These tokens are defined as: an access token that identifies the owner of the credential, and a secret token that is used to authenticate ownership of the access token.

Token pairs can be managed either via the Kong Admin API or independently via direct access with Vault. Token pairs must be associated with an existing Kong Consumer. Creating a token pair with the Kong Admin API can be done via the following request:

$ curl -X POST http://kong:8001/vaults/{vault}/credentials/{consumer}
HTTP/1.1 201 Created{
“data”: {
“access_token”: “v3cOV1jWglS0PFOrTcdr85bs1GP0e2yM”,
“consumer”: {
“id”: “64063284-e3b5-48e7-9bca-802251c32138”
},
“created_at”: 1550538920,
“secret_token”: “11XYyybbu3Ty0Qt4ImIshPGQ0WsvjLzl”,
“ttl”: null
}
}

When the access_token or secret_token values are not provided, token values will be automatically generated via a cryptographically-secure random number generator (CSPRNG).

4. Integrating Vault objects with Vault-Auth plugins

To create a seamless lifecycle relationship between Vault instances and plugins with which they're associated, Vault objects are treated as foreign references in plugin configs. To integrate them, you’ll need to define an association with a Vault object, which can be accomplished using the following HTTP request during plugin creation:

$ curl -X POST http://kong:8001/plugins \
--data name=vault-auth \
--data config.vault.id=<uuid>
HTTP/1.1 201 Created{
“created_at”: 1550539002,
“config”: {
“tokens_in_body”: false,
“secret_token_name”: “secret_token”,
“run_on_preflight”: true,
“vault”: {
“id”: “d3da058d-0acb-49c2-b7fe-72b3e9fd4b0a”
},
“anonymous”: null,
“hide_credentials”: false,
“access_token_name”: “access_token”
},
“id”: “b4d0cbb7-bff2-4599-ba19-67c705c15b9a”,
“service”: null,
“enabled”: true,
“run_on”: “first”,
“consumer”: null,
“route”: null,
“name”: “vault-auth”
}

Where <uuid> is the id of an existing Vault object.

5. Using Vault credentials

Now that we’re all set up, to get started using your Vault credentials simply make a request with the access_token and secret_token as querystring parameters:

$ curl http://kong:8000/{proxy path}?access_token=<access token>&secret_token=<secret token>

Or in a header:

$ curl http://kong:8000/{proxy path} \
-H 'access_token: <access_token>' \
-H 'secret_token: <secret_token>'

Getting the Most Out of Using Kong with Vault

Now that you’re up and running with Kong and Vault, you’ll want to manage them effectively. Below, we’ve detailed some key considerations for optimizing your experience with Kong and Vault.

Deleting an Access/Secret Token Pair

When you need to restrict or remove access, you can delete existing Vault credentials from the Vault server via the following API:

$ curl -X DELETE http://kong:8001/vaults/{vault}/credentials/token/{access token}HTTP/1.1 204 No Content

Token TTL

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

Extra-Kong Token Pairs

Kong can read access/token secret pairs that have been created directly in Vault, outside of the Kong Admin API. Currently vault-auth supports creating and reading credentials based on the Vault v1 KV engine. Create Vault KV secret values must contain the following fields:

{
access_token: <string>
secret_token: <string>
created_at: <integer>
updated_at: <integer>
ttl: <integer> (optional)
consumer: {
id: <uuid>
}
}

Additional fields within the secret are ignored. The key must be the access_token value; this is the identifier by which Kong queries the Vault API to fetch the credential data. See the Vault documentation for further information on the KV v1 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

We’re incredibly excited about the new capabilities this integration with Vault will provide Kong Enterprise customers. Get started with a free trial of Kong Enterprise today, refer to the Vault plugin documentation, and be sure to reach out on Kong Nation with any questions or feedback.