Configure HashiCorp Vault Integration

Last modified on October 4, 2023

Secret store integrations allow you to use your existing third-party secret stores with StrongDM. Your credentials are stored in a tool that is controlled by you, and those credentials are never transmitted to StrongDM in any form. If you would like to learn more about how this integration works and why you might wish to use it, please read the Secret Stores Reference.

This guide will walk you through how to integrate HashiCorp Vault with StrongDM, as well as how to use it to connect to resources.

Limitations

The following are not supported for this integration:

  • HashiCorp Cloud Platform (HCP) Vault
  • Automatic rotation of the SecretID (i.e., VAULT_SECRET_ID environment variable)
  • Any other authentication method besides token-based authentication, TLS certificate-based authentication, or AppRole authentication
  • Any secrets engine that does not conform to the same URL structure as KV 1 or KV 2 (e.g., key management or SSH certificate signing)
  • Writing credentials to Vault (i.e., credentials must already be in Vault for StrongDM to read them)

Requirements

Before you begin, ensure that you have the following:

  • A running Vault server (see the Vault Installation Guide)
  • Credentials to some of your resources, stored in the Vault instance
  • Correct paths to the credentials

Authentication to Vault

StrongDM supports three authentication methods to enable your Relay to authenticate with Vault: token-based authentication, TLS certificate-based authentication, and AppRole authentication. For more information on these methods, see HashiCorp’s Vault tutorials: Token Authentication, TLS Certificate Authentication, and AppRole Authentication.

Token-based authentication

Set the VAULT_TOKEN environment variable to allow the Relay to authenticate with Vault.

  1. Get a token for Vault.
  2. Open the file /etc/sysconfig/sdm-proxy (unless you have moved or renamed your sdm-proxy file) for editing.
  3. In the file, add the following line to set the necessary environment variable (VAULT_TOKEN) on your Relay, being sure to replace <YOUR_TOKEN> with the actual value:
    VAULT_TOKEN=<YOUR_TOKEN>
  4. To enable the token to be periodically renewed automatically, also set the LEASE_RENEWAL_TTL environment variable. Be sure to replace <RENEWAL_RATE> with the specific increment of time after which you intend the token to be renewed. The rate is specified as a number of seconds with no suffix (e.g., 3600 for 3,600 seconds or 1 hour).
    LEASE_RENEWAL_TTL=<RENEWAL_RATE>
  5. Restart the sdm-proxy service (with something like sudo systemctl restart sdm-proxy, depending on your distribution).

Token-based authentication with Docker gateways

For Vault to integrate with a Docker gateway, an environment variable needs to be passed in for VAULT_TOKEN.

Typically, to run the Docker gateway, you run a command similar to this:

docker run --restart=always [--net=host] --name sdm-relay -e SDM_RELAY_TOKEN=<YOURTOKEN> -p 5000:5000 -d quay.io/sdmrepo/relay

You need to add the VAULT_TOKEN to the previous command:

docker run --restart=always [--net=host] --name sdm-relay -e VAULT_TOKEN=<VAULT_TOKEN> -e SDM_RELAY_TOKEN=<YOUR_TOKEN> -p 5000:5000 -d quay.io/sdmrepo/relay

Be sure to replace <VAULT_TOKEN> and <YOUR_TOKEN> with the correct values.

Token-based authentication with Kubernetes gateways

For Vault to integrate with a Kubernetes gateway, you need to pass in an environment variable for VAULT_TOKEN. Add the following to the env: block:

name: VAULT_TOKEN
   valueFrom:
    secretKeyRef:
     name: vault-secret
     key: token

TLS certificate-based authentication

Follow the Vault documentation regarding certificate authentication with Vault.

When you install the TLS certificates on the Relay, place them in a directory that is accessible to the sdm relay service. Save the file paths for use later. Note that the policy for the certificate used needs to allow access to the secret paths.

AppRole authentication

