• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Try Cloud(opens in new tab)
  • Sign up
App Integration

Skip to main content
12 tutorials
  • Secure Introduction of Vault Clients
  • Use Consul Template and Envconsul with Vault
  • AppRole With Terraform & Chef
  • Java Application Demo
  • Transit Secrets Re-wrapping
  • Encrypting Data with Transform Secrets Engine
  • Using HashiCorp Vault C# Client with .NET Core
  • Using HashiCorp Vault Agent with .NET Core
  • Build Your Own Plugins
  • Vault GitHub Actions
  • Vault AWS Lambda Extension
  • Introduction to the Vault AWS Lambda Extension

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Tutorials
  4. App Integration
  5. Secure Introduction of Vault Clients

Secure Introduction of Vault Clients

  • 6min

  • VaultVault

To reduce risk, only trusted entities should have access to your secrets. Exposed secrets can result in undesired consequences such as unauthorized data access. If you can securely get the first secret from an originator to a consumer, all subsequent secrets transmitted between this originator and consumer can be authenticated with the trust established by the successful distribution.

Getting the first secret to the consumer, is the secure introduction challenge. How does a secret consumer, an application or machine, prove that it is the legitimate recipient for a secret so that it can acquire a token? How can you avoid persisting raw token values during your secure introduction?

Secure Introduction

The Vault authentication process verifies the secret consumer's identity and then generates a token to associate with that identity. Tokens are the core method for authentication within Vault which means that the secret consumer must first acquire a valid token.

Tokens must be maintained client side and upon expiration can be renewed. For short lived workflows, traditionally, tokens would be created with a lifetime that would match the average deploy time and left to expire, securing new tokens with each deployment.

Secure introduction approach

Vault's auth methods perform authentication of its client and assignment of policies which defines the permitted operations for the client.

Auth Method

There are three approaches to securely authenticate a secret consumer.

  • Platform Integration
  • Trusted Orchestrator
  • Vault Agent

Platform integration

In the Platform Integration model, Vault trusts the underlying platform (e.g. AliCloud, AWS, Azure, GCP) which assigns a token or cryptographic identity (such as IAM token, signed JWT) to virtual machine, container, or serverless function.

Vault uses the provided identifier to verify the identity of the client by interacting with the underlying platform. After the client identity is verified, Vault returns a token to the client that is bound to their identity and policies that grant access to secrets.

Platform Integration

For example, suppose we have an application running on a virtual machine in AWS EC2. When that instance is started, an IAM token is provided via the machine local metadata URL. That IAM token is provided to Vault, as part of the AWS Auth Method, to login and authenticate the client. Vault uses that token to query the AWS API and verify the token validity and fetch additional metadata about the instance (Account ID, VPC ID, AMI, Region, etc). These properties are used to determine the identity of the client and to distinguish between different roles (e.g. a Web server versus an API server).

Once validated and assigned to a role, Vault generates a token that is appropriately scoped and returns it to the client. All future requests from the client are made with the associated token, allowing Vault to efficiently authenticate the client and check for proper authorizations when consuming secrets.

Vault AWS EC2 Authentication Flow

Use case

When the client app is running on a VM hosted on a supported cloud platform, you can leverage the corresponding auth method to authenticate with Vault.

Reference materials:

  • AWS Auth Method
  • Azure Auth Method
  • GCP Auth Method

Trusted orchestrator

In the Trusted Orchestrator model, you have an orchestrator which is already authenticated against Vault with privileged permissions. The orchestrator launches new applications and inject a mechanism they can use to authenticate (e.g. AppRole, PKI cert, token, etc) with Vault.

Trusted Orchestrator

For example, suppose Terraform is being used as a trusted orchestrator. This means Terraform already has a Vault token, with enough capabilities to generate new tokens or create new mechanisms to authenticate such as an AppRole. Terraform can interact with platforms such as VMware to provision new virtual machines. VMware does not provide a cryptographic identity, so a platform integration isn't possible. Instead, Terraform can provision a new AppRole credential, and SSH into the new machine to inject the credentials. Terraform is creating the new credential in Vault, and making that credential available to the new resource. In this way, Terraform is acting as a trusted orchestrator and extending trust to the new machine. The new machine, or application running on it, can use the injected credentials to authenticate against Vault.

AppRole auth method workflow

Use case

When you are using an orchestrator tool such as Chef to launch applications, this model can be applied regardless of where the applications are running.

Reference materials:

  • AppRole Auth Method
  • TLS Certificates Auth Method
  • Token Auth Method

Vault Agent

Vault Agent is a client daemon which automates the workflow of client login and token refresh. It can be used with either platform integration or trusted orchestrator approaches.

Vault agent auto-auth:

  • Automatically authenticates to Vault for those supported auth methods
  • Keeps token renewed (re-authenticates as needed) until the renewal is no longer allowed
  • Designed with robustness and fault tolerance
Vault Agent

To leverage this feature, run the vault binary in agent mode (vault agent -config=<config_file>) on the client. The agent configuration file must specify the auth method and sink locations where the token to be written.

When the agent is started, it will attempt to acquire a Vault token using the auth method specified in the agent configuration file. On successful authentication, the resulting token is written to the sink locations. Optionally, this token can be response-wrapped or encrypted. Whenever the current token value changes, the agent writes to the sinks. If authentication fails, the agent waits for a while and then retries.

The client can simply retrieve the token from the sink and connect to Vault using the token. This simplifies client integration since the Vault agent handles the login and token refresh logic.

Reference materials:

  • Blog post: Why Use the Vault Agent for Secrets Management?
  • Video: Streamline Secrets Management with Vault Agent and Vault 0.11
  • Vault Agent documentation
  • Auto-Auth documentation

Vault Agent tutorials:

  • Vault Agent with AWS
  • Vault Agent with Kubernetes
  • Vault Agent Caching
  • Vault Agent Templates
  • Vault Agent Windows Service
  • Read Secrets From Vault Using Vault Agent
  • Using HashiCorp Vault Agent with .NET Core

Next steps

Authentication methods are generally configured by an operator at initial configuration time. Most commonly, systems perform an authentication process automatically, though responsibility of carrying out the process is generally agreed as part of a handover, when multiple teams take responsibility of provisioning a system or deploying an application.

Help and reference

  • AppRole Auth Method
  • TLS Certificates Auth Method
  • Token Auth Method
  • How (and Why) to Use AppRole Correctly in HashiCorp Vault
 Back to Collection
 Next

On this page

  1. Secure Introduction of Vault Clients
  2. Secure introduction approach
  3. Platform integration
  4. Trusted orchestrator
  5. Vault Agent
  6. Next steps
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)