Get Started Sign In

Vault secrets management for installations with Helm 3-deployed sidecars

Role of Vault in a Cyral deployment

You can configure Cyral to use HashiCorp Vault to store sensitive credentials and certificates. Items that Cyral can read from a Vault store include:

  • Database account credentials to be used for single-sign on (SSO). The Cyral Access Portal allows users to connect with their SSO credentials and get access to data repositories you've configured. To do this, Cyral maps an SSO user or group to a local account on the database. At login time, Cyral handles database authentication using the local account credentials you've stored in Vault. See instructions below for storing credentials. The Cyral authenticator service accepts credentials as per-repo JSON objects in the format {"repo1":["creds-repo1"]}

  • Certificate chain, server certificate, and private key for sidecar communication. The Cyral sidecar supports mutual TLS (mTLS) authentication and relies on Vault to store the required certificates and keys.

  • Certificate chain, client certificate, and private key for log data communication (Filebeat). The Cyral sidecar relies on a utility called Filebeat to send log information to Logstash or ElasticSearch. In this configuration, you can choose to enable TLS and optionally mutual TLS to secure the connection.


Note! In this document, we assume Cyral will authenticate to Vault using AWS authentication. These instructions assume you have a Kubernetes cluster running on AWS Elastic Kubernetes Server (EKS). If you do not have one, you can create a cluster following this guide.

Before you begin integrating Vault into your Cyral deployment, have the following ready:

  • A Vault instance

  • A service account with read access to the secrets location in the Vault server. You'll need to provide the authentication credentials for this account. Cyral supports using AWS, Kubernetes, or app role authentication for connecting to Vault.

    • Note for AWS authentication: These instructions assume that you've created an OIDC provider and an identity provider, and that you've created the AWS IAM roles that we will bind to Kubernetes Service accounts.

    • Note for app role authentication: Make sure remove_secret_id_file_after_reading is set to false. The sidecar must have continuous access to the secret id file.

  • Optional: A Vault account with admin or write access to your Vault instance. These instructions show examples that create and update secrets on the Vault server. To follow these examples, you will need admin or write access to the secrets.

  • The payload you plan to store in Vault. For example, for database credentials, make sure you have the username and the password for each database account.

Add Vault Integration in Cyral Management Console

  1. In the Cyral control plane UI, click Integrations, find the Vault tile, and click Configure.

  2. Provide the integration values:

    • Integration Name: A name you'll use to identify this integration. The name must be unique. You can change it after the integration is created.

    • Server: The Vault server address and port number where Cyral sidecars will connect.

    • Method section of the Vault Agent configuration file: This specifies how Cyral will authenticate to your Vault server. This information comes from the configuration file of your Vault Agent. In this example, we're using AWS IAM. This mode uses a role (for example, cyral-sidecar) that you've created in your Vault Server and that you've associated with one or more AWS IAM roles. The sidecar needs to have access to one of those IAM roles, for example, by attaching it to the EC2 instance where the sidecar was deployed (for AWS deployments). For other authentication methods, please refer to the Vault Agent documentation.

Below, we show an example configuration:

In the example shown above, the Vault server uses AWS IAM authentication. The block pasted in the Method section specifies where Cyral will find the authentication information. In this example, “cyral-sidecar” is the name of the role in the Vault server:

method "aws" {

  mount_path = "auth/aws"

  config {

    type = "iam"

    role = "cyral-sidecar"



Supported Vault secrets engines

Cyral stores your Vault integration configuration in an open format. The following types of Vault secrets engines are supported:

Associate the Vault integration with your sidecar

Now that your Vault integration is in place, you can deploy sidecars that use it. When downloading the sidecar template from the Cyral management console, choose the Vault integration that you want the sidecar to use. For example, to use the vault-prod integration we created above, you would choose it as shown here:

Store database credentials in Vault

The following example shows how to store a local database account credential set using the vault command line utility. For this example, we'll store the credentials using Vault's KV-v2 secrets engine.

The first argument after put or patch is the secret path. You can use any value for the secret path, but it is advisable to organize it so that it can be extended to include more repos and more local account credentials.

vault kv put /cyral/dbsecrets/patientdata/analyst username=analyst

vault kv patch /cyral/dbsecrets/patientdata/analyst password=STRONGPASSWORD

# Optional, database name you want users connected to upon login

vault kv patch /cyral/dbsecrets/patientdata/analyst databaseName=finance

Kubernetes example: The kubectl equivalent of the first two example commands above is as follows. This assumes you're using a pod, "vault-0". Replace all example values to match your environment:

kubectl exec -n vault vault-0 -- sh -c "VAULT_TOKEN=root vault kv put /cyral/dbsecrets/patientdata/analyst username='analyst' password='STRONGPASSWORD"

Add local accounts

  1. In the Cyral management plane UI, go to Data Repos and click the name of your repo.

  2. Click Local Accounts, and click the plus sign.

  3. Choose Hashicorp Vault, and paste the secret path you created above. 

  4. In Account username provide the username for a database user whose credentials you've stored in Vault. 

  5. Optional: Some Vault secrets engines, such as Vault's database secrets engine, allow usernames to be dynamically created, meaning that the username is unknown until Vault generates it at login time. For such cases, check the Dynamic username checkbox at the bottom.

  6. In the secret path section, provide the path to the credentials you stored in Vault Server. This path does not need to follow any strict formatting rules. The only requirement is that your Vault integration authentication method and associated policy must provide access to the secret path you specify here.

  7. Click Track.

Add an Identity to Account Map

  1. In the Cyral management plane UI, go to Data Repos and click the name of your repo.

  2. Click Identity to Account Map and click the plus sign.

  3. Choose Group or User as the Identity Type, and provide the name of the SSO user or group you'll map to the local account. Choose the local account you created in the previous procedure, choose Unlimited or Limited, and click Create.

Below is an example identity map showing association between SSO user "Nancy Drew" and the local account “analyst”:

With this mapping in place, database users can connect to the Cyral Access Portal with their SSO credentials and get a connection string that allows them to log in to the data repository you configured above. At login time, Cyral completes the database authentication using the local account credentials you've stored in Vault.

See also

Vault secrets management for Cyral in a Nomad-automated environment

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.