Authenticating to Hashicorp Vault using GCE Signed Metadata

Tuesday, September 19, 2017

Applications often require access to small pieces of sensitive data at build or run time, referred to as secrets. Secrets are generally more sensitive than other environment variables or parts of your repository as they may grant access to additional data, such as user information.

HashiCorp Vault is a popular open source tool for secret management, which allows a developer to store, manage and control access to tokens, passwords, certificates, API keys and other secrets. Vault has authentication backends, which allow developers to use many kinds of identities to access Vault, including tokens, or usernames and passwords.

Today, we’re announcing a new Google Compute Engine signed metadata authentication backend for Vault. This allows a developer to use an existing running instance to authenticate directly to Vault, using a JWT of this instance’s signed metadata as its identity. Learn more about the latest release of Vault.

The following example shows how a user can enable and configure the GCP auth backend and then authenticate an instance with Vault. See the docs to learn more.

In the following example, an admin mounts the backend at auth/gcp and adds:
  • Credentials that the backend can use to verify the instance (requiring some read-only permissions)
  • A Vault-specific role (roles determine what Vault secrets the authenticating GCE VM instance can access, and can restrict login to a set of instances by zone or region, instance group, or GCP labels)
# Mount the backend at ‘auth/gcp’.
$ vault auth-enable ‘gcp’

# Add configuration. This can include credentials Vault will 
# use to make calls to GCP APIs to verify authenticating instances. 
$ vault write auth/gcp/config credentials=@path/to/creds.json

# Add configuration. This can include credentials Vault will 
# use to make calls to GCP APIs to verify authenticating instances. 
$ vault write auth/gcp/role/my-gce-role \
type='gce' \
policies=’dev,prod’ \
project_id=”project-123456” \
instance_group=”my-instance-group” \
labels=”foo:bar,prod:true,...” \

Then, a Compute Engine instance can authenticate to the Vault server using the following script:

#! /bin/bash

# Subtitute real vault address or env variable.

# Substitute another service account for the VM instance or use the
# built-in default.

# The instance will attempt login under this role.

# Generate a metadata identity token JWT with the expected audience.
# The GCP backend expect a JWT 'aud' claim ending in “vault/$ROLE”.
TOKEN="$(curl -H "Metadata-Flavor: Google" \

# Attempt login against VAULT. 
# Using API calls:

cat > payload.json <<-END 
  "role": "$ROLE", 
  "jwt": "$TOKEN" 

$ RESP="$(curl \
    --request POST \
    --data @payload.json \

# OR

# Use CL vault tool if downloaded
vault write auth/gcp/login role=”$ROLE" jwt="$TOKEN" > response

# Get auth token from JSON
# response (response) and get
# your secrets from Vault!
# ...

A few weeks ago, we also announced a Google Cloud Platform IAM authentication backend for HashiCorp Vault, allowing authentication using an existing IAM service account identity. For further guidance on using HashiCorp Vault with Google Cloud, take a look at today’s Google Cloud blog post.

By Emily Ye, Software Engineer