1--- 2layout: "docs" 3page_title: "AWS - Auth Methods" 4sidebar_title: "AWS" 5sidebar_current: "docs-auth-aws" 6description: |- 7 The aws auth method allows automated authentication of AWS entities. 8--- 9 10# AWS Auth Method 11 12The `aws` auth method provides an automated mechanism to retrieve a Vault token 13for IAM principals and AWS EC2 instances. Unlike most Vault auth methods, this 14method does not require manual first-deploying, or provisioning 15security-sensitive credentials (tokens, username/password, client certificates, 16etc), by operators under many circumstances. 17 18## Authentication Workflow 19 20There are two authentication types present in the aws auth method: `iam` and 21`ec2`. 22 23With the `iam` method, a special AWS request signed with AWS IAM credentials is 24used for authentication. The IAM credentials are automatically supplied to AWS 25instances in IAM instance profiles, Lambda functions, and others, and it is 26this information already provided by AWS which Vault can use to authenticate 27clients. 28 29With the `ec2` method, AWS is treated as a Trusted Third Party and 30cryptographically signed dynamic metadata information that uniquely represents 31each EC2 instance is used for authentication. This metadata information is 32automatically supplied by AWS to all EC2 instances. 33 34Based on how you attempt to authenticate, Vault will determine if you are 35attempting to use the `iam` or `ec2` type. Each has a different authentication 36workflow, and each can solve different use cases. 37 38Note: The `ec2` method was implemented before the primitives to implement the 39`iam` method were supported by AWS. The `iam` method is the recommended approach 40as it is more flexible and aligns with best practices to perform access 41control and authentication. See the section on comparing the two auth methods 42below for more information. 43 44### IAM auth method 45 46The AWS STS API includes a method, 47[`sts:GetCallerIdentity`](http://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html), 48which allows you to validate the identity of a client. The client signs a 49`GetCallerIdentity` query using the [AWS Signature v4 50algorithm](http://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) and 51submits 4 pieces of information to the Vault server to recreate a valid signed 52request: the request URL, the request body, the request headers, and the 53request method, as the AWS signature is computed over those fields. The Vault 54server then reconstructs the query and forwards it on to the AWS STS service 55and validates the result back. Clients don't need network-level access to talk 56to the AWS STS API endpoint; they merely need access to the credentials to sign 57the request. However, it means that the Vault server does need network-level 58access to send requests to the STS endpoint. 59 60Importantly, the credentials used to sign the GetCallerIdentity request can 61come from the EC2 instance metadata service for an EC2 instance, or from the 62AWS environment variables in an AWS Lambda function execution, which obviates 63the need for an operator to manually provision some sort of identity material 64first. However, the credentials can, in principle, come from anywhere, not 65just from the locations AWS has provided for you. 66 67Each signed AWS request includes the current timestamp to mitigate the risk of 68replay attacks. In addition, Vault allows you to require an additional header, 69`X-Vault-AWS-IAM-Server-ID`, to be present to mitigate against different types 70of replay attacks (such as a signed `GetCallerIdentity` request stolen from a 71dev Vault instance and used to authenticate to a prod Vault instance). Vault 72further requires that this header be one of the headers included in the AWS 73signature and relies upon AWS to authenticate that signature. 74 75While AWS API endpoints support both signed GET and POST requests, for 76simplicity, the aws auth method supports only POST requests. It also does not 77support `presigned` requests, i.e., requests with `X-Amz-Credential`, 78`X-Amz-Signature`, and `X-Amz-SignedHeaders` GET query parameters containing 79the authenticating information. 80 81It's also important to note that Amazon does NOT appear to include any sort of 82authorization around calls to `GetCallerIdentity`. For example, if you have an 83IAM policy on your credential that requires all access to be MFA authenticated, 84non-MFA authenticated credentials (i.e., raw credentials, not those retrieved 85by calling `GetSessionToken` and supplying an MFA code) will still be able to 86authenticate to Vault using this method. It does not appear possible to enforce 87an IAM principal to be MFA authenticated while authenticating to Vault. 88 89### EC2 auth method 90 91Amazon EC2 instances have access to metadata which describes the instance. The 92Vault EC2 auth method leverages the components of this metadata to authenticate 93and distribute an initial Vault token to an EC2 instance. The data flow (which 94is also represented in the graphic below) is as follows: 95 96[![Vault AWS EC2 Authentication Flow](/img/vault-aws-ec2-auth-flow.png)](/img/vault-aws-ec2-auth-flow.png) 97 981. An AWS EC2 instance fetches its [AWS Instance Identity Document][aws-iid] 99from the [EC2 Metadata Service][aws-ec2-mds]. In addition to data itself, AWS 100also provides the PKCS#7 signature of the data, and publishes the public keys 101(by region) which can be used to verify the signature. 102 1031. The AWS EC2 instance makes a request to Vault with the PKCS#7 signature. 104The PKCS#7 signature contains the Instance Identity Document within itself. 105 1061. Vault verifies the signature on the PKCS#7 document, ensuring the information 107is certified accurate by AWS. This process validates both the validity and 108integrity of the document data. As an added security measure, Vault verifies 109that the instance is currently running using the public EC2 API endpoint. 110 1111. Provided all steps are successful, Vault returns the initial Vault token to 112the EC2 instance. This token is mapped to any configured policies based on the 113instance metadata. 114 115[aws-iid]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html 116[aws-ec2-mds]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html 117 118There are various modifications to this workflow that provide more or less 119security, as detailed later in this documentation. 120 121## Authorization Workflow 122 123The basic mechanism of operation is per-role. Roles are registered in the 124method and associated with a specific authentication type that cannot be 125changed once the role has been created. Roles can also be associated with 126various optional restrictions, such as the set of allowed policies and max TTLs 127on the generated tokens. Each role can be specified with the constraints that 128are to be met during the login. Many of these constraints accept lists of 129required values. For any constraint which accepts a list of values, that 130constraint will be considered satisfied if any one of the values is matched 131during the login process. For example, one such constraint that is 132supported is to bind against a list of AMI IDs. A role which is bound to a 133specific list of AMIs can only be used for login by EC2 instances that are 134deployed to one of the AMIs that the role is bound to. 135 136The iam auth method allows you to specify bound IAM principal ARNs. 137Clients authenticating to Vault must have an ARN that matches one of the ARNs bound to 138the role they are attempting to login to. The bound ARN allows specifying a 139wildcard at the end of the bound ARN. For example, if the bound ARN were 140`arn:aws:iam::123456789012:*` it would allow any principal in AWS account 141123456789012 to login to it. Similarly, if it were 142`arn:aws:iam::123456789012:role/*` it would allow any IAM role in the AWS 143account to login to it. If you wish to specify a wildcard, you must give Vault 144`iam:GetUser` and `iam:GetRole` permissions to properly resolve the full user 145path. 146 147In general, role bindings that are specific to an EC2 instance are only checked 148when the ec2 auth method is used to login, while bindings specific to IAM 149principals are only checked when the iam auth method is used to login. However, 150the iam method includes the ability for you to "infer" an EC2 instance ID from 151the authenticated client and apply many of the bindings that would otherwise 152only apply specifically to EC2 instances. 153 154In many cases, an organization will use a "seed AMI" that is specialized after 155bootup by configuration management or similar processes. For this reason, a 156role entry in the method can also be associated with a "role tag" when using 157the ec2 auth type. These tags 158are generated by the method and are placed as the value of a tag with the 159given key on the EC2 instance. The role tag can be used to further restrict the 160parameters set on the role, but cannot be used to grant additional privileges. 161If a role with an AMI bind constraint has "role tag" enabled on the role, and 162the EC2 instance performing login does not have an expected tag on it, or if the 163tag on the instance is deleted for some reason, authentication fails. 164 165The role tags can be generated at will by an operator with appropriate API 166access. They are HMAC-signed by a per-role key stored within the method, allowing 167the method to verify the authenticity of a found role tag and ensure that it has 168not been tampered with. There is also a mechanism to blacklist role tags if one 169has been found to be distributed outside of its intended set of machines. 170 171## IAM Authentication Inferences 172 173With the iam auth method, normally Vault will see the IAM principal that 174authenticated, either the IAM user or role. However, when you have an EC2 175instance in an IAM instance profile, Vault can actually see the instance ID of 176the instance and can "infer" that it's an EC2 instance. However, there are 177important security caveats to be aware of before configuring Vault to make that 178inference. 179 180Each AWS IAM role has a "trust policy" which specifies which entities are 181trusted to call 182[`sts:AssumeRole`](http://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) 183on the role and retrieve credentials that can be used to authenticate with that 184role. When AssumeRole is called, a parameter called RoleSessionName is passed 185in, which is chosen arbitrarily by the entity which calls AssumeRole. If you 186have a role with an ARN `arn:aws:iam::123456789012:role/MyRole`, then the 187credentials returned by calling AssumeRole on that role will be 188`arn:aws:sts::123456789012:assumed-role/MyRole/RoleSessionName` where 189RoleSessionName is the session name in the AssumeRole API call. It is this 190latter value which Vault actually sees. 191 192When you have an EC2 instance in an instance profile, the corresponding role's 193trust policy specifies that the principal `"Service": "ec2.amazonaws.com"` is 194trusted to call AssumeRole. When this is configured, EC2 calls AssumeRole on 195behalf of your instance, with a RoleSessionName corresponding to the 196instance's instance ID. Thus, it is possible for Vault to extract the instance 197ID out of the value it sees when an EC2 instance in an instance profile 198authenticates to Vault with the iam auth method. This is known as 199"inferencing." Vault can be configured, on a role-by-role basis, to infer that a 200caller is an EC2 instance and, if so, apply further bindings that apply 201specifically to EC2 instances -- most of the bindings available to the ec2 202auth method. 203 204However, it is very important to note that if any entity other than an AWS 205service is permitted to call AssumeRole on your role, then that entity can 206simply pass in your instance's instance ID and spoof your instance to Vault. 207This also means that anybody who is able to modify your role's trust policy 208(e.g., via 209[`iam:UpdateAssumeRolePolicy`](http://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateAssumeRolePolicy.html), 210then that person could also spoof your instances. If this is a concern but you 211would like to take advantage of inferencing, then you should tightly restrict 212who is able to call AssumeRole on the role, tightly restrict who is able to call 213UpdateAssumeRolePolicy on the role, and monitor CloudTrail logs for calls to 214AssumeRole and UpdateAssumeRolePolicy. All of these caveats apply equally to 215using the iam auth method without inferencing; the point is merely 216that Vault cannot offer an iron-clad guarantee about the inference and it is up 217to operators to determine, based on their own AWS controls and use cases, 218whether or not it's appropriate to configure inferencing. 219 220## Mixing Authentication Types 221 222Vault allows you to configure using either the ec2 auth method or the iam auth 223method, but not both auth methods. Further, Vault will prevent you from 224enforcing restrictions that it cannot enforce given the chosen auth type for a 225role. Some examples of how this works in practice: 226 2271. You configure a role with the ec2 auth type, with a bound AMI ID. A 228 client would not be able to login using the iam auth type. 2292. You configure a role with the iam auth type, with a bound IAM 230 principal ARN. A client would not be able to login with the ec2 auth method. 2313. You configure a role with the iam auth type and further configure 232 inferencing. You have a bound AMI ID and a bound IAM principal ARN. A client 233 must login using the iam method; the RoleSessionName must be a valid instance 234 ID viewable by Vault, and the instance must have come from the bound AMI ID. 235 236## Comparison of the IAM and EC2 Methods 237 238The iam and ec2 auth methods serve similar and somewhat overlapping 239functionality, in that both authenticate some type of AWS entity to Vault. 240Here are some comparisons that illustrate why `iam` method is preferred over 241`ec2`. 242 243* What type of entity is authenticated: 244 * The ec2 auth method authenticates only AWS EC2 instances and is specialized 245 to handle EC2 instances, such as restricting access to EC2 instances from 246 a particular AMI, EC2 instances in a particular instance profile, or EC2 247 instances with a specialized tag value (via the role_tag feature). 248 * The iam auth method authenticates AWS IAM principals. This can 249 include IAM users, IAM roles assumed from other accounts, AWS Lambdas that 250 are launched in an IAM role, or even EC2 instances that are launched in an 251 IAM instance profile. However, because it authenticates more generalized IAM 252 principals, this method doesn't offer more granular controls beyond binding 253 to a given IAM principal without the use of inferencing. 254* How the entities are authenticated 255 * The ec2 auth method authenticates instances by making use of the EC2 256 instance identity document, which is a cryptographically signed document 257 containing metadata about the instance. This document changes relatively 258 infrequently, so Vault adds a number of other constructs to mitigate against 259 replay attacks, such as client nonces, role tags, instance migrations, etc. 260 Because the instance identity document is signed by AWS, you have a strong 261 guarantee that it came from an EC2 instance. 262 * The iam auth method authenticates by having clients provide a specially 263 signed AWS API request which the method then passes on to AWS to validate 264 the signature and tell Vault who created it. The actual secret (i.e., 265 the AWS secret access key) is never transmitted over the wire, and the 266 AWS signature algorithm automatically expires requests after 15 minutes, 267 providing simple and robust protection against replay attacks. The use of 268 inferencing, however, provides a weaker guarantee that the credentials came 269 from an EC2 instance in an IAM instance profile compared to the ec2 270 authentication mechanism. 271 * The instance identity document used in the ec2 auth method is more likely to 272 be stolen given its relatively static nature, but it's harder to spoof. On 273 the other hand, the credentials of an EC2 instance in an IAM instance 274 profile are less likely to be stolen given their dynamic and short-lived 275 nature, but it's easier to spoof credentials that might have come from an 276 EC2 instance. 277* Specific use cases 278 * If you have non-EC2 instance entities, such as IAM users, Lambdas in IAM 279 roles, or developer laptops using [AdRoll's 280 Hologram](https://github.com/AdRoll/hologram) then you would need to use the 281 iam auth method. 282 * If you have EC2 instances, then you could use either auth method. If you 283 need more granular filtering beyond just the instance profile of given EC2 284 instances (such as filtering based off the AMI the instance was launched 285 from), then you would need to use the ec2 auth method, change the instance 286 profile associated with your EC2 instances so they have unique IAM roles 287 for each different Vault role you would want them to authenticate 288 to, or make use of inferencing. If you need to make use of role tags, then 289 you will need to use the ec2 auth method. 290 291## Recommended Vault IAM Policy 292 293This specifies the recommended IAM policy needed by the AWS auth method. Note 294that if you are using the same credentials for the AWS auth and secret methods 295(e.g., if you're running Vault on an EC2 instance in an IAM instance profile), 296then you will need to add additional permissions as required by the AWS secret 297method. 298 299```json 300{ 301 "Version": "2012-10-17", 302 "Statement": [ 303 { 304 "Effect": "Allow", 305 "Action": [ 306 "ec2:DescribeInstances", 307 "iam:GetInstanceProfile", 308 "iam:GetUser", 309 "iam:GetRole" 310 ], 311 "Resource": "*" 312 }, 313 { 314 "Effect": "Allow", 315 "Action": ["sts:AssumeRole"], 316 "Resource": [ 317 "arn:aws:iam::<AccountId>:role/<VaultRole>" 318 ] 319 } 320 ] 321} 322``` 323 324Here are some of the scenarios in which Vault would need to use each of these 325permissions. This isn't intended to be an exhaustive list of all the scenarios 326in which Vault might make an AWS API call, but rather illustrative of why these 327are needed. 328 329* `ec2:DescribeInstances` is necessary when you are using the `ec2` auth method 330 or when you are inferring an `ec2_instance` entity type to validate that the 331 EC2 instance meets binding requirements of the role 332* `iam:GetInstanceProfile` is used when you have a `bound_iam_role_arn` in the 333 `ec2` auth method. Vault needs to determine which IAM role is attached to the 334 instance profile. 335* `iam:GetUser` and `iam:GetRole` are used when using the iam auth method and 336 binding to an IAM user or role principal to determine the unique AWS user ID 337 or when using a wildcard on the bound ARN to resolve the full ARN of the user 338 or role. 339* The `sts:AssumeRole` stanza is necessary when you are using [Cross Account 340 Access](#cross-account-access). The `Resource`s specified should be a list of 341 all the roles for which you have configured cross-account access, and each of 342 those roles should have this IAM policy attached (except for the 343 `sts:AssumeRole` statement). 344 345## Client Nonce 346 347Note: this only applies to the ec2 auth method. 348 349If an unintended party gains access to the PKCS#7 signature of the identity 350document (which by default is available to every process and user that gains 351access to an EC2 instance), it can impersonate that instance and fetch a Vault 352token. The method addresses this problem by using a Trust On First Use (TOFU) 353mechanism that allows the first client to present the PKCS#7 signature of the 354document to be authenticated and denying the rest. An important property of 355this design is detection of unauthorized access: if an unintended party authenticates, 356the intended client will be unable to authenticate and can raise an alert for 357investigation. 358 359During the first login, the method stores the instance ID that authenticated 360in a `whitelist`. One method of operation of the method is to disallow any 361authentication attempt for an instance ID contained in the whitelist, using the 362`disallow_reauthentication` option on the role, meaning that an instance is 363allowed to login only once. However, this has consequences for token rotation, 364as it means that once a token has expired, subsequent authentication attempts 365would fail. By default, reauthentication is enabled in this method, and can be 366turned off using `disallow_reauthentication` parameter on the registered role. 367 368In the default method of operation, the method will return a unique nonce 369during the first authentication attempt, as part of auth `metadata`. Clients 370should present this `nonce` for subsequent login attempts and it should match 371the `nonce` cached at the identity-whitelist entry at the method. Since only 372the original client knows the `nonce`, only the original client is allowed to 373reauthenticate. (This is the reason that this is a whitelist rather than a 374blacklist; by default, it's keeping track of clients allowed to reauthenticate, 375rather than those that are not.). Clients can choose to provide a `nonce` even 376for the first login attempt, in which case the provided `nonce` will be tied to 377the cached identity-whitelist entry. It is recommended to use a strong `nonce` 378value in this case. 379 380It is up to the client to behave correctly with respect to the nonce; if the 381client stores the nonce on disk it can survive reboots, but could also give 382access to other users or applications on the instance. It is also up to the 383operator to ensure that client nonces are in fact unique; sharing nonces allows 384a compromise of the nonce value to enable an attacker that gains access to any 385EC2 instance to imitate the legitimate client on that instance. This is why 386nonces can be disabled on the method side in favor of only a single 387authentication per instance; in some cases, such as when using ASGs, instances 388are immutable and single-boot anyways, and in conjunction with a high max TTL, 389reauthentication may not be needed (and if it is, the instance can simply be 390shut down and allow ASG to start a new one). 391 392In both cases, entries can be removed from the whitelist by instance ID, 393allowing reauthentication by a client if the nonce is lost (or not used) and an 394operator approves the process. 395 396One other point: if available by the OS/distribution being used with the EC2 397instance, it is not a bad idea to firewall access to the signed PKCS#7 metadata 398to ensure that it is accessible only to the matching user(s) that require 399access. 400 401The client nonce which is generated by the backend and which gets returned 402along with the authentication response, will be audit logged in plaintext. If 403this is undesired, clients can supply a custom nonce to the login endpoint 404which will not be returned and hence will not be audit logged. 405 406## Advanced Options and Caveats 407 408### Dynamic Management of Policies Via Role Tags 409 410Note: This only applies to the ec2 auth method or the iam auth method when 411inferencing is used. 412 413If the instance is required to have customized set of policies based on the 414role it plays, the `role_tag` option can be used to provide a tag to set on 415instances, for a given role. When this option is set, during login, along with 416verification of PKCS#7 signature and instance health, the method will query 417for the value of a specific tag with the configured key that is attached to the 418instance. The tag holds information that represents a *subset* of privileges that 419are set on the role and are used to further restrict the set of the role's 420privileges for that particular instance. 421 422A `role_tag` can be created using `auth/aws/role/<role>/tag` endpoint 423and is immutable. The information present in the tag is SHA256 hashed and HMAC 424protected. The per-role key to HMAC is only maintained in the method. This prevents 425an adversarial operator from modifying the tag when setting it on the EC2 instance 426in order to escalate privileges. 427 428When 'role_tag' option is enabled on a role, the instances are required to have a 429role tag. If the tag is not found on the EC2 instance, authentication will fail. 430This is to ensure that privileges of an instance are never escalated for not 431having the tag on it or for getting the tag removed. If the role tag creation does 432not specify the policy component, the client will inherit the allowed policies set 433on the role. If the role tag creation specifies the policy component but it contains 434no policies, the token will contain only the `default` policy; by default, this policy 435allows only manipulation (revocation, renewal, lookup) of the existing token, plus 436access to its [cubbyhole](/docs/secrets/cubbyhole/index.html). 437This can be useful to allow instances access to a secure "scratch space" for 438storing data (via the token's cubbyhole) but without granting any access to 439other resources provided by or resident in Vault. 440 441### Handling Lost Client Nonces 442 443Note: This only applies to the ec2 auth method. 444 445If an EC2 instance loses its client nonce (due to a reboot, a stop/start of the 446client, etc.), subsequent login attempts will not succeed. If the client nonce 447is lost, normally the only option is to delete the entry corresponding to the 448instance ID from the identity `whitelist` in the method. This can be done via 449the `auth/aws/identity-whitelist/<instance_id>` endpoint. This allows a new 450client nonce to be accepted by the method during the next login request. 451 452Under certain circumstances there is another useful setting. When the instance 453is placed onto a host upon creation, it is given a `pendingTime` value in the 454instance identity document (documentation from AWS does not cover this option, 455unfortunately). If an instance is stopped and started, the `pendingTime` value 456is updated (this does not apply to reboots, however). 457 458The method can take advantage of this via the `allow_instance_migration` 459option, which is set per-role. When this option is enabled, if the client nonce 460does not match the saved nonce, the `pendingTime` value in the instance 461identity document will be checked; if it is newer than the stored `pendingTime` 462value, the method assumes that the client was stopped/started and allows the 463client to log in successfully, storing the new nonce as the valid nonce for 464that client. This essentially re-starts the TOFU mechanism any time the 465instance is stopped and started, so should be used with caution. Just like with 466initial authentication, the legitimate client should have a way to alert (or an 467alert should trigger based on its logs) if it is denied authentication. 468 469Unfortunately, the `allow_instance_migration` only helps during stop/start 470actions; the current metadata does not provide for a way to allow this 471automatic behavior during reboots. The method will be updated if this needed 472metadata becomes available. 473 474The `allow_instance_migration` option is set per-role, and can also be 475specified in a role tag. Since role tags can only restrict behavior, if the 476option is set to `false` on the role, a value of `true` in the role tag takes 477effect; however, if the option is set to `true` on the role, a value set in the 478role tag has no effect. 479 480### Disabling Reauthentication 481 482Note: this only applies to the ec2 auth method. 483 484If in a given organization's architecture, a client fetches a long-lived Vault 485token and has no need to rotate the token, all future logins for that instance 486ID can be disabled. If the option `disallow_reauthentication` is set, only one 487login will be allowed per instance. If the intended client successfully 488retrieves a token during login, it can be sure that its token will not be 489hijacked by another entity. 490 491When `disallow_reauthentication` option is enabled, the client can choose not 492to supply a nonce during login, although it is not an error to do so (the nonce 493is simply ignored). Note that reauthentication is enabled by default. If only 494a single login is desired, `disallow_reauthentication` should be set explicitly 495on the role or on the role tag. 496 497The `disallow_reauthentication` option is set per-role, and can also be 498specified in a role tag. Since role tags can only restrict behavior, if the 499option is set to `false` on the role, a value of `true` in the role tag takes 500effect; however, if the option is set to `true` on the role, a value set in the 501role tag has no effect. 502 503### Blacklisting Role Tags 504 505Note: this only applies to the ec2 auth method or the iam auth method 506when inferencing is used. 507 508Role tags are tied to a specific role, but the method has no control over, which 509instances using that role, should have any particular role tag; that is purely up 510to the operator. Although role tags are only restrictive (a tag cannot escalate 511privileges above what is set on its role), if a role tag is found to have been 512used incorrectly, and the administrator wants to ensure that the role tag has no 513further effect, the role tag can be placed on a `blacklist` via the endpoint 514`auth/aws/roletag-blacklist/<role_tag>`. Note that this will not invalidate the 515tokens that were already issued; this only blocks any further login requests from 516those instances that have the blacklisted tag attached to them. 517 518### Expiration Times and Tidying of `blacklist` and `whitelist` Entries 519 520The expired entries in both identity `whitelist` and role tag `blacklist` are 521deleted automatically. The entries in both of these lists contain an expiration 522time which is dynamically determined by three factors: `max_ttl` set on the role, 523`max_ttl` set on the role tag, and `max_ttl` value of the method mount. The 524least of these three dictates the maximum TTL of the issued token, and 525correspondingly will be set as the expiration times of these entries. 526 527The endpoints `auth/aws/tidy/identity-whitelist` and `auth/aws/tidy/roletag-blacklist` are 528provided to clean up the entries present in these lists. These endpoints allow 529defining a safety buffer, such that an entry must not only be expired, but be 530past expiration by the amount of time dictated by the safety buffer in order 531to actually remove the entry. 532 533Automatic deletion of expired entries is performed by the periodic function 534of the method. This function does the tidying of both blacklist role tags 535and whitelist identities. Periodic tidying is activated by default and will 536have a safety buffer of 72 hours, meaning only those entries are deleted which 537were expired before 72 hours from when the tidy operation is being performed. 538This can be configured via `config/tidy/roletag-blacklist` and `config/tidy/identity-whitelist` 539endpoints. 540 541### Varying Public Certificates 542 543Note: this only applies to the ec2 auth method. 544 545The AWS public certificate, which contains the public key used to verify the 546PKCS#7 signature, varies for different AWS regions. The primary AWS public 547certificate, which covers most AWS regions, is already included in Vault and 548does not need to be added. Instances whose PKCS#7 signatures cannot be 549verified by the default public certificate included in Vault can register a 550different public certificate which can be found [here] 551(http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html), 552via the `auth/aws/config/certificate/<cert_name>` endpoint. 553 554### Dangling Tokens 555 556An EC2 instance, after authenticating itself with the method, gets a Vault token. 557After that, if the instance terminates or goes down for any reason, the method 558will not be aware of such events. The token issued will still be valid, until 559it expires. The token will likely be expired sooner than its lifetime when the 560instance fails to renew the token on time. 561 562### Cross Account Access 563 564To allow Vault to authenticate IAM principals and EC2 instances in other 565accounts, Vault supports using AWS STS (Security Token Service) to assume AWS 566IAM Roles in other accounts. For each target AWS account ID, you configure the 567IAM Role for Vault to assume using the `auth/aws/config/sts/<account_id>` and 568Vault will use credentials from assuming that role to validate IAM principals 569and EC2 instances in the target account. 570 571The account in which Vault is running (i.e. the master account) must be listed as 572a trusted entity in the IAM Role being assumed on the remote account. The Role itself 573should allow the permissions specified in the (Recommended Vault IAM 574Policy)(#recommended-vault-iam-policy) except it doesn't need any further 575`sts:AssumeRole` permissions. 576 577Furthermore, in the master account, Vault must be granted the action `sts:AssumeRole` 578for the IAM Role to be assumed. 579 580## Authentication 581 582### Via the CLI 583 584#### Enable AWS EC2 authentication in Vault. 585 586``` 587$ vault auth enable aws 588``` 589 590#### Configure the credentials required to make AWS API calls 591 592If not specified, Vault will attempt to use standard environment variables 593(`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) or IAM EC2 instance role 594credentials if available. 595 596The IAM account or role to which the credentials map must allow the 597`ec2:DescribeInstances` action. In addition, if IAM Role binding is used (see 598`bound_iam_role_arn` below), `iam:GetInstanceProfile` must also be allowed. 599 600``` 601$ vault write auth/aws/config/client secret_key=vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj access_key=VKIAJBRHKH6EVTTNXDHA 602``` 603 604#### Configure the policies on the role. 605 606``` 607$ vault write auth/aws/role/dev-role auth_type=ec2 bound_ami_id=ami-fce3c696 policies=prod,dev max_ttl=500h 608 609$ vault write auth/aws/role/dev-role-iam auth_type=iam \ 610 bound_iam_principal_arn=arn:aws:iam::123456789012:role/MyRole policies=prod,dev max_ttl=500h 611``` 612 613#### Configure a required X-Vault-AWS-IAM-Server-ID Header (recommended) 614 615``` 616$ vault write auth/aws/config/client iam_server_id_header_value=vault.example.com 617``` 618 619 620#### Perform the login operation 621 622``` 623$ vault write auth/aws/login role=dev-role \ 624pkcs7=MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCAJIAEggGmewogICJkZXZwYXlQcm9kdWN0Q29kZXMiIDogbnVsbCwKICAicHJpdmF0ZUlwIiA6ICIxNzIuMzEuNjMuNjAiLAogICJhdmFpbGFiaWxpdHlab25lIiA6ICJ1cy1lYXN0LTFjIiwKICAidmVyc2lvbiIgOiAiMjAxMC0wOC0zMSIsCiAgImluc3RhbmNlSWQiIDogImktZGUwZjEzNDQiLAogICJiaWxsaW5nUHJvZHVjdHMiIDogbnVsbCwKICAiaW5zdGFuY2VUeXBlIiA6ICJ0Mi5taWNybyIsCiAgImFjY291bnRJZCIgOiAiMjQxNjU2NjE1ODU5IiwKICAiaW1hZ2VJZCIgOiAiYW1pLWZjZTNjNjk2IiwKICAicGVuZGluZ1RpbWUiIDogIjIwMTYtMDQtMDVUMTY6MjY6NTVaIiwKICAiYXJjaGl0ZWN0dXJlIiA6ICJ4ODZfNjQiLAogICJrZXJuZWxJZCIgOiBudWxsLAogICJyYW1kaXNrSWQiIDogbnVsbCwKICAicmVnaW9uIiA6ICJ1cy1lYXN0LTEiCn0AAAAAAAAxggEXMIIBEwIBATBpMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQwIJAJa6SNnlXhpnMAkGBSsOAwIaBQCgXTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNjA0MDUxNjI3MDBaMCMGCSqGSIb3DQEJBDEWBBRtiynzMTNfTw1TV/d8NvfgVw+XfTAJBgcqhkjOOAQDBC4wLAIUVfpVcNYoOKzN1c+h1Vsm/c5U0tQCFAK/K72idWrONIqMOVJ8Uen0wYg4AAAAAAAA nonce=5defbf9e-a8f9-3063-bdfc-54b7a42a1f95 625``` 626 627For the iam auth method, generating the signed request is a non-standard 628operation. The Vault cli supports generating this for you: 629 630``` 631$ vault login -method=aws header_value=vault.example.com role=dev-role-iam 632``` 633 634This assumes you have AWS credentials configured in the standard locations AWS 635SDKs search for credentials (environment variables, ~/.aws/credentials, IAM 636instance profile, or ECS task role, in that order). If you do not have IAM 637credentials available at any of these locations, you can explicitly pass them 638in on the command line (though this is not recommended), omitting 639`aws_security_token` if not applicable. 640 641``` 642$ vault login -method=aws header_value=vault.example.com role=dev-role-iam \ 643 aws_access_key_id=<access_key> \ 644 aws_secret_access_key=<secret_key> \ 645 aws_security_token=<security_token> 646``` 647 648An example of how to generate the required request values for the `login` method 649can be found found in the [vault cli 650source code](https://github.com/hashicorp/vault/blob/master/builtin/credential/aws/cli.go). 651Using an approach such as this, the request parameters can be generated and 652passed to the `login` method: 653 654``` 655$ vault write auth/aws/login role=dev-role-iam \ 656 iam_http_request_method=POST \ 657 iam_request_url=aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8= \ 658 iam_request_body=QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ== \ 659 iam_request_headers=eyJDb250ZW50LUxlbmd0aCI6IFsiNDMiXSwgIlVzZXItQWdlbnQiOiBbImF3cy1zZGstZ28vMS40LjEyIChnbzEuNy4xOyBsaW51eDsgYW1kNjQpIl0sICJYLVZhdWx0LUFXU0lBTS1TZXJ2ZXItSWQiOiBbInZhdWx0LmV4YW1wbGUuY29tIl0sICJYLUFtei1EYXRlIjogWyIyMDE2MDkzMFQwNDMxMjFaIl0sICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZDsgY2hhcnNldD11dGYtOCJdLCAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPWZvby8yMDE2MDkzMC91cy1lYXN0LTEvc3RzL2F3czRfcmVxdWVzdCwgU2lnbmVkSGVhZGVycz1jb250ZW50LWxlbmd0aDtjb250ZW50LXR5cGU7aG9zdDt4LWFtei1kYXRlO3gtdmF1bHQtc2VydmVyLCBTaWduYXR1cmU9YTY5ZmQ3NTBhMzQ0NWM0ZTU1M2UxYjNlNzlkM2RhOTBlZWY1NDA0N2YxZWI0ZWZlOGZmYmM5YzQyOGMyNjU1YiJdfQ== 660``` 661 662### Via the API 663 664#### Enable AWS authentication in Vault. 665 666``` 667curl -X POST -H "X-Vault-Token:123" "http://127.0.0.1:8200/v1/sys/auth/aws" -d '{"type":"aws"}' 668``` 669 670#### Configure the credentials required to make AWS API calls. 671 672``` 673curl -X POST -H "X-Vault-Token:123" "http://127.0.0.1:8200/v1/auth/aws/config/client" -d '{"access_key":"VKIAJBRHKH6EVTTNXDHA", "secret_key":"vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj"}' 674``` 675 676#### Configure the policies on the role. 677 678``` 679curl -X POST -H "X-Vault-Token:123" "http://127.0.0.1:8200/v1/auth/aws/role/dev-role -d '{"bound_ami_id":"ami-fce3c696","policies":"prod,dev","max_ttl":"500h"}' 680 681curl -X POST -H "X-Vault-Token:123" "http://127.0.0.1:8200/v1/auth/aws/role/dev-role-iam -d '{"auth_type":"iam","policies":"prod,dev","max_ttl":"500h","bound_iam_principal_arn":"arn:aws:iam::123456789012:role/MyRole"}' 682``` 683 684#### Perform the login operation 685 686``` 687curl -X POST "http://127.0.0.1:8200/v1/auth/aws/login" -d '{"role":"dev-role","pkcs7":"'$(curl -s http://169.254.169.254/latest/dynamic/instance-identity/pkcs7 | tr -d '\n')'","nonce":"5defbf9e-a8f9-3063-bdfc-54b7a42a1f95"}' 688 689curl -X POST "http://127.0.0.1:8200/v1/auth/aws/login" -d '{"role":"dev", "iam_http_request_method": "POST", "iam_request_url": "aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8=", "iam_request_body": "QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ==", "iam_request_headers": "eyJDb250ZW50LUxlbmd0aCI6IFsiNDMiXSwgIlVzZXItQWdlbnQiOiBbImF3cy1zZGstZ28vMS40LjEyIChnbzEuNy4xOyBsaW51eDsgYW1kNjQpIl0sICJYLVZhdWx0LUFXU0lBTS1TZXJ2ZXItSWQiOiBbInZhdWx0LmV4YW1wbGUuY29tIl0sICJYLUFtei1EYXRlIjogWyIyMDE2MDkzMFQwNDMxMjFaIl0sICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZDsgY2hhcnNldD11dGYtOCJdLCAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPWZvby8yMDE2MDkzMC91cy1lYXN0LTEvc3RzL2F3czRfcmVxdWVzdCwgU2lnbmVkSGVhZGVycz1jb250ZW50LWxlbmd0aDtjb250ZW50LXR5cGU7aG9zdDt4LWFtei1kYXRlO3gtdmF1bHQtc2VydmVyLCBTaWduYXR1cmU9YTY5ZmQ3NTBhMzQ0NWM0ZTU1M2UxYjNlNzlkM2RhOTBlZWY1NDA0N2YxZWI0ZWZlOGZmYmM5YzQyOGMyNjU1YiJdfQ==" }' 690``` 691 692The response will be in JSON. For example: 693 694```javascript 695{ 696 "auth": { 697 "renewable": true, 698 "lease_duration": 72000, 699 "metadata": { 700 "role_tag_max_ttl": "0s", 701 "role": "ami-f083709d", 702 "region": "us-east-1", 703 "nonce": "5defbf9e-a8f9-3063-bdfc-54b7a42a1f95", 704 "instance_id": "i-a832f734", 705 "ami_id": "ami-f083709d" 706 }, 707 "policies": [ 708 "default", 709 "dev", 710 "prod" 711 ], 712 "accessor": "5cd96cd1-58b7-2904-5519-75ddf957ec06", 713 "client_token": "150fc858-2402-49c9-56a5-f4b57f2c8ff1" 714 }, 715 "warnings": null, 716 "wrap_info": null, 717 "data": null, 718 "lease_duration": 0, 719 "renewable": false, 720 "lease_id": "", 721 "request_id": "d7d50c06-56b8-37f4-606c-ccdc87a1ee4c" 722} 723``` 724 725## API 726 727The AWS auth method has a full HTTP API. Please see the 728[AWS Auth API](/api/auth/aws/index.html) for more 729details. 730