README.md
1# vault-plugin-database-couchbase
2
3[](https://circleci.com/gh/hashicorp/vault-plugin-database-couchbase)
4
5A [Vault](https://www.vaultproject.io) plugin for Couchbase
6
7This project uses the database plugin interface introduced in Vault version 0.7.1.
8
9The plugin supports the generation of static and dynamic user roles and root credential rotation.
10
11## Build
12
13To build this package for any platform you will need to clone this repository and cd into the repo directory and `go build -o couchbase-database-plugin ./cmd/couchbase-database-plugin/`. To test `go test` will execute a set of basic tests against against the docker.io/couchbase/server-sandbox:6.5.0 couchbase database image. To test against different sandbox images, for example 5.5.1, set the `COUCHBASE_VERSION=5.5.1` environment variable. If you want to run the tests against a local couchbase installation or an already running couchbase container, set the environment variable `COUCHBASE_HOST` before executing. **Note** you will need to align the Administrator username, password and bucket_name with the pre-set values in the `couchbase_test.go` file. Set VAULT_ACC to execute all of the tests. A subset of tests can be run using the command `go test -run TestDriver/Init` for example.
14
15## Installation
16
17The Vault plugin system is documented on the [Vault documentation site](https://www.vaultproject.io/docs/internals/plugins.html).
18
19You will need to define a plugin directory using the `plugin_directory` configuration directive, then place the
20`vault-plugin-database-couchbase` executable generated above, into the directory.
21
22**Please note:** Versions v0.2.0 onwards of this plugin are incompatible with Vault versions before 1.6.0 due to an update of the database plugin interface.
23
24Sample commands for registering and starting to use the plugin:
25
26```bash
27$ SHA256=$(shasum -a 256 plugins/couchbase-database-plugin | cut -d' ' -f1)
28
29$ vault secrets enable database
30
31$ vault write sys/plugins/catalog/database/couchbase-database-plugin sha256=$SHA256 \
32 command=couchbase-database-plugin
33```
34
35At this stage you are now ready to initialize the plugin to connect to couchbase cluster using unencrypted or encrypted communications.
36
37Prior to initializing the plugin, ensure that you have created an administration account. Vault will use the user specified here to create/update/revoke database credentials. That user must have the appropriate permissions to perform actions upon other database users.
38
39### Unencrypted plugin initialization
40
41```bash
42$ vault write database/config/insecure-couchbase plugin_name="couchbase-database-plugin" \
43 hosts="localhost" username="Administrator" password="password" \
44 bucket_name="travel-sample" \ # only needed for pre-6.5.0 clusters
45 allowed_roles="insecure-couchbase-admin-role,insecure-couchbase-*-bucket-role,static-account"
46
47# You should consider rotating the admin password. Note that if you do, the new password will never be made available
48# through Vault, so you should create a vault-specific database admin user for this.
49$ vault write -force database/rotate-root/insecure-couchbase
50
51 ```
52
53Note: If you want to connect the plugin to a couchbase cluster prior to version 6.5.0 you will also have to supply an existing bucket (bucket_name="travel-sample") or the command will fail with the error message **"error verifying connection: error in Connection waiting for cluster: unambiguous timeout"**.
54
55### Encrypted plugin initialization
56
57The example here uses the self signed CA certificate that comes with the out of the box couchbase cluster installation and is not suitable for real production use where commercial grade certificates should be obtained.
58
59```bash
60$ BASE64PEM=$(curl -X GET http://Administrator:Admin123@127.0.0.1:8091/pools/default/certificate|base64 -w0)
61
62$ vault write database/config/secure-couchbase plugin_name="couchbase-database-plugin" \
63 hosts="couchbases://localhost" username="Administrator" password="password" \
64 tls=true base64pem=${BASE64PEM} \
65 bucket_name="travel-sample" \ # only needed for pre-6.5.0 clusters
66 allowed_roles="secure-couchbase-admin-role,secure-couchbase-*-bucket-role,static-account"
67
68# You should consider rotating the admin password. Note that if you do, the new password will never be made available
69# through Vault, so you should create a vault-specific database admin user for this.
70$ vault write -force database/rotate-root/secure-couchbase
71```
72
73### Dynamic Role Creation
74
75When you create roles, you need to provide a JSON string containing the Couchbase RBAC roles which are documented [here](https://docs.couchbase.com/server/6.5/learn/security/roles.html). From Couchbase 6.5 groups are supported and the creation statement can contain just roles or just groups or a mixture of the two. **Note** to use a group, it must have been created in the database previously.
76
77```bash
78# if a creation_statement is not provided the user account will default to read only admin, '{"roles":[{"role":"ro_admin"}]}'
79$ vault write database/roles/insecure-couchbase-admin-role db_name=insecure-couchbase \
80 default_ttl="5m" max_ttl="1h" creation_statements='{"roles":[{"role":"admin"}],"groups":["Supervisor"]}'
81
82$ vault write database/roles/insecure-couchbase-travel-sample-bucket-role db_name=insecure-couchbase \
83 default_ttl="5m" max_ttl="1h" creation_statements='{"roles":[{"role":"bucket_full_access","bucket_name":"travel-sample"}]}'
84Success! Data written to: database/roles/insecure-couchbase-travel-sample-bucket-role
85```
86
87If you create a role that uses groups on a pre 6.5 couchbase server it will be successful, but when you try to generate credentials
88you will receive the error **rpc error: code = Unknown desc = {"errors":{"groups":"Unsupported key"}} ...**
89
90To retrieve the credentials for the dynamic accounts
91
92```bash
93
94$ vault read database/creds/insecure-couchbase-admin-role
95Key Value
96--- -----
97lease_id database/creds/insecure-couchbase-admin-role/KJ7CTmpFni6U6BCDJ14HcmDm
98lease_duration 5m
99lease_renewable true
100password A1a-yCSH5rAh8QAkCzwu
101username v-token-insecure-couchbase-admin-role-yA2hgb0tfewf
102
103$ vault read database/creds/insecure-couchbase-travel-sample-bucket-role
104Key Value
105--- -----
106lease_id database/creds/insecure-couchbase-travel-sample-bucket-role/OzHdfkIZdeY9p8kjdWur512j
107lease_duration 5m
108lease_renewable true
109password A1a-0yTIuO4q0dCvphz1
110username v-token-insecure-couchbase-travel-sample-bucket-role-iN5
111
112```
113
114### Static Role Creation
115
116In order to use static roles, the user must already exist in the Couchbase security settings. The example below assumes that there is an existing user with the name "vault-edu". If the user does not exist you will receive the following error.
117
118```bash
119* 1 error occurred:
120 * error setting credentials: rpc error: code = Unknown desc = user not found | {"unique_id":"74f229fd-b3b3-4036-9673-312adae094bb","endpoint":"http://localhost:8091"}
121```
122
123```bash
124$ vault write database/static-roles/static-account db_name=insecure-couchbase \
125 username="vault-edu" rotation_period="5m"
126Success! Data written to: database/static-roles/static-account
127````
128
129To retrieve the credentials for the vault-edu user
130
131```bash
132$ vault read database/static-creds/static-account
133Key Value
134--- -----
135last_vault_rotation 2020-06-15T14:32:16.682130141-05:00
136password A1a-09ApRvglZY1Usdjp
137rotation_period 5m
138ttl 30s
139username vault-edu
140```
141
142## Developing
143
144You can run `make dev` in the root of the repo to start up a development vault server and automatically register a local build of the plugin. You will need to have a built `vault` binary available in your `$PATH` to do so.
145
){kind=link}