1--- 2layout: "guides" 3page_title: "Secure Introduction of Vault Clients - Guides" 4sidebar_title: "Secure Introduction of Vault Clients" 5sidebar_current: "guides-identity-secure-intro" 6description: |- 7 This introductory guide walk through the mechanism of Vault clients to 8 authenticate with Vault. There are two approaches at a high-level: platform 9 integration, and trusted orchestrator. 10--- 11 12# Secure Introduction of Vault Clients 13 14A _secret_ is something that will elevate the risk if exposed to unauthorized 15entities and results in undesired consequences (e.g. unauthorized data access); 16therefore, only the ***trusted entities*** should have an access to your 17secrets. 18 19If you can securely get the first secret from an originator to a consumer, all 20subsequent secrets transmitted between this originator and consumer can be 21authenticated with the trust established by the successful distribution and user 22of that first secret. Getting the first secret to the consumer, is the ***secure 23introduction*** challenge. 24 25 26 27The Vault authentication process verifies the secret consumer's identity and 28then generate a **token** to associate with that identity. 29[Tokens](/docs/concepts/tokens.html) are the core method for authentication 30within Vault which means that the secret consumer must first acquire a valid 31token. 32 33 34## Challenge 35 36How does a secret consumer (an application or machine) prove that it is the 37legitimate recipient for a secret so that it can acquire a token? 38 39How can you avoid persisting raw token values during our secure 40introduction? 41 42## Secure Introduction Approach 43 44Vault's auth methods perform authentication of its client and assigning a set of 45policies which defines the permitted operations for the client. 46 47 48 49There are three basic approaches to securely authenticate a secret consumer: 50 51- [Platform Integration](#platform-integration) 52- [Trusted Orchestrator](#trusted-orchestrator) 53- [Vault Agent](#vault-agent) 54 55 56## Platform Integration 57 58In the **Platform Integration** model, Vault trusts the underlying platform 59(e.g. AliCloud, AWS, Azure, GCP) which assigns a token or cryptographic identity 60(such as IAM token, signed JWT) to virtual machine, container, or serverless 61function. 62 63Vault uses the provided identifier to verify the identity of the client by 64interacting with the underlying platform. After the client identity is verified, 65Vault returns a token to the client that is bound to their identity and policies 66that grant access to secrets. 67 68 69 70For example, suppose we have an application running on a virtual machine in AWS 71EC2. When that instance is started, an IAM token is provided via the machine 72local metadata URL. That IAM token is provided to Vault, as part of the AWS Auth 73Method, to login and authenticate the client. Vault uses that token to query the 74AWS API and verify the token validity and fetch additional metadata about the 75instance (Account ID, VPC ID, AMI, Region, etc). These properties are used to 76determine the identity of the client and to distinguish between different roles 77(e.g. a Web server versus an API server). 78 79Once validated and assigned to a role, Vault generates a token that is 80appropriately scoped and returns it to the client. All future requests from the 81client are made with the associated token, allowing Vault to efficiently 82authenticate the client and check for proper authorizations when consuming 83secrets. 84 85 86 87 88### Use Case 89 90When the client app is running on a VM hosted on a supported cloud platform, you 91can leverage the corresponding auth method to authenticate with Vault. 92 93### Reference Materials: 94 95- [AWS Auth Method](/docs/auth/aws.html) 96- [Azure Auth Method](/docs/auth/azure.html) 97- [GCP Auth Method](/docs/auth/gcp.html) 98 99 100## Trusted Orchestrator 101 102In the **Trusted Orchestrator** model, you have an _orchestrator_ which is 103already authenticated against Vault with privileged permissions. The 104orchestrator launches new applications and inject a mechanism they can use to 105authenticate (e.g. AppRole, PKI cert, token, etc) with Vault. 106 107 108 109For example, suppose [Terraform](https://www.terraform.io/) is being used as a 110trusted orchestrator. This means Terraform already has a Vault token, with 111enough capabilities to generate new tokens or create new mechanisms to 112authenticate such as an AppRole. Terraform can interact with platforms such as 113VMware to provision new virtual machines. VMware does not provide a 114cryptographic identity, so a platform integration isn't possible. Instead, 115Terraform can provision a new AppRole credential, and SSH into the new machine 116to inject the credentials. Terraform is creating the new credential in Vault, 117and making that credential available to the new resource. In this way, Terraform 118is acting as a trusted orchestrator and extending trust to the new machine. The 119new machine, or application running on it, can use the injected credentials to 120authenticate against Vault. 121 122 123 124 125### Use Case 126 127When you are using an orchestrator tool such as Chef to launch applications, 128this model can be applied regardless of where the applications are running. 129 130### Reference Materials: 131 132- [AppRole Auth Method](/docs/auth/approle.html) 133 - [AppRole Pull Authentication](/guides/identity/authentication.html) 134 - [AppRole with Terraform and Chef Demo](/guides/identity/approle-trusted-entities.html) 135- [TLS Certificates Auth Method](/docs/auth/cert.html) 136- [Token Auth Method](/docs/auth/token.html) 137 - [Cubbyhole Response Wrapping](/guides/secret-mgmt/cubbyhole.html) 138 139 140## Vault Agent 141 142Vault agent is a client daemon which automates the workflow of client login and 143token refresh. It can be used with either [platform 144integration](#platform-integration) or [trusted 145orchestrator](#trusted-orchestrator) approaches. 146 147#### Vault agent auto-auth: 148 149- Automatically authenticates to Vault for those [supported auth 150methods](/docs/agent/autoauth/methods/index.html) 151- Keeps token renewed (re-authenticates as needed) until the renewal is no 152longer allowed 153- Designed with robustness and fault tolerance 154 155 156 157To leverage this feature, run the vault binary in agent mode (`vault agent 158-config=<config_file>`) on the client. The agent configuration file must specify 159the auth method and [sink](/docs/agent/autoauth/sinks/index.html) locations 160where the token to be written. 161 162When the agent is started, it will attempt to acquire a Vault token using the 163auth method specified in the agent configuration file. On successful 164authentication, the resulting token is written to the sink locations. 165Optionally, this token can be response-wrapped or encrypted. Whenever the 166current token value changes, the agent writes to the sinks. If authentication 167fails, the agent waits for a while and then retry. 168 169The client can simply retrieve the token from the sink and connect to Vault 170using the token. This simplifies client integration since the Vault agent 171handles the login and token refresh logic. 172 173### Reference Materials: 174 175- [Streamline Secrets Management with Vault Agent and Vault 0.11](https://youtu.be/zDnIqSB4tyA) 176- [Vault Agent documentation](/docs/agent/index.html) 177- [Auto-Auth documentation](/docs/agent/autoauth/index.html) 178 179 180## Next steps 181 182When a [platform integration](#platform-integration) is available that should be 183preferred, as it is generally the simpler solution and works independent of the 184orchestration mechanism. For a [trusted orchestrator](#trusted-orchestrator), 185specific documentation for that orchestrator should be consulted on Vault 186integration. 187
