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
7.7 KiB
| layout | page_title | sidebar_title | sidebar_current | description |
|---|---|---|---|---|
| guides | Secure Introduction of Vault Clients - Guides | Secure Introduction of Vault Clients | guides-identity-secure-intro | 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 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
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:
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 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:
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
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 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
- Vault Agent documentation
- Auto-Auth documentation
Next steps
When a 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, specific documentation for that orchestrator should be consulted on Vault integration.