luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/source/docs/secrets/consul/index.html.md

5.2 KiB
Raw Blame History

layout page_title sidebar_current description
docs Secret Backend: Consul docs-secrets-consul The Consul secret backend for Vault generates tokens for Consul dynamically.

Consul Secret Backend

Name: consul

The Consul secret backend for Vault generates Consul API tokens dynamically based on Consul ACL policies.

This page will show a quick start for this backend. For detailed documentation on every path, use vault help after mounting the backend.

Quick Start

The first step to using the mysql backend is to mount it. Unlike the generic backend, the consul backend is not mounted by default.

$ vault mount consul
Successfully mounted 'consul' at 'consul'!

Next, we must configure Vault to know how to contact Consul. This is done by writing the access information:

$ vault write consul/config/access address=127.0.0.1:8500 token=root
Success! Data written to: consul/config/access

In this case, we've configured Vault to connect to Consul on the default port with the loopback address. We've also provided an ACL token to use with the token parameter. Vault must have a management type token so that it can create and revoke ACL tokens.

The next step is to configure a role. A role is a logical name that maps to a role used to generated those credentials. For example, lets create a "readonly" role:

POLICY='key "" { policy = "read" }'
$ echo $POLICY | base64 | vault write consul/roles/readonly policy=-
Success! Data written to: consul/roles/readonly

The backend expects the policy to be base64 encoded, so we need to encode it properly before writing. The policy language is documented by Consul, but we've definited a read-only policy.

To generate a new set Consul ACL token, we simply read from that role:

$ vault read consul/creds/readonly
Key           	Value
lease_id      	consul/creds/readonly/c7a3bd77-e9af-cfc4-9cba-377f0ef10e6c
lease_duration	3600
token         	973a31ea-1ec4-c2de-0f63-623f477c2510

Here we can see that Vault has generated a new Consul ACL token for us. We can test this token out, and verify that it is read-only:

$ curl 127.0.0.1:8500/v1/kv/foo?token=973a31ea-1ec4-c2de-0f63-623f477c25100
[{"CreateIndex":12,"ModifyIndex":53,"LockIndex":4,"Key":"foo","Flags":3304740253564472344,"Value":"YmF6"}]

$ curl -X PUT -d 'test' 127.0.0.1:8500/v1/kv/foo?token=973a31ea-1ec4-c2de-0f63-623f477c2510
Permission denied

API

/consul/config/access

POST

Description
Configures the access information for Consul. This is a root protected endpoint.
Method
POST
URL
`/consul/config/access`
Parameters
  • address required The address of the Consul instance, provided as host:port
  • scheme optional The URL scheme to use. Defaults to HTTP, as Consul does not expose HTTPS by default.
  • token required The Consul ACL token to use. Must be a management type token.
Returns
A `204` response code.

/consul/roles/

POST

Description
Creates or updates the Consul role definition. This is a root protected endpoint.
Method
POST
URL
`/consul/roles/`
Parameters
Returns
A `204` response code.

GET

Description
Queries a Consul role definition. This is a root protected endpoint.
Method
GET
URL
`/consul/roles/`
Parameters
None
Returns
```javascript
{
    "data": {
        "policy": "abcdef="
    }
}
```

Delete

Description
Deletes a Consul role definition. This is a root protected endpoint.
Method
DELETE
URL
`/consul/roles/`
Parameters
None
Returns
A `204` response code.

/consul/creds/

GET

Description
Generates a dynamic Consul token based on the role definition.
Method
GET
URL
`/consul/creds/`
Parameters
None
Returns
```javascript
{
    "data": {
        "token": "973a31ea-1ec4-c2de-0f63-623f477c2510"
    }
}
```