Secret (Vault)

Secrets tell the engine where a secret manager keeps the values plugins reference.

In the console SecretsEngine resource secret

What a secret is

A secret tells the gateway where a secret manager keeps the values plugins reference. This one reads them from a Vault key-value store at Address, below Path prefix, signed in with Token. A plugin field then carries a reference in place of the value, for example $secret://vault/production/<key>/<field> for this secret under the ID production.

Only a version-one key-value mount is read. On a version-two mount a prefix with data/ resolves to nothing, so a plugin receives the reference text instead of the value.

When to use it

• The passwords and keys plugins send on, to a log service or a backend for example, are kept in Vault by your security team rather than written on routes.
• Several environments read their values from one Vault, each through a secret of its own and below a path of its own.
• A Vault Agent or Proxy beside the gateway adds the token itself, and the secret carries an empty Token.
• Each team has its own Vault namespace, named under Namespace.

Not for values kept in AWS Secrets Manager — see Secret (Secrets tell the engine where a secret manager keeps the values plugins reference) or values kept in Google Cloud Secret Manager — see Secret (Secrets tell the engine where a secret manager keeps the values plugins reference).

Set it up

Read secrets from a Vault key-value store

The mount must be a version-one key-value store; a version-two mount, whose paths carry data/, resolves to nothing. A plugin field reads a value as $secret://vault/production/<key>/<field>.

Under General set ID to vault/production. Under Connection set Address to https://vault.example.com:8200. Under Credentials set Token to <secret>. Under Keys set Path prefix to kv/gateway.

secret · Vault · as the console saves it

{
  "id": "vault/production",
  "uri": "https://vault.example.com:8200",
  "prefix": "kv/gateway",
  "token": "<secret>"
}

Things to know

• When Vault cannot answer, a reference to this secret resolves to nothing: a plugin receives the reference text, and a consumer whose credential names it is skipped. A Vault that never answers holds the request first, for five seconds unless Timeout sets another wait.
• Path prefix — With an empty Path prefix the reference carries the mount too, $secret://vault/<name>/<mount>/<key>/<field>.
• Path prefix — A version-two prefix without data/ answers 500 to requests reading this secret and, once a plugin's credential names it, to every request and consumer or credential save of that plugin.
• ID — The secret is stored as its manager and this ID joined by a slash, vault/production for the ID production. A reference names the secret by that ID.
• Address — Only http and https addresses are kept: another scheme, ftp://vault.:8200 for example, and an address with a trailing slash are refused when you save.
• Deleting a secret makes every reference to it stop resolving. g8 does not see a certificate whose private key is read from the secret, so deleting the secret can break TLS for that certificate.
• AdviceKeep the token out of the stored secret: write Token as an $env:// reference to a variable of the gateway host.

Referring to a value

Any string setting of a plugin, a credential or an upstream's TLS block may carry a reference the engine resolves when it runs: $secret://vault/<id>/<key>/<field>, where <id> is the part of this secret's ID after the manager's name, the next part is the key under the path prefix, and the last is one field of that key. A reference that resolves to nothing is kept as its own text.

Settings

The fields as the console shows them, section by section.

General

IDidstringRequired

Letters, digits, dots, hyphens and underscores, up to 64 characters. It cannot be changed later. The secret is stored as its manager and this ID joined by a slash. In JSON it carries the manager's name and a slash in front, as the pattern shows; the console asks only for the part after the slash.

the manager name, a slash and the ID

pattern

^vault/.+

Connection

When the manager cannot answer, a reference to this secret resolves to nothing: a plugin receives the reference text, and a consumer whose credential names it is skipped. A manager that never answers holds the request first: Vault for five seconds, AWS and GCP for sixty.

AddressuristringRequired

Without a trailing slash; an https address is checked against the certificate authorities the gateway trusts.

pattern

^https?:\/\/([\da-zA-Z.-]+|\[[\da-fA-F:]+\])(:\d+)?(\/[^?#]*[^\/?#])?$

Namespacenamespacestring

Sent as the X-Vault-Namespace header; Vault Community Edition ignores it.

Timeouttimeoutnumber

How long a reference to this secret waits for Vault before it resolves to nothing. Left empty, it waits 5.

over 0 · in seconds

Credentials

TokentokenstringRequired

May be an $env:// reference to a variable of the gateway host. An empty token works in front of a Vault Agent or Proxy that adds its own. Stored on the engine and shown only to roles that manage this object.

Keys

Path prefixprefixstringRequired

Where keys are read from: $secret://vault/<name>/<key>/<field> reads <field> from <prefix>/<key>, where <name> is the name of this secret. With an empty prefix the reference carries the mount too: $secret://vault/<name>/<mount>/<key>/<field>. Only a version-one key-value mount is read; on version two a prefix with data/ resolves to nothing.