a3dfde5cec
* conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
187 lines
7.7 KiB
Markdown
187 lines
7.7 KiB
Markdown
---
|
|
layout: "guides"
|
|
page_title: "Secure Introduction of Vault Clients - Guides"
|
|
sidebar_title: "Secure Introduction of Vault Clients"
|
|
sidebar_current: "guides-identity-secure-intro"
|
|
description: |-
|
|
This introductory guide walk through the mechanism of Vault clients to
|
|
authenticate with Vault. There are two approaches at a high-level: platform
|
|
integration, and trusted orchestrator.
|
|
---
|
|
|
|
# Secure Introduction of Vault Clients
|
|
|
|
A _secret_ is something that will elevate the risk if exposed to unauthorized
|
|
entities and results in undesired consequences (e.g. unauthorized data access);
|
|
therefore, only the ***trusted entities*** should have an access to your
|
|
secrets.
|
|
|
|
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 and user
|
|
of that first secret. Getting the first secret to the consumer, is the ***secure
|
|
introduction*** challenge.
|
|
|
|
|
|
|
|
The Vault authentication process verifies the secret consumer's identity and
|
|
then generate a **token** to associate with that identity.
|
|
[Tokens](/docs/concepts/tokens.html) are the core method for authentication
|
|
within Vault which means that the secret consumer must first acquire a valid
|
|
token.
|
|
|
|
|
|
## 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 our secure
|
|
introduction?
|
|
|
|
## Secure Introduction Approach
|
|
|
|
Vault's auth methods perform authentication of its client and assigning a set of
|
|
policies which defines the permitted operations for the client.
|
|
|
|
|
|
|
|
There are three basic approaches to securely authenticate a secret consumer:
|
|
|
|
- [Platform Integration](#platform-integration)
|
|
- [Trusted Orchestrator](#trusted-orchestrator)
|
|
- [Vault Agent](#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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### 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](/docs/auth/aws.html)
|
|
- [Azure Auth Method](/docs/auth/azure.html)
|
|
- [GCP Auth Method](/docs/auth/gcp.html)
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
For example, suppose [Terraform](https://www.terraform.io/) 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.
|
|
|
|
|
|
|
|
|
|
### 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](/docs/auth/approle.html)
|
|
- [AppRole Pull Authentication](/guides/identity/authentication.html)
|
|
- [AppRole with Terraform and Chef Demo](/guides/identity/approle-trusted-entities.html)
|
|
- [TLS Certificates Auth Method](/docs/auth/cert.html)
|
|
- [Token Auth Method](/docs/auth/token.html)
|
|
- [Cubbyhole Response Wrapping](/guides/secret-mgmt/cubbyhole.html)
|
|
|
|
|
|
## 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](#platform-integration) or [trusted
|
|
orchestrator](#trusted-orchestrator) approaches.
|
|
|
|
#### Vault agent auto-auth:
|
|
|
|
- Automatically authenticates to Vault for those [supported auth
|
|
methods](/docs/agent/autoauth/methods/index.html)
|
|
- Keeps token renewed (re-authenticates as needed) until the renewal is no
|
|
longer allowed
|
|
- Designed with robustness and fault tolerance
|
|
|
|
|
|
|
|
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](/docs/agent/autoauth/sinks/index.html) 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 retry.
|
|
|
|
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:
|
|
|
|
- [Streamline Secrets Management with Vault Agent and Vault 0.11](https://youtu.be/zDnIqSB4tyA)
|
|
- [Vault Agent documentation](/docs/agent/index.html)
|
|
- [Auto-Auth documentation](/docs/agent/autoauth/index.html)
|
|
|
|
|
|
## Next steps
|
|
|
|
When a [platform integration](#platform-integration) is available that should be
|
|
preferred, as it is generally the simpler solution and works independent of the
|
|
orchestration mechanism. For a [trusted orchestrator](#trusted-orchestrator),
|
|
specific documentation for that orchestrator should be consulted on Vault
|
|
integration.
|