Retrieve a secret from HCP Vault Secrets

5min
|
HCP
Vault

In the previous tutorial, you created a secret and learned how to authenticate with HCP Vault Secrets.

In this tutorial, you will learn how to retrieve secrets using the HCP CLI and HCP Vault Secrets API.

Prerequisites

An existing HCP account
Completed the previous HCP Vault Secrets tutorials
HCP CLI
jq
curl (API only)
HCP service principal with HCP_CLIENT_ID and HCP_CLIENT_SECRET environment variables set

Applications, services, and workflows need to retrieve secrets so teams do not have to store secret information such as usernames and passwords, or API keys in source code.

HCP Vault Secrets provides the flexibility to use either the HCP CLI, or an API to interact with secrets.

Tip

The HCP CLI provides context aware help based on the command or subcommand in use.

Review the available secrets.
```
$ hcp vault-secrets secrets list
Secret Name   Latest Version   Created At
username      2                2024-06-11T13:02:55.482Z
```
You created he username secret during the Create a secret in HCP Vault Secrets tutorial.
The version was incremented to 2 by changing the username value from database-user to db-user.

Retrieve details about the username secret.

$ hcp vault-secrets secrets open username
Secret Name:    username
Latest Version: 2
Created At:     2024-06-11T13:02:55.482Z
Type:           kv
Value:          db-user

You can control the CLI output using the --format parameter. Use --format json to retrieve a secret in JSON format.

$ hcp vault-secrets secrets open username --format=json
{
  "created_at": "2024-06-11T13:02:55.482Z",
  "latest_version": 2,
  "name": "username",
  "static_version": {
    "created_at": "0001-01-01T00:00:00.000Z",
    "value": "db-user"
  },
  "type": "kv"
}

Retrieve the username secret and inject the value into a process.
```
$ hcp vault-secrets run env | grep USERNAME
USERNAME=db-user
```
The run command runs the env command injecting all available secrets from a HCP Vault Secrets application as environment variables.

Create a script named output.sh.

$ tee output.sh <<EOF
#!/bin/bash
echo \$USERNAME
EOF

Use the run subcommand to run output.sh and show the secret value stored in HCP Vault Secrets.
```
$ hcp vault-secrets run bash ./output.sh
db-user
```
Refer to the HCP Vault Secrets documentation for a list of all available CLI commands.

Note

Refer to the HCP Vault Secrets API documentation for a complete list of all endpoints and parameters.

The HCP Vault Secrets API requires additional information to complete API requests.

A token from the HCP token API using the HCP service principal
The HCP organization id
The HCP project id

You can retrieve the organization ID and project ID using the HCP CLI.

Retrieve the HCP organization ID and project ID selected during the vlt init process.

$ hcp profile display
name            = "default"
organization_id = "ab35ef-8d87-4443-a8a8-s3asam3st"
project_id      = "ab35ef-d3f4-4fda-b245-s3asam3st"

vault-secrets {
  app = "WebApplication"
}

Store the organization_id in a environment variable.

$ export HCP_ORG_ID=$(hcp profile display --format=json | jq -r .OrganizationID)

Store the project_id in a environment variable.

$ export HCP_PROJECT_ID=$(hcp profile display --format=json | jq -r .ProjectID)

Store the app name in a environment variable.

$ export APP_NAME=$(hcp profile display --format=json | jq -r .VaultSecrets.AppName)

Request a token using curl and store the token in a environment variable.

$ HCP_API_TOKEN=$(curl https://auth.idp.hashicorp.com/oauth/token \
     --data grant_type=client_credentials \
     --data client_id="$HCP_CLIENT_ID" \
     --data client_secret="$HCP_CLIENT_SECRET" \
     --data audience="https://api.hashicorp.cloud" | jq -r .access_token)

Review the available applications.

$ curl \
    --location "https://api.cloud.hashicorp.com/secrets/2023-11-28/organizations/$HCP_ORG_ID/projects/$HCP_PROJECT_ID/apps" \
    --request GET \
    --header "Authorization: Bearer $HCP_API_TOKEN" | jq

Example output:

{
  "apps": [
    {
      "location": {
        "organization_id": "ab35ef-8d87-4443-a8a8-s3asam3st",
        "project_id": "ab35ef-d3f4-4fda-b245-s3asam3st",
        "region": null
      },
      "name": "WebApplication",
      "description": "",
      "created_at": "2024-06-10T19:48:05.776171Z",
      "updated_at": null,
      "created_by": {
        "name": "Example Name",
        "type": "TYPE_USER",
        "email": "example.name@example.com"
      },
      "updated_by": null,
      "sync_integrations": [],
      "secret_count": 1
    }
  ]
}

You created the WebApplication app during the Create a secret in HCP Vault Secrets tutorial.

Review the available secrets.

$ curl \
    --location "https://api.cloud.hashicorp.com/secrets/2023-11-28/organizations/$HCP_ORG_ID/projects/$HCP_PROJECT_ID/apps/$APP_NAME/secrets" \
    --request GET \
    --header "Authorization: Bearer $HCP_API_TOKEN" | jq

Example output:

 {
  "secrets": [
    {
      "name": "username",
      "version": {
        "version": "2",
        "type": "kv",
        "created_at": "2024-06-11T13:11:29.666377Z",
        "created_by": {
          "name": "Example Name",
          "type": "TYPE_USER",
          "email": "example.name@example.com"
        }
      },
      "created_at": "2024-06-11T13:02:55.482028Z",
      "latest_version": "2",
      "created_by": {
        "name": "Example Name",
        "type": "TYPE_USER",
        "email": "example.name@example.com"
      },
      "sync_status": {}
    }
  ]
}

You created the username secret during the Create a secret in HCP Vault Secrets tutorial.

The version was incremented to version 2 when you changed the username value from database-user to db-user.

Retrieve the username secret and display the value using the OpenAppSecrets API.

$ curl \
    --location "https://api.cloud.hashicorp.com/secrets/2023-11-28/organizations/$HCP_ORG_ID/projects/$HCP_PROJECT_ID/apps/$APP_NAME/secrets:open" \
    --request GET \
    --header "Authorization: Bearer $HCP_API_TOKEN" | jq

Example output:

{
  "secrets": [
    {
      "name": "username",
      "version": {
        "version": "2",
        "type": "kv",
        "created_at": "2024-06-11T13:11:29.666377Z",
        "value": "db-user",
        "created_by": {
          "name": "Example Name",
          "type": "TYPE_USER",
          "email": "example.name@example.com"
        },
        "created_by_id": "d4b1306d-c16b-47ed-a42b-afd5e8fd5bc8"
      },
      "created_at": "2024-06-11T13:02:55.482028Z",
      "latest_version": "2",
      ...snip...
  ]
}

The username secret value db-user is displayed.

Next steps

In this tutorial you learned how to retrieve a secret using the HCP Vault Secrets CLI, and API.

You can learn more about supported integrations in the HCP Vault Secrets documentation

Install HCP CLI for Vault Secrets

HCP Vault Secrets with Terraform