open-vault/website/content/docs/secrets/databases/couchbase.mdx

---
layout: docs
page_title: Couchbase - Database - Secrets Engines
description: |-
  Couchbase is one of the supported plugins for the database secrets engine.
  This plugin generates database credentials dynamically based on configured
  roles for the Couchbase database.
---

# Couchbase Database Secrets Engine

@include 'x509-sha1-deprecation.mdx'

Couchbase is one of the supported plugins for the database secrets engine. This
plugin generates database credentials dynamically based on configured roles for
the Couchbase database.

See the [database secrets engine](/docs/secrets/databases) docs for
more information about setting up the database secrets engine.

## Capabilities

| Plugin Name                 | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization |
| --------------------------- | ------------------------ | ------------- | ------------ | ---------------------- |
| `couchbase-database-plugin` | Yes                      | Yes           | Yes          | Yes (1.7+)             |

## Setup

1.  Enable the database secrets engine if it is not already enabled:

    ```bash
    $ vault secrets enable database
    Success! Enabled the database secrets engine at: database/
    ```

    By default, the secrets engine will enable at the name of the engine. To
    enable the secrets engine at a different path, use the `-path` argument.

1.  Configure Vault with the proper plugin and connection configuration:

    ```bash
    $ vault write database/config/my-couchbase-database \
        plugin_name="couchbase-database-plugin" \
        hosts="couchbases://127.0.0.1" \
        tls=true \
        base64pem="${BASE64PEM}" \
        username="vaultuser" \
        password="vaultpass" \
        allowed_roles="my-*-role"
    ```

    Where `${BASE64PEM}` is the server's root certificate authority in PEM
    format, encoded as a base64 string with no new lines.

    To connect to clusters prior to version 6.5.0, a `bucket_name` must also
    be configured:

    ```bash
    $ vault write database/config/my-couchbase-database \
        plugin_name="couchbase-database-plugin" \
        hosts="couchbases://127.0.0.1" \
        tls=true \
        base64pem="${BASE64PEM}" \
        username="vaultuser" \
        password="vaultpass" \
        allowed_roles="my-*-role" \
        bucket_name="travel-sample"
    ```

1.  You should consider rotating the admin password. Note that if you do, the
    new password will never be made available through Vault, so you should
    create a Vault-specific database admin user for this.

    ```bash
    vault write -force database/rotate-root/my-couchbase-database
    ```

## Usage

After the secrets engine is configured, configure dynamic and static roles
to enable generating credentials.

### Dynamic roles

1.  Configure a dynamic role that maps a name in Vault to a JSON string
    specifying a Couchbase RBAC role. The default value for
    `creation_statements` is a read-only admin role:
    `{"Roles": [{"role":"ro_admin"}]}`.

    ```bash
    $ vault write database/roles/my-dynamic-role \
        db_name="my-couchbase-database" \
        creation_statements='{"Roles": [{"role":"ro_admin"}]}' \
        default_ttl="5m" \
        max_ttl="1h"
    ```

    Note that any groups specified in the creation statement must already exist.

1.  Generate a new credential by reading from the `/creds` endpoint with the name
    of the role:

    ```bash
    $ vault read database/creds/my-dynamic-role
    Key                Value
    ---                -----
    lease_id           database/creds/my-dynamic-role/wiLNQjtcvCOT1VnN3qnUJnBz
    lease_duration     5m
    lease_renewable    true
    password           mhyM-Gs7IpmOPnSqXEDe
    username           v-root-my-dynamic-role-eXnVr4gm55dpM1EVgTYz-1596815027
    ```

### Static roles

1.  Configure a static role that maps a name in Vault to an existing couchbase
    user.

    ```bash
    $ vault write database/static-roles/my-static-role \
        db_name="my-couchbase-database" \
        username="my-existing-couchbase-user" \
        rotation_period=5m
    ```

1.  Retrieve the credentials from the `/static-creds` endpoint:

    ```bash
    $ vault read database/static-creds/my-static-role
    Key                    Value
    ---                    -----
    last_vault_rotation    2020-08-07T16:50:48.393354+01:00
    password               Z4-KH8F-VK5VJc0hSkXQ
    rotation_period        5m
    ttl                    4m39s
    username               my-existing-couchbase-user
    ```

## API

The full list of configurable options can be seen in the [Couchbase database plugin API](/api-docs/secret/databases/couchbase) page.

For more information on the database secrets engine's HTTP API please see the [Database secret secrets engine API](/api-docs/secret/databases) page.