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 vlt CLI and HCP Vault Secrets API.

Prerequisites

An existing HCP account
Completed the previous HCP Vault Secrets tutorials
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 vlt CLI tool, or an API to interact with secrets.

Tip

The HCP Vault Secrets CLI includes a --help parameter. This parameter can be appended to the vlt command, and any sub-commands.

Review the available secrets.
```
$ vlt secrets list
Name      Latest Version  Created At
username  2               2023-05-24T12:22:18.395Z
```
The username secret was created 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 details about the username secret.

$ vlt secrets get username
Name      Value         Latest Version  Created At
username  ************  2               2023-05-24T12:22:18.395Z

By default, the secret value is redacted.

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

$ vlt secrets get --format json username | jq
{
  "created_at": "2023-06-09T13:14:28.140Z",
  "created_by": {
    "email": "username@example.com",
    "name": "example",
    "type": "TYPE_USER"
  },
  "latest_version": "2",
  "name": "username"
}

Retrieve the username secret and inject the value into a process.
```
$ vlt run -- env | grep USERNAME
USERNAME=db-user
```
The run command runs a process while injecting all available secrets from a HCP Vault Secrets application as environment variables.
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 that can be retrieved from the HCP token API using the HCP service principal
The HCP organization id
The HCP project id

The organization ID and project ID can be retrieved using the vlt CLI. This information was collected as part of the vlt config init command.

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

$ vlt config
App Name: WebApplication
Project ID: ab35ef-d3f4-4fda-b245-s3asam3st
Organization ID: ab35ef-8d87-4443-a8a8-s3asam3st

Copy the Organization ID and store it in a environment variable.
```
$ export HCP_ORG_ID=ab35ef-8d87-4443-a8a8-s3asam3st
```
Copy the Project ID and store it in a environment variable.
```
$ export HCP_PROJ_ID=ab35ef-d3f4-4fda-b245-s3asam3st
```
Copy the App Name and store it in a environment variable.
```
$ export APP_NAME=WebApplication
```

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-06-13/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_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": "2023-05-24T12:04:14.279930Z",
      "updated_at": null,
      "created_by": {
        "name": "username",
        "type": "TYPE_USER",
        "email": "username@example.com"
      },
      "updated_by": null,
      "sync_integrations": []
    }
  ]
}

The WebApplication application was created during the Create a secret in HCP Vault Secrets tutorial.

Review the available secrets.

$ curl \
    --location "https://api.cloud.hashicorp.com/secrets/2023-06-13/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_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": "2023-05-24T12:34:11.138965Z",
        "created_by": {
          "name": "username",
          "type": "TYPE_USER",
          "email": "username@example.com"
        }
      },
      "created_at": "2023-05-24T12:22:18.395158Z",
      "latest_version": "2",
      "created_by": {
        "name": "username",
        "type": "TYPE_USER",
        "email": "username@example.com"
      },
      "sync_status": {}
    }
  ]
}

The username secret was created 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-06-13/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_ID/apps/$APP_NAME/open" \
    --request GET \
    --header "Authorization: Bearer $HCP_API_TOKEN" | jq

Example output:

{
  "secrets": [
    {
      "name": "username",
      "version": {
        "version": "2",
        "type": "kv",
        "created_at": "2023-12-11T18:10:45.464814Z",
        "value": "db-user",
        "created_by": {
          "name": "username",
          "type": "TYPE_USER",
          "email": "username@example.com"
        }
      },
      ...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 Vault Secrets CLI

HCP Vault Secrets with Terraform