In today’s data-driven world, secure database credential management is a paramount concern for organizations of all sizes. As we strive to empower you with cutting-edge solutions, we are thrilled to announce the release of our HashiCorp Vault plugin for Capella database credential management. 

Incorporating HashiCorp Vault into Capella offers a multifaceted approach to database security:

    • One of the key advantages is external, centralized user management, where user identities and access permissions are managed in a unified and secure manner. This ensures that access to your databases is controlled, audited, and consistent across your organization. 
    • Vault’s capabilities extend to credential usage auditing, providing detailed logs and insights into who accessed your databases, when, and for what purpose. This level of transparency is invaluable for compliance and security teams, enabling them to track data access and meet regulatory requirements effectively. 
    • Vault’s automation shines through with automatic credential rotation and revocation, reducing the risk of unauthorized access due to stale or compromised credentials. 
    • Finally, Vault enables the issuance of dynamic temporary credentials, granting users time-limited access to databases. This not only enhances security but also simplifies user management by reducing the need for long-term credentials. Together, these features transform how you manage database access, making it more secure, efficient, and compliant.

This article serves as a guide to help you leverage the capabilities of our plugin effectively. We will walk you through the entire process, from setting up a local Docker container Vault to managing dynamic credentials effortlessly. By the end of this tutorial, you’ll be well-equipped to enhance your database security with ease.

Let’s dive into the world of secure database credential management and unlock the potential of our HashiCorp Vault plugin for Capella

Step 1: Preparations

Before diving into the details, it’s essential to lay the foundation. In this initial step, we’ll guide you through the essential preparations required to set the stage for seamless integration. From creating an API key to setting up a sandbox database and gathering crucial organizational details, these preparations ensure you have everything you need to complete the plugin setup.

Create a Capella API Key

Begin by ensuring you have the necessary API keys. Navigate to your organization settings and head to the API Key section. Here, generate a Version 4 key with the organization owner role. This key will be instrumental in our credential management process. The reason for the organization owner role is that we will rotate the root credential later on.

Create a Capella API Key

Decode API Key Credentials

We will need to provide the Capella ACCESS_KEY and the SECRET_KEY when we configure the vault plugin. We will grab this from the API key we generated earlier. 

    • Download the Key
    • Click copy button twice at the end of the  API Key Token field. 

Decode API Key Credentials

    • Decode it using base64

The decoded key will have two values separated by a semicolon:

The first one is your ACCESS_KEY and the second one is your SECRET_KEY. You will need this later when you configure the plugin.

Set Up a Sandbox Database

To facilitate this demo, set up a sandbox database. This will serve as a safe environment for testing our plugin.

Create a Bucket and Scope

We’ll also create a bucket vault-bucket-1 and a scope vault-bucket-1-scope-1 within our cluster, which will be used when creating dynamic credentials later on.

Create a Bucket and Scope

Gather Essential Information

For the plugin configuration, you’ll need your organization ID, project ID, and cluster ID. The easiest way to obtain these details is by copying them from the URL and saving them in a text file for reference.

    • oid is your organization Id
    • projectId is your project id
    • dbid is your database id

Gather Essential Information

Step 2: Set up Vault

Now, let’s get started with the technical aspect. We have two options to run the demo. 

    1. To run the demo, clone the repository and utilize the Dockerfile within it. This Dockerfile includes steps to compile the plugin from source. 
    2. Alternatively, download the binary version of the plugin from the releases page and use that in your Vault installation.

I will provide instructions for both methods. Please choose the path that suits your needs and follow the corresponding steps. There is no need to execute both methods

Option 1: Use the Dockerfile in the plugin repository

Begin by cloning our GitHub repository:

This repository contains the plugin source code, we will need to build the plugin. For this demo we will be building a docker image using Hashicorp’s vault image. The plugin will be built during the Docker image creation process. This method should only be used for demo purposes. Please follow the instructions from Hashicorp on how to install the plugin and use it in your environment.

Use the Dockerfile in the plugin repository

Now the image has been built, We’ll launch a Vault server in a Docker container, configured for development mode. This allows us to bypass certain security features for easier testing. The Vault server will listen on port 8200 and will be initialized with a root token set to password. We’ll also enable debug-level logging to capture detailed information during our tests.

Vault server will listen on port 8200

Please proceed directly to Step 3, bypassing Option 2.

Option 2: Download the plugin binary

Begin by downloading the plugin from the releases page. As of writing this article, the latest version is 1.0.0, and since I am running Linux, I will proceed with downloading the linux version

Ensure you download the version appropriate for your computer’s architecture. 

