# HashiCorp Vault 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](https://docs.strongdm.com/admin/access/secret-stores). This guide will show you 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: * Automatic rotation of the SecretID (that is, `VAULT_SECRET_ID` environment variable) * Any other authentication method besides token-based authentication, TLS certificate-based authentication, AppRole authentication, AWS EC2-based authentication, or AWS IAM-based authentication * Any secrets engine that does not conform to the same URL structure as KV 1 or KV 2 (for example, key management or SSH certificate signing) * Writing credentials to Vault (that is, credentials must already be in Vault for StrongDM to read them) ### Requirements Before you begin, ensure that you have the following: * Running Vault server * Credentials to some of your resources, stored in the Vault instance * Correct paths to the credentials ### Authentication to Vault This section provides important configuration information for allowing StrongDM nodes to authenticate with Vault. StrongDM supports the following authentication methods to enable your relay to authenticate with Vault: token-based authentication, TLS certificate-based authentication, AppRole authentication, AWS EC2-based authentication, and AWS IAM-based authentication. For more information on these methods, please see [HashiCorp's Vault authentication documentation](https://www.vaultproject.io/docs/auth/). {% hint style="warning" %} Although token-based authentication for Vault secret stores may be a good resource for testing and quick implementation, token-based authentication is not recommended for production environments. {% endhint %} The following are some common environment variables for all Vault clients: * `VAULT_TOKEN_TTL`: Allows you to override the token lease time when renewing the token. If set as a numeric value (for example, `600`), it is treated as seconds. Otherwise, it is parsed as a Go duration string (for example, `10m`, `1h`). * `VAULT_TOKEN_RENEW_BEHAVIOR`: Supported values are: * `STOP_ON_ERROR`: If the token renewal fails, it will stop renewal process, and login will be attempted on the next healthcheck attempt. * `DISABLED`: Disable token renewal. It will login again after the current token is expired. #### 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 `` with the actual value: ``` VAULT_TOKEN= ``` 4. 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: ```shell docker run --restart=always [--net=host] --name sdm-relay -e SDM_RELAY_TOKEN= -p 5000:5000 -d public.ecr.aws/strongdm/relay ``` You need to add the VAULT\_TOKEN to the previous command, and replace `` and `` with the correct values. ```shell docker run --restart=always [--net=host] --name sdm-relay -e VAULT_TOKEN= -e SDM_RELAY_TOKEN= -p 5000:5000 -d public.ecr.aws/strongdm/relay ``` **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: ```shell name: VAULT_TOKEN valueFrom: secretKeyRef: name: vault-secret key: token ``` #### TLS certificate-based authentication For TLS certificate-based authentication, follow the Vault documentation regarding [certificate authentication with Vault](https://www.vaultproject.io/docs/auth/cert). 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 (for example, `600`) or amount of minutes or hours (for example, `10m` or `1h`) 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 auth method, which is the `token_ttl` setting that is configured when AppRole is enabled in Vault. 3. Open the environment file for editing. The default location is `/etc/sysconfig/sdm-proxy` for gateways and relays, or `/etc/sysconfig/sdm-worker` for proxy clusters. 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= VAULT_SECRET_ID= VAULT_TOKEN_TTL= ``` 5. Restart the service. If your system uses systemd, the command is `sudo systemctl restart sdm-proxy` for gateways and relays, or `sudo systemctl restart sdm-worker` for proxy clusters. #### AWS authentication By default, the relay will use your EC2 instance configuration to authenticate with Vault. For the EC2 authentication method, the instance's AMI ID will be used as a Vault role identifier. For the IAM authentication method, the role that is bound to given instance will be used as a Vault role. You can adjust IAM authentication by specifying environment variables. Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` to specify a custom service account with a different role, or set `AWS_SHARED_CREDENTIALS_FILE` to point to the AWS configuration file created with the `aws configure` command. AWS roles are mapped to Vault roles. For more information, please see the Vault documentation regarding the AWS auth method. ### 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 **Settings** > **Secrets Management** and to the **Secret Stores** tab. 2. Click the **add secret store** button. That opens the **Add Secret Store** form where the secret store properties are set. ![](https://4180056444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF7eka9SH5TT8nJm2ZfWj%2Fuploads%2Fgit-blob-7b0b511fc1f76df747c9d4ed3418d62a5ff068dd%2Fsecretstores-vault.png?alt=media) 3. For **Display Name (Required)**, enter a name for the secret store. 4. For **Secret Store Type (Required)**, select either **HashiCorp Vault**, **HashiCorp Vault (AWS EC2 auth)** (AWS EC2-based authentication), **HashiCorp Vault (AWS IAM auth)** (AWS IAM-based authentication), **HashiCorp Vault (AppRole)** (AppRole authentication), or **HashiCorp Vault (Token)** (token-based authentication). 5. Enter the appropriate authentication information for the selected Secret Store type. For **HashiCorp Vault** (certificate-based authentication), enter the paths to the certificates stored on your relay server. For all the other types, enter the server address (for example, `https://vault.example.com:1235`). 6. If you have a secret inside a Vault Enterprise namespace, you can use the **Namespace (Optional)** 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: * Set an empty string and use the secret path `namespace/mysecret?key=username`. * Set `namespace/` and use the secret path `mysecret?key=username`. {% hint style="info" %} If you try to use a token from `namespace1/`, for example, but you configure the secret store to use `namespace2/`, the secret store healthcheck will fail. {% endhint %} 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](https://docs.strongdm.com/admin/resources/add-resources-secret-stores) 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. {% hint style="info" %} 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, (for example, `example-secret?key=username`). Note that Vault will even allow the direct import of JSON (for example, `vault kv put secret/foo @data.json`). 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`. {% endhint %} 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 shows 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 Follow the instructions for one of the following different ways to set up Vault to use the StrongDM HTTP proxy: * [HTTP](#http) * [HTTP Custom Auth](#http-custom-auth) * [CLI for Vault HTTP API](#cli-for-vault-http-api) * [Vault CLI with HTTP Custom Auth](#vault-cli-with-http-custom-auth) * [Vault CLI with HTTP](#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 Resource**, and then set the properties. 3. For **Display Name**, enter a name for the website. 4. For **Resource Type**, select **HTTP**. 5. For **Base URL**, add your full Vault address, including port (for example, `https://vault.example.com:8200`). 6. For **HTTP Subdomain**, enter the subdomain that you want to use in StrongDM (for example, `vault`). 7. Click **Create**. **HTTP Custom Auth** 1. In the StrongDM Admin UI, click **Websites**. 2. Click **Add Resource**, and then set the properties. 3. For **Display Name**, enter a name for the website. 4. For **Resource Type**, select **HTTP Custom Auth**. 5. For **Base URL**, add your full Vault address, including port (for example, `https://vault.example.com:8200`). 6. For **HTTP Subdomain**, enter the subdomain that you want to use in StrongDM (for example, `vault`). 7. For **Authorization Header (path)**, enter the **token** for Vault that you want to use, in the format `Bearer ` (for example, `Bearer 12aab3cd-e456-f7ga-h8ij-912345678912`). 8. Click **Create**. **CLI for Vault HTTP API** **HTTP with a proxy** For HTTP with a proxy, use the following command. Replace with your actual Vault token and with your desired subdomain in StrongDM (for example, `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. ```bash curl --proxy "127.0.0.1:65230" -H "Authorization: Bearer " -X GET https://.sdm.network/v1/path/secret ``` Example: ```bash 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: ```json { "request_id": "eebdb123-1a2b-01a1-1234-1abc2345d678", "lease_id": "", "renewable": false, "lease_duration": 2764800, "data":{ "password":"Thisisasecurepassword!", "username":"sdm" }, "wrap_info": null, "warnings": null, "auth": null } ``` **HTTP without a proxy** For HTTP without a proxy, use the following command. Replace with your actual Vault token and with your desired subdomain in StrongDM (for example, `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. ```bash curl -H "Authorization: Bearer " -X GET https://.sdm.network/v1/path/secret ``` Example: ```bash 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: ```json { "request_id": "eebdb123-1a2b-01a1-1234-1abc2345d678", "lease_id": "", "renewable": false, "lease_duration": 2764800, "data":{ "password":"Thisisasecurepassword!", "username":"sdm" }, "wrap_info": null, "warnings": null, "auth": null } ``` **HTTP Custom Auth with a proxy** For HTTP Custom Auth with a proxy, use the following command. Replace with your desired subdomain in StrongDM (for example, `vault`). This command uses curl to set StrongDM as a proxy and perform an HTTP GET request to access Vault secrets. ```bash curl --proxy "127.0.0.1:65230" -X GET https://.sdm.network/v1/path/secret ``` Example: ```bash 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: ```json { "request_id": "eebdb123-1a2b-01a1-1234-1abc2345d678", "lease_id": "", "renewable": false, "lease_duration": 2764800, "data":{ "password":"Thisisasecurepassword!", "username":"sdm" }, "wrap_info": null, "warnings": null, "auth": null } ``` **HTTP Custom Auth without proxy** For HTTP Custom Auth without proxy, use the following command. Replace with your desired subdomain in StrongDM (for example, `vault`). This command uses curl to perform an HTTP GET request to access Vault secrets. ```bash curl -X GET https://.sdm.network/v1/path/secret ``` Example: ```bash curl -X GET https://vault.example.sdm.network/v1/path/secret ``` In return, you’ll get a JSON payload similar to the following: ```json { "request_id": "eebdb123-1a2b-01a1-1234-1abc2345d678", "lease_id": "", "renewable": false, "lease_duration": 2764800, "data":{ "password":"Thisisasecurepassword!", "username":"sdm" }, "wrap_info": null, "warnings": null, "auth": null } ``` **Vault CLI with HTTP Custom Auth** To use the Vault CLI with HTTP Custom Auth, use the following command to set the path to your Vault secrets. Replace with your desired subdomain in StrongDM (for example, `vault`). ```bash export VAULT_ADDR="https://.sdm.network" ``` Example: ```bash export VAULT_ADDR="https://vault.example.sdm.network" ``` Then run `vault status` to verify that it works: ```bash 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 2024-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. Replace with your desired subdomain in StrongDM (for example, `vault`). ```bash export VAULT_ADDR="https://.sdm.network" ``` Example: ```bash export VAULT_ADDR="https://vault.example.sdm.network" ``` 2. Log in to Vault, using your Vault token: ```bash vault login token= ``` Example: ```bash vault login token=12aab3cd-e456-f7ga-h8ij-912345678912 ``` 3. Run `vault status` to verify that it works: ```bash 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 2024-05-04T18:53:45.8603209687 ``` #### Next steps Now that configuration is complete, you can run all Vault commands and management through StrongDM. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.strongdm.com/admin/access/secret-stores/hashicorp-vault.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.