Set the environment variable inputs VAULT_ROLE_ID, VAULT_SECRET_ID, and VAULT_TOKEN_TTL to allow the Relay to authenticate with Vault.

  1. Get your RoleID and SecretID for Vault.
  2. Determine what value to set for VAULT_TOKEN_TTL, an integer number of seconds (e.g., 600) after which the Relay will refresh the credentials retrieved with VAULT_ROLE_ID and VAULT_SECRET_ID. Its value should be set to approximately match but not exceed the lifetime of tokens generated with the AppRole authentication method, which is the token_ttl setting that is configured when AppRole is enabled in Vault.
  3. Open the file /etc/sysconfig/sdm-proxy (unless you have moved or renamed your sdm-proxy file) for editing.
  4. In the file, add the following lines to set the necessary environment variables on your Relay, being sure to replace the placeholders with the actual values:
    VAULT_ROLE_ID=<YOUR_ROLE_ID>
VAULT_SECRET_ID=<YOUR_SECRET_ID>
VAULT_TOKEN_TTL=<YOUR_TOKEN_TTL>
  5. Restart the sdm-proxy service (with something like sudo systemctl restart sdm-proxy, depending on your distribution).

Configure the Secret Store with the Admin UI

Once you have your Vault set up, credentials stored, and your Relay is able to access said credentials, it’s time to register the Vault with StrongDM.

  1. In the Admin UI, go to Network > Secret Stores.

  2. Click the add secret store button.

  3. On the Add Secret Store form, set the following:

    Secret Stores Settings
    Secret Stores Settings
    1. Display Name (Required): The name that you enter here will show up in the Admin UI.
    2. Secret Store Type (Required): Select either HashiCorp Vault, HashiCorp Vault (Token), or HashiCorp Vault (AppRole).
    3. Enter the appropriate authentication information for the selected Secret Store Type:
      1. For HashiCorp Vault (Token) (token-based authentication), enter the server address (e.g., https://vault.example.com:1235).
      2. For HashiCorp Vault (certificate-based authentication), enter the paths to the certificates stored on your Relay server.
      3. For HashiCorp Vault (AppRole) (AppRole authentication), enter the server address (e.g., https://vault.example.com:8200).
    4. Namespace (Optional): If you have a secret inside a Vault Enterprise namespace, you can use this option to allow StrongDM to authenticate to a specified namespace and access the secret within it. Using either a root token or a token created inside the namespace, you can access the secret in the following ways:
      1. Set an empty string and use the secret path namespace/mysecret?key=username.
      2. Set namespace/ and use the secret path mysecret?key=username.

If you have configured the Relay correctly for secret store access and authentication, you will see the green online indicator.

Test Access to the Resource

Now, create a resource that uses the secret store, assign it to a Role that is assigned to a User, and verify that you can connect.

  1. In the Admin UI, add a new resource, such as a Server or Datasource, and choose the Vault Secret Store type.
  2. Fill out the information for a resource whose credentials you have stored in your Vault secret store.
  3. Select the Vault Secrets Store you created for the Secret Store field, and then fill in the path to the secrets that you have stored in your secret store.
    1. Vault accepts plaintext secrets, which you would use to store one credential field per secret, or JSON secrets, which could include many credential values with different keys. If using JSON, add the key along with the path to the credential, (e.g., example-secret?key=username). Note that Vault will even allow the direct import of JSON (e.g., vault kv put secret/foo @data.json).
    2. It is preferred that certificates be Base64-encoded. If the secret you are storing is a certificate, you should Base64-encode it, and then enter the path as follows when setting up a resource to use it: example-secret?key=certificate&encoding=base64.
  4. Submit the form.
  5. Go to Roles, create a Role with an access rule that grants access to the resource, and assign the Role to the User.
  6. Log in as that User in your local GUI (or have the User do so, if not yours) and verify that the resource exists, test a connection, and execute a query.

Congratulations! You have connected to a resource using secret stores.

Configure Vault to Use the StrongDM HTTP Proxy

This section will show you how to proxy HashiCorp Vault HTTP API and CLI traffic through StrongDM.

Vault is a client/server application that lets you securely access, read, write, and store secret information, like API keys, database credentials, and passwords. When secrets are added to Vault, they are passed to secrets engines, which read and write the data to storage. The flow of requests, or traffic, to and from Vault is typically managed via the Vault HTTP API or CLI, but you can run all Vault commands and management through StrongDM instead.

Using the StrongDM HTTP proxy allows you to keep Vault internal to your network without having to expose it for external access, easily audit all commands run against Vault using StrongDM as the proxy, and obfuscate the exact address of the server.

Prerequisites

To follow these instructions, you need to know your full Vault address and port, your subdomain in StrongDM, and your Vault token (if using HTTP).

Instructions

We’ve outlined five different ways to set up Vault to use the StrongDM HTTP proxy. Choose one: HTTP, HTTP Custom Auth, CLI for Vault HTTP API, Vault CLI with HTTP Custom Auth, or Vault CLI with HTTP.

Note the following:

  • CLI and curl obey the http_proxy and https_proxy variables.
  • Set https_proxy="127.0.0.1:65230" in the terminal session if you want to utilize functionality, but don’t add it to your Bash profile.

HTTP

  1. In the StrongDM Admin UI, click Websites.

  2. Click add website, and then set:

    • Display Name: Enter a name for the website.

    • Server Type: Select HTTP.

    • Base URL: Add your full Vault address, including port.

      • Example: https://vault.example.com:8200

    • HTTP Subdomain: Enter the subdomain that you want to use in StrongDM.

      • Example: vault

  3. Click Create.

HTTP Custom Auth

  1. In the StrongDM Admin UI, click Websites.

  2. Click add website, and then set:

    • Display Name: Enter a name for the website.

    • Server Type: Select HTTP Custom Auth.

    • Base URL: Add your full Vault address, including port.

      • Example: https://vault.example.com:8200

    • HTTP Subdomain: Enter the subdomain that you want to use in StrongDM.

      • Example: vault

    • Authorization Header (path): Enter the token for Vault that you want to use, in this specific format: Bearer {TOKEN}

      • Example: Bearer 12aab3cd-e456-f7ga-h8ij-912345678912

  3. Click Create.

CLI for Vault HTTP API

  • For HTTP with a proxy, use the following command, being sure to replace {TOKEN} with your actual Vault token and {SUBDOMAIN} with your desired subdomain in StrongDM (e.g., “vault”).

    This command uses curl to set StrongDM as a proxy, set a header with your bearer token to authorize access to Vault, and perform an HTTP GET request to access Vault secrets.

    curl --proxy "127.0.0.1:65230" -H "Authorization: Bearer {TOKEN}" -X GET https://{SUBDOMAIN}.sdm.network/v1/path/secret

    Example:

    curl --proxy "127.0.0.1:65230" -H "Authorization: Bearer 12aab3cd-e456-f7ga-h8ij-912345678912" -X GET https://vault.example.sdm.network/v1/path/secret

    In return, you’ll get a JSON payload similar to the following:

    {
  "request_id": "eebdb123-1a2b-01a1-1234-1abc2345d678",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 2764800,
  "data":{
     "password":"Thisisasecurepassword2021!",
     "username":"sdm"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

  • For HTTP without a proxy, use the following command, being sure to replace {TOKEN} with your actual Vault token and {SUBDOMAIN} with your desired subdomain in StrongDM (e.g., “vault”).

    This command uses curl to set a header with your bearer token to authorize access to Vault, and perform an HTTP GET request to access Vault secrets.

    curl -H "Authorization: Bearer {TOKEN}" -X GET https://{SUBDOMAIN}.sdm.network/v1/path/secret

    Example:

    curl -H "Authorization: Bearer 12aab3cd-e456-f7ga-h8ij-912345678912" -X GET https://vault.example.sdm.network/v1/path/secret

    In return, you’ll get a JSON payload similar to the following:

    {
  "request_id": "eebdb123-1a2b-01a1-1234-1abc2345d678",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 2764800,
  "data":{
     "password":"Thisisasecurepassword2021!",
     "username":"sdm"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

  • For HTTP Custom Auth with a proxy, use the following command, being sure to replace {SUBDOMAIN} with your desired subdomain in StrongDM (e.g., “vault”).

    This command uses curl to set StrongDM as a proxy and perform an HTTP GET request to access Vault secrets:

    curl --proxy "127.0.0.1:65230" -X GET https://{SUBDOMAIN}.sdm.network/v1/path/secret

    Example:

    curl --proxy "127.0.0.1:65230" -X GET https://vault.example.sdm.network/v1/path/secret

    In return, you’ll get a JSON payload similar to the following:

    {
  "request_id": "eebdb123-1a2b-01a1-1234-1abc2345d678",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 2764800,
  "data":{
     "password":"Thisisasecurepassword2021!",
     "username":"sdm"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

  • For HTTP Custom Auth without proxy, use the following command, being sure to replace {SUBDOMAIN} with your desired subdomain in StrongDM (e.g., “vault”).

    This command uses curl to perform an HTTP GET request to access Vault secrets.

    curl -X GET https://{SUBDOMAIN}.sdm.network/v1/path/secret

    Example:

    curl -X GET https://vault.example.sdm.network/v1/path/secret

    In return, you’ll get a JSON payload similar to the following:

    {
  "request_id": "eebdb123-1a2b-01a1-1234-1abc2345d678",
  "lease_id": "",
  "renewable": false,

  "lease_duration": 2764800,
  "data":{
     "password":"Thisisasecurepassword2021!",
     "username":"sdm"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Vault CLI with HTTP Custom Auth

  1. To use the Vault CLI with HTTP Custom Auth, use the following command to set the path to your Vault secrets, being sure to replace {SUBDOMAIN} with your desired subdomain in StrongDM (e.g., “vault”):
export VAULT_ADDR="https://{SUBDOMAIN}.sdm.network"

Example:

export VAULT_ADDR="https://vault.example.sdm.network"
  1. Run vault status to verify that it works:
vault status

The status check will show a response similar to the following:

Key               Value
---               ---
Seal Type         shamir
Initialized       true
Sealed            false
Total Shares      5
Threshold         3
Version           1.7.1
Storage Type      consul
Cluster Name      vault-cluster-12a345bc
Cluster ID        1a2345c6-78d9-ef12-3gh4-5abc12345d6e
HA Enabled        true
HA Cluster        example-cluster
HA Mode           active
Active Since      2021-05-04T18:53:45.8603209687

Vault CLI with HTTP

  1. In the Vault CLI, use the following command to set the path to your Vault secrets, being sure to replace {SUBDOMAIN} with your desired subdomain in StrongDM (e.g., “vault”):
export VAULT_ADDR="https://{SUBDOMAIN}.sdm.network"

Example:

export VAULT_ADDR="https://vault.example.sdm.network"
  1. Log in to Vault, using your Vault token:
vault login token={TOKEN}

Example:

vault login token=12aab3cd-e456-f7ga-h8ij-912345678912
  1. Run vault status to verify that it works:
vault status

The status check will show a response similar to the following:

Key               Value
---               ---
Seal Type         shamir
Initialized       true
Sealed            false
Total Shares      5
Threshold         3
Version           1.7.1
Storage Type      consul
Cluster Name      vault-cluster-12a345bc
Cluster ID        1a2345c6-78d9-ef12-3gh4-5abc12345d6e
HA Enabled        true
HA Cluster        example-cluster
HA Mode           active
Active Since      2021-05-04T18:53:45.8603209687

Next Steps

Now that configuration is complete, you can run all Vault commands and management through StrongDM.