As a security best practice, it’s important to validate the integrity of the file. Therefore, also download the checksums of the binaries, which can be found on the releases page.

Locate the checksum corresponding to the file you downloaded within the text file.

Locate the checksum

Generate the checksum and validate the result

checksum comparison indicates a match

The checksum comparison indicates a match, confirming that the file validation is successful.

It is now secure to extract the contents of the zipfile and retrieve the vault plugin. 

At this point, the vault plugin binary should be in our folder. The final step is to generate the hash of this binary, which is necessary for registering the plugin with Vault later. It’s important to note that this hash is for the binary itself, not the zip file downloaded earlier.

Executing this command should have resulted in the creation of a new file containing the hash of the vault plugin.

We will also need to create a vault configuration that defines where the plugin resides.

 The final step involves creating a custom password policy that mirrors the policy used in Capella.

Having downloaded the vault plugin and generated its hash, we will now initiate a Vault server in a Docker container, configured in development mode. This setup enables us to circumvent some security features for simplified testing purposes. 

The Vault server will listen on port 8200 and will be initialized with a root token set to password. We’ll also enable debug-level logging to capture detailed information during our tests. It is also important to note that we will need to mount our plugin and sha as a volume:

Vault server will listen on port 8200

Step 3: Enable Database Secrets

Vault is now up and running in development mode. Next We’ll enable Vault’s database secrets engine. This engine allows Vault to generate dynamic credentials for databases, and it’s crucial for our plugin to function correctly. By enabling this, we’re setting the stage for Vault to manage our Capella database credentials. Open up a new terminal and run the following:

Enable Database Secrets

Step 4: Register the Plugin

We’ll register our custom plugin with Vault. This involves calculating the SHA-256 hash of the plugin binary to ensure its integrity. Vault uses this hash to verify that the plugin hasn’t been tampered with when it’s invoked. Once the hash is calculated, we’ll use it to register the plugin.

Register the Plugin

Now the plugin has been successfully registered.

Step 5: Upload Password Policy

We’ll upload a password policy to Vault that aligns with Capella’s password requirements. This ensures that any credentials generated by Vault for Capella will comply with Capella’s security standards. The policy will be defined in a HashiCorp Configuration Language (HCL) file. This file was added to the Docker image during the build.

Upload Password Policy

Step 6: Create Database Config

We’ll configure Vault to connect to our Capella cluster. This involves specifying various parameters like the base URL for Capella’s cloud API, organization ID, project ID, and cluster ID. We’ll also provide the Capella access key we generated earlier. This configuration allows Vault to interact with our Capella cluster and manage credentials dynamically. 

Create Database Config

Now the Capella plugin is configured and able to talk to Capella. 

Step 7: Rotate Root Credentials

We’ll perform a security best practice by rotating the high-privilege root credentials that Vault uses to manage the Capella database. This minimizes the risk associated with any potential exposure of these credentials.

Rotate Root Credentials

Step 8: Create a Dynamic Role

Next We’ll define a dynamic role in Vault. This role will have a set of permissions, defined in JSON format, that specify what kind of database operations are allowed. For example, we’ll grant data_reader and data_writer privileges on a specific bucket and scope in our Capella cluster. This dynamic role will be used to generate credentials with these permissions.

Create a dynamic role

Step 9: Create New Credentials

Finally, we’ll generate a new set of database credentials using the dynamic role we created. These credentials are temporary and will adhere to the TTL (Time-To-Live) settings we’ve configured. This is the culmination of our setup, demonstrating how Vault can dynamically manage Capella database credentials.

create new credentials

Let’s go back to Capella to check if our credentials in fact show in the UI as well.

manage Capella database credentials


In conclusion, our HashiCorp Vault plugin for Capella’s database credential management opens new horizons in enhancing the security of your database infrastructure. Through this step-by-step tutorial, you’ve gained valuable insights into setting up and utilizing the plugin effectively.

By embracing this solution, you’re simplifying the process of managing database credentials. We encourage you to explore the full potential of our plugin and look forward to your experiences and feedback.

Secure, efficient, and user-friendly database credential management is now at your fingertips. Take the first step towards a more secure database environment today!

If you’re interested in learning more about how you can build your own mission-critical modern applications on Couchbase, try our 30 day free trial of Couchbase Capella. And to see more of what our customers are doing with Couchbase, check out our customer case study page!


Posted by Istvan Orban

Istvan Orban is the Principal Product Manager for Couchbase and lives in the United Kingdom. Istvan has a wide range of experience as a Full stack Software Engineer, Team leader and Devops Engineer. His main focus is security and Single Sign On. Istvan has led several large scale projects of his 20 year professional career.

Leave a reply