1--- 2layout: api 3page_title: AWS - Auth Methods - HTTP API 4description: This is the API documentation for the Vault AWS auth method. 5--- 6 7# AWS Auth Method (API) 8 9This is the API documentation for the Vault AWS auth method. For 10general information about the usage and operation of the AWS method, please 11see the [Vault AWS method documentation](/docs/auth/aws). 12 13This documentation assumes the AWS method is mounted at the `/auth/aws` 14path in Vault. Since it is possible to enable auth methods at any location, 15please update your API calls accordingly. 16 17~> **Vault 1.7** deprecated several AWS Auth URLs. The full 18[list of affected endpoints](#deprecations-effective-in-vault-1-7) and their 19replacements is provided at the end of this document. 20 21## Configure Client 22 23Configures the credentials required to perform API calls to AWS as well as 24custom endpoints to talk to AWS APIs. The instance identity document 25fetched from the PKCS#7 signature will provide the EC2 instance ID. The 26credentials configured using this endpoint will be used to query the status 27of the instances via DescribeInstances API. If static credentials are not 28provided using this endpoint, then the credentials will be retrieved from 29the environment variables `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` and 30`AWS_REGION` respectively. If the credentials are still not found and if the 31method is configured on an EC2 instance with metadata querying 32capabilities, the credentials are fetched automatically. 33 34| Method | Path | 35| :----- | :------------------------ | 36| `POST` | `/auth/aws/config/client` | 37 38### Parameters 39 40- `max_retries` `(int: -1)` - Number of max retries the client should use for 41 recoverable errors. The default (`-1`) falls back to the AWS SDK's default 42 behavior. 43- `access_key` `(string: "")` - AWS Access key with permissions to query AWS 44 APIs. The permissions required depend on the specific configurations. If using 45 the `iam` auth method without inferencing, then no credentials are necessary. 46 If using the `ec2` auth method or using the `iam` auth method with 47 inferencing, then these credentials need access to `ec2:DescribeInstances`. If 48 additionally a `bound_iam_role` is specified, then these credentials also need 49 access to `iam:GetInstanceProfile`. If, however, an alternate sts 50 configuration is set for the target account, then the credentials must be 51 permissioned to call `sts:AssumeRole` on the configured role, and that role 52 must have the permissions described here. 53- `secret_key` `(string: "")` - AWS Secret key with permissions to query AWS 54 APIs. 55- `endpoint` `(string: "")` - URL to override the default generated endpoint for 56 making AWS EC2 API calls. 57- `iam_endpoint` `(string: "")` - URL to override the default generated endpoint 58 for making AWS IAM API calls. 59- `sts_endpoint` `(string: "")` - URL to override the default generated endpoint 60 for making AWS STS API calls. If set, `sts_region` should also be set. 61- `sts_region` `(string: "")` - Region to override the default region for making 62 AWS STS API calls. Should only be set if `sts_endpoint` is set. If so, should 63 be set to the region in which the custom `sts_endpoint` resides. 64- `iam_server_id_header_value` `(string: "")` - The value to require in the 65 `X-Vault-AWS-IAM-Server-ID` header as part of GetCallerIdentity requests that 66 are used in the iam auth method. If not set, then no value is required or 67 validated. If set, clients must include an X-Vault-AWS-IAM-Server-ID header in 68 the headers of login requests, and further this header must be among the 69 signed headers validated by AWS. This is to protect against different types of 70 replay attacks, for example a signed request sent to a dev server being resent 71 to a production server. Consider setting this to the Vault server's DNS name. 72- `allowed_sts_header_values` `(string: "")` A comma separated list of 73 additional request headers permitted when providing the iam_request_headers for 74 an IAM based login call. In any case, a default list of headers AWS STS 75 expects for a GetCallerIdentity are allowed. 76 77### Sample Payload 78 79```json 80{ 81 "access_key": "VKIAJBRHKH6EVTTNXDHA", 82 "secret_key": "vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj" 83} 84``` 85 86### Sample Request 87 88```shell-session 89$ curl \ 90 --header "X-Vault-Token: ..." \ 91 --request POST \ 92 --data @payload.json \ 93 http://127.0.0.1:8200/v1/auth/aws/config/client 94``` 95 96## Read Config 97 98Returns the previously configured AWS access credentials. 99 100| Method | Path | 101| :----- | :------------------------ | 102| `GET` | `/auth/aws/config/client` | 103 104### Sample Request 105 106```shell-session 107$ curl \ 108 --header "X-Vault-Token: ..." \ 109 http://127.0.0.1:8200/v1/auth/aws/config/client 110``` 111 112### Sample Response 113 114```json 115{ 116 "data": { 117 "access_key": "VKIAJBRHKH6EVTTNXDHA", 118 "endpoint": "", 119 "iam_endpoint": "", 120 "sts_endpoint": "", 121 "sts_region": "", 122 "iam_server_id_header_value": "" 123 } 124} 125``` 126 127## Delete Config 128 129Deletes the previously configured AWS access credentials. 130 131| Method | Path | 132| :------- | :------------------------ | 133| `DELETE` | `/auth/aws/config/client` | 134 135### Sample Request 136 137```shell-session 138$ curl \ 139 --header "X-Vault-Token: ..." \ 140 --request DELETE \ 141 http://127.0.0.1:8200/v1/auth/aws/config/client 142``` 143 144## Rotate Root Credentials 145 146When you have configured Vault with static credentials, you can use this 147endpoint to have Vault rotate the access key it used. Note that, due to AWS 148eventual consistency, after calling this endpoint, subsequent calls from Vault 149to AWS may fail for a few seconds until AWS becomes consistent again. 150 151In order to call this endpoint, Vault's AWS access key MUST be the only access 152key on the IAM user; otherwise, generation of a new access key will fail. Once 153this method is called, Vault will now be the only entity that knows the AWS 154secret key is used to access AWS. 155 156| Method | Path | 157| :----- | :----------------------------- | 158| `POST` | `/auth/aws/config/rotate-root` | 159 160### Parameters 161 162There are no parameters to this operation. 163 164### Sample Request 165 166```$ curl \ 167 --header "X-Vault-Token: ..." \ 168 --request POST \ 169 http://127.0.0.1:8200/v1/auth/aws/config/rotate-root 170``` 171 172### Sample Response 173 174```json 175{ 176 "data": { 177 "access_key": "AKIA..." 178 } 179} 180``` 181 182The new access key Vault uses is returned by this operation. 183 184## Configure Identity Integration 185 186This configures the way that Vault interacts with the 187[Identity](/docs/secrets/identity) store. The default (as of Vault 1881.0.3) is `role_id` for both values. 189 190| Method | Path | 191| :----- | :-------------------------- | 192| `POST` | `/auth/aws/config/identity` | 193 194### Parameters 195 196- `iam_alias` `(string: "role_id")` - How to generate the identity alias when 197 using the `iam` auth method. Valid choices are `role_id`, `unique_id`, and 198 `full_arn` When `role_id` is selected, the randomly generated ID of the role 199 is used. When `unique_id` is selected, the [IAM Unique 200 ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers#identifiers-unique-ids) 201 of the IAM principal (either the user or role) is used as the identity alias 202 name. When `full_arn` is selected, the ARN returned by the 203 `sts:GetCallerIdentity` call is used as the alias name. This is either 204 `arn:aws:iam::<account_id>:user/<optional_path/><user_name>` or 205 `arn:aws:sts::<account_id>:assumed-role/<role_name_without_path>/<role_session_name>`. 206 **Note**: if you select `full_arn` and then delete and recreate the IAM role, 207 Vault won't be aware and any identity aliases set up for the role name will 208 still be valid. 209 210- `iam_metadata` `(string: "default")` - The metadata to include on the token 211 returned by the `login` endpoint. This metadata will be added to both audit logs, 212 and on the `iam_alias`. By default, it includes `account_id` and `auth_type`. 213 Additionally, `canonical_arn`, `client_arn`, `client_user_id`, `inferred_aws_region`, 214 `inferred_entity_id`, and `inferred_entity_type` are available. To include no metadata, 215 set to `""` via the CLI or `[]` via the API. To use only particular fields, select 216 the explicit fields. To restore to defaults, send only a field of `default`. 217 **Only select fields that will have a low rate of change** for your `iam_alias` because 218 each change triggers a storage write and can have a performance impact at scale. 219 220- `ec2_alias` `(string: "role_id")` - Configures how to generate the identity 221 alias when using the `ec2` auth method. Valid choices are `role_id`, 222 `instance_id`, and `image_id`. When `role_id` is selected, the randomly 223 generated ID of the role is used. When `instance_id` is selected, the 224 instance identifier is used as the identity alias name. When `image_id` is 225 selected, AMI ID of the instance is used as the identity alias name. 226 227- `ec2_metadata` `(string: "default")` - The metadata to include on the token 228 returned by the `login` endpoint. This metadata will be added to both audit logs, 229 and on the `ec2_alias`. By default, it includes `account_id` and `auth_type`. 230 Additionally, `ami_id`, `instance_id`, and `region`, are available. To include no metadata, 231 set to `""` via the CLI or `[]` via the API. To use only particular fields, select 232 the explicit fields. To restore to defaults, send only a field of `default`. 233 **Only select fields that will have a low rate of change** for your `ec2_alias` because 234 each change triggers a storage write and can have a performance impact at scale. 235 236### Sample Payload 237 238```json 239{ 240 "iam_alias": "unique_id" 241} 242``` 243 244### Sample Request 245 246```shell-session 247$ curl \ 248 -- header "X-Vault-Token:..." \ 249 --request POST 250 --data @payload.json \ 251 http://127.0.0.1:8200/v1/auth/aws/config/identity 252``` 253 254## Read Identity Integration Configuration 255 256Returns the previously configured Identity integration configuration 257 258| Method | Path | 259| :----- | :-------------------------- | 260| `GET` | `/auth/aws/config/identity` | 261 262### Sample Request 263 264```shell-session 265$ curl \ 266 --header "X-Vault-Token:..." \ 267 http://127.0.0.1:8200/v1/auth/aws/config/identity 268``` 269 270### Sample Response 271 272```json 273{ 274 "data": { 275 "iam_alias": "full_arn" 276 } 277} 278``` 279 280## Create Certificate Configuration 281 282Registers an AWS public key to be used to verify the instance identity 283documents. While the PKCS#7 signature of the identity documents have DSA 284digest, the identity signature will have RSA digest, and hence the public 285keys for each type varies respectively. Indicate the type of the public key 286using the "type" parameter. 287 288| Method | Path | 289| :----- | :---------------------------------------- | 290| `POST` | `/auth/aws/config/certificate/:cert_name` | 291 292### Parameters 293 294- `cert_name` `(string: <required>)` - Name of the certificate. 295- `aws_public_cert` `(string: <required>)` - Base64 encoded AWS Public key required to verify 296 PKCS7 signature of the EC2 instance metadata. 297- `type` `(string: "pkcs7")` - Takes the value of either "pkcs7" or "identity", 298 indicating the type of document which can be verified using the given 299 certificate. The PKCS#7 document will have a DSA digest and the identity 300 signature will have an RSA signature, and accordingly the public certificates 301 to verify those also vary. Defaults to "pkcs7". 302 303### Sample Payload 304 305```json 306{ 307 "aws_public_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM3VENDQXEwQ0NRQ1d1a2paNVY0YVp6QUpCZ2NxaGtqT09BUURNRnd4Q3pBSkJnTlZCQVlUQWxWVE1Sa3cKRndZRFZRUUlFeEJYWVhOb2FXNW5kRzl1SUZOMFlYUmxNUkF3RGdZRFZRUUhFd2RUWldGMGRHeGxNU0F3SGdZRApWUVFLRXhkQmJXRjZiMjRnVjJWaUlGTmxjblpwWTJWeklFeE1RekFlRncweE1qQXhNRFV4TWpVMk1USmFGdzB6Ck9EQXhNRFV4TWpVMk1USmFNRnd4Q3pBSkJnTlZCQVlUQWxWVE1Sa3dGd1lEVlFRSUV4QlhZWE5vYVc1bmRHOXUKSUZOMFlYUmxNUkF3RGdZRFZRUUhFd2RUWldGMGRHeGxNU0F3SGdZRFZRUUtFeGRCYldGNmIyNGdWMlZpSUZObApjblpwWTJWeklFeE1RekNDQWJjd2dnRXNCZ2NxaGtqT09BUUJNSUlCSHdLQmdRQ2prdmNTMmJiMVZRNHl0LzVlCmloNU9PNmtLL24xTHpsbHI3RDhad3RRUDhmT0VwcDVFMm5nK0Q2VWQxWjFnWWlwcjU4S2ozbnNzU05wSTZiWDMKVnlJUXpLN3dMY2xuZC9Zb3pxTk5tZ0l5WmVjTjdFZ2xLOUlUSEpMUCt4OEZ0VXB0M1FieVlYSmRtVk1lZ042UApodmlZdDVKSC9uWWw0aGgzUGExSEpkc2tnUUlWQUxWSjNFUjExK0tvNHRQNm53dkh3aDYrRVJZUkFvR0JBSTFqCmsrdGtxTVZIdUFGY3ZBR0tvY1Rnc2pKZW02LzVxb216SnVLRG1iSk51OVF4dzNyQW90WGF1OFFlK01CY0psL1UKaGh5MUtIVnBDR2w5ZnVlUTJzNklMMENhTy9idXljVTFDaVlRazQwS05IQ2NIZk5pWmJkbHgxRTlycFVwN2JuRgpsUmEydjFudE1YM2NhUlZEZGJ0UEVXbWR4U0NZc1lGRGs0bVpyT0xCQTRHRUFBS0JnRWJtZXZlNWY4TElFL0dmCk1ObVA5Q001ZW92UU9HeDVobzhXcUQrYVRlYnMrazJ0bjkyQkJQcWVacXBXUmE1UC8ranJkS21sMXF4NGxsSFcKTVhyczNJZ0liNitoVUlCK1M4ZHo4L21tTzBicHI3NlJvWlZDWFlhYjJDWmVkRnV0N3FjM1dVSDkrRVVBSDVtdwp2U2VEQ09VTVlRUjdSOUxJTll3b3VISXppcVFZTUFrR0J5cUdTTTQ0QkFNREx3QXdMQUlVV1hCbGs0MHhUd1N3CjdIWDMyTXhYWXJ1c2U5QUNGQk5HbWRYMlpCclZOR3JOOU4yZjZST2swazlLCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K" 308} 309``` 310 311### Sample Request 312 313```shell-session 314$ curl \ 315 --header "X-Vault-Token: ..." \ 316 --request POST \ 317 --data @payload.json \ 318 http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert 319``` 320 321## Read Certificate Configuration 322 323Returns the previously configured AWS public key. 324 325| Method | Path | 326| :----- | :---------------------------------------- | 327| `GET` | `/auth/aws/config/certificate/:cert_name` | 328 329### Parameters 330 331- `cert_name` `(string: <required>)` - Name of the certificate. 332 333### Sample Request 334 335```shell-session 336$ curl \ 337 --header "X-Vault-Token: ..." \ 338 http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert 339``` 340 341### Sample Response 342 343```json 344{ 345 "data": { 346 "aws_public_cert": "-----BEGIN CERTIFICATE-----\nMIIC7TCCAq0CCQCWukjZ5V4aZzAJBgcqhkjOOAQDMFwxCzAJBgNVBAYTAlVTMRkw\nFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYD\nVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQzAeFw0xMjAxMDUxMjU2MTJaFw0z\nODAxMDUxMjU2MTJaMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9u\nIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNl\ncnZpY2VzIExMQzCCAbcwggEsBgcqhkjOOAQBMIIBHwKBgQCjkvcS2bb1VQ4yt/5e\nih5OO6kK/n1Lzllr7D8ZwtQP8fOEpp5E2ng+D6Ud1Z1gYipr58Kj3nssSNpI6bX3\nVyIQzK7wLclnd/YozqNNmgIyZecN7EglK9ITHJLP+x8FtUpt3QbyYXJdmVMegN6P\nhviYt5JH/nYl4hh3Pa1HJdskgQIVALVJ3ER11+Ko4tP6nwvHwh6+ERYRAoGBAI1j\nk+tkqMVHuAFcvAGKocTgsjJem6/5qomzJuKDmbJNu9Qxw3rAotXau8Qe+MBcJl/U\nhhy1KHVpCGl9fueQ2s6IL0CaO/buycU1CiYQk40KNHCcHfNiZbdlx1E9rpUp7bnF\nlRa2v1ntMX3caRVDdbtPEWmdxSCYsYFDk4mZrOLBA4GEAAKBgEbmeve5f8LIE/Gf\nMNmP9CM5eovQOGx5ho8WqD+aTebs+k2tn92BBPqeZqpWRa5P/+jrdKml1qx4llHW\nMXrs3IgIb6+hUIB+S8dz8/mmO0bpr76RoZVCXYab2CZedFut7qc3WUH9+EUAH5mw\nvSeDCOUMYQR7R9LINYwouHIziqQYMAkGByqGSM44BAMDLwAwLAIUWXBlk40xTwSw\n7HX32MxXYruse9ACFBNGmdX2ZBrVNGrN9N2f6ROk0k9K\n-----END CERTIFICATE-----\n", 347 "type": "pkcs7" 348 } 349} 350``` 351 352## Delete Certificate Configuration 353 354Removes the previously configured AWS public key. 355 356| Method | Path | 357| :------- | :---------------------------------------- | 358| `DELETE` | `/auth/aws/config/certificate/:cert_name` | 359 360### Sample Request 361 362```shell-session 363$ curl \ 364 --header "X-Vault-Token: ..." \ 365 --request DELETE \ 366 http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert 367``` 368 369## List Certificate Configurations 370 371Lists all the AWS public certificates that are registered with the method. 372 373| Method | Path | 374| :----- | :------------------------------ | 375| `LIST` | `/auth/aws/config/certificates` | 376 377### Sample Request 378 379```shell-session 380$ curl \ 381 --header "X-Vault-Token: ..." \ 382 --request LIST \ 383 http://127.0.0.1:8200/v1/auth/aws/config/certificates 384``` 385 386### Sample Response 387 388```json 389{ 390 "data": { 391 "keys": ["cert1"] 392 } 393} 394``` 395 396## Create STS Role 397 398Allows the explicit association of STS roles to satellite AWS accounts 399(i.e. those which are not the account in which the Vault server is 400running.) Vault will use credentials obtained by assuming these STS roles 401when validating IAM principals or EC2 instances in the particular AWS account. 402 403| Method | Path | 404| :----- | :--------------------------------- | 405| `POST` | `/auth/aws/config/sts/:account_id` | 406 407### Parameters 408 409- `account_id` `(string: <required>)` - AWS account ID to be associated with 410 STS role. If set, Vault will use assumed credentials to verify any login 411 attempts from EC2 instances in this account. 412- `sts_role` `(string: <required>)` - AWS ARN for STS role to be assumed when 413 interacting with the account specified. The Vault server must have 414 permissions to assume this role. 415 416### Sample Payload 417 418```json 419{ 420 "sts_role": "arn:aws:iam:111122223333:role/myRole" 421} 422``` 423 424### Sample Request 425 426```shell-session 427$ curl \ 428 --header "X-Vault-Token: ..." \ 429 --request POST \ 430 --data @payload.json \ 431 http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333 432``` 433 434## Read STS Role 435 436Returns the previously configured STS role. 437 438| Method | Path | 439| :----- | :--------------------------------- | 440| `GET` | `/auth/aws/config/sts/:account_id` | 441 442### Parameters 443 444- `account_id` `(string: <required>)` - AWS account ID that has been 445 previously associated with STS role. 446 447### Sample Request 448 449```shell-session 450$ curl \ 451 --header "X-Vault-Token: ..." \ 452 http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333 453``` 454 455### Sample Response 456 457```json 458{ 459 "data": { 460 "sts_role ": "arn:aws:iam:111122223333:role/myRole" 461 } 462} 463``` 464 465## List STS Roles 466 467Lists all the AWS Account IDs for which an STS role is registered. 468 469| Method | Path | 470| :----- | :--------------------- | 471| `LIST` | `/auth/aws/config/sts` | 472 473### Sample Request 474 475```shell-session 476$ curl \ 477 --header "X-Vault-Token: ..." \ 478 --request LIST \ 479 http://127.0.0.1:8200/v1/auth/aws/config/sts 480``` 481 482### Sample Response 483 484```json 485{ 486 "data": { 487 "keys": ["111122223333", "999988887777"] 488 } 489} 490``` 491 492## Delete STS Role 493 494Deletes a previously configured AWS account/STS role association. 495 496| Method | Path | 497| :------- | :--------------------------------- | 498| `DELETE` | `/auth/aws/config/sts/:account_id` | 499 500### Parameters 501 502- `account_id` `(string: <required>)` - AWS account ID that has been 503 previously associated with STS role. 504 505### Sample Request 506 507```shell-session 508$ curl \ 509 --header "X-Vault-Token: ..." \ 510 --request DELETE \ 511 http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333 512``` 513 514## Configure Identity Access List Tidy Operation 515 516Configures the periodic tidying operation of the access listed identity entries. 517 518| Method | Path | 519| :----- | :------------------------------------------ | 520| `POST` | `/auth/aws/config/tidy/identity-accesslist` | 521 522### Parameters 523 524- `safety_buffer` `(string: "72h")` - The amount of extra time that must have 525 passed beyond the `roletag` expiration, before it is removed from the method 526 storage. Defaults to 72h. 527- `disable_periodic_tidy` `(bool: false)` - If set to 'true', disables the 528 periodic tidying of the `identity-accesslist/<instance_id>` entries. 529 530### Sample Payload 531 532```json 533{ 534 "safety_buffer": "48h" 535} 536``` 537 538### Sample Request 539 540```shell-session 541$ curl \ 542 --header "X-Vault-Token: ..." \ 543 --request POST \ 544 --data @payload.json \ 545 http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist 546``` 547 548## Read Identity Access List Tidy Settings 549 550Returns the previously configured periodic access list tidying settings. 551 552| Method | Path | 553| :----- | :------------------------------------------ | 554| `GET` | `/auth/aws/config/tidy/identity-accesslist` | 555 556### Sample Request 557 558```shell-session 559$ curl \ 560 --header "X-Vault-Token: ..." \ 561 http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist 562``` 563 564### Sample Response 565 566```json 567{ 568 "data": { 569 "safety_buffer": 600, 570 "disable_periodic_tidy": false 571 } 572} 573``` 574 575## Delete Identity Access List Tidy Settings 576 577Deletes the previously configured periodic access list tidying settings. 578 579| Method | Path | 580| :------- | :------------------------------------------ | 581| `DELETE` | `/auth/aws/config/tidy/identity-accesslist` | 582 583### Sample Request 584 585```shell-session 586$ curl \ 587 --header "X-Vault-Token: ..." \ 588 --request DELETE \ 589 http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist 590``` 591 592## Configure Role Tag Deny List Tidy Operation 593 594Configures the periodic tidying operation of the deny listed role tag entries. 595 596| Method | Path | 597| :----- | :--------------------------------------- | 598| `POST` | `/auth/aws/config/tidy/roletag-denylist` | 599 600### Parameters 601 602- `safety_buffer` `(string: "72h")` - The amount of extra time that must have 603 passed beyond the `roletag` expiration, before it is removed from the method 604 storage. Defaults to 72h. 605- `disable_periodic_tidy` `(bool: false)` - If set to 'true', disables the 606 periodic tidying of the `roletag-denylist/<instance_id>` entries. 607 608### Sample Payload 609 610```json 611{ 612 "safety_buffer": "48h" 613} 614``` 615 616### Sample Request 617 618```shell-session 619$ curl \ 620 --header "X-Vault-Token: ..." \ 621 --request POST \ 622 --data @payload.json \ 623 http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist 624``` 625 626## Read Role Tag Deny List Tidy Settings 627 628Returns the previously configured periodic deny list tidying settings. 629 630| Method | Path | 631| :----- | :--------------------------------------- | 632| `GET` | `/auth/aws/config/tidy/roletag-denylist` | 633 634### Sample Request 635 636```shell-session 637$ curl \ 638 --header "X-Vault-Token: ..." \ 639 http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist 640``` 641 642### Sample Response 643 644```json 645{ 646 "data": { 647 "safety_buffer": 600, 648 "disable_periodic_tidy": false 649 } 650} 651``` 652 653## Delete Role Tag Deny List Tidy Settings 654 655Deletes the previously configured periodic deny list tidying settings. 656 657| Method | Path | 658| :------- | :--------------------------------------- | 659| `DELETE` | `/auth/aws/config/tidy/roletag-denylist` | 660 661### Sample Request 662 663```shell-session 664$ curl \ 665 --header "X-Vault-Token: ..." \ 666 --request DELETE \ 667 http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist 668``` 669 670## Create Role 671 672Registers a role in the method. Only those instances or principals which 673are using the role registered using this endpoint, will be able to perform 674the login operation. Constraints can be specified on the role, that are 675applied on the instances or principals attempting to login. At least one 676constraint must be specified on the role. The available constraints you 677can choose are dependent on the `auth_type` of the role and, if the 678`auth_type` is `iam`, then whether inferencing is enabled. A role will not 679let you configure a constraint if it is not checked by the `auth_type` and 680inferencing configuration of that role. For the constraints which accept a list 681of values, the authenticating instance/principal must match any one value in the 682list in order to satisfy that constraint. 683 684| Method | Path | 685| :----- | :--------------------- | 686| `POST` | `/auth/aws/role/:role` | 687 688### Parameters 689 690- `role` `(string: <required>)` - Name of the role. Vault normalizes all role 691 names to lower case. If you create two roles, "Web-Workers" and "WEB-WORKERS", 692 they will both be normalized to "web-workers" and will be regarded as the same role. 693 This is to prevent unexpected behavior due to casing differences. At all points, 694 Vault can be provided the role in any casing, and it will internally handle 695 sending it to lower case and seeking it inside its storage engine. 696- `auth_type` `(string: "iam")` - The auth type permitted for this role. Valid 697 choices are "ec2" or "iam". If no value is specified, then it will default to 698 "iam" (except for legacy `aws-ec2` auth types, for which it will default to 699 "ec2"). Only those bindings applicable to the auth type chosen will be allowed 700 to be configured on the role. 701- `bound_ami_id` `(list: [])` - If set, defines a constraint on the EC2 702 instances that they should be using one of the AMI ID specified by this parameter. 703 This constraint is checked during ec2 auth as well as the iam auth method only 704 when inferring an EC2 instance. This is a comma-separated string or JSON 705 array. 706- `bound_account_id` `(list: [])` - If set, defines a constraint on the EC2 707 instances that the account ID in its identity document to match one of the ones 708 specified by this parameter. This constraint is checked during ec2 auth as 709 well as the iam auth method only when inferring an EC2 instance. This is a 710 comma-separated string or JSON array. 711- `bound_region` `(list: [])` - If set, defines a constraint on the EC2 712 instances that the region in its identity document must match one of the 713 regions specified by this parameter. This constraint is only checked by the ec2 auth 714 method as well as the iam auth method only when inferring an ec2 instance. 715 This is a comma-separated string or JSON array. 716- `bound_vpc_id` `(list: [])` - If set, defines a constraint on the EC2 717 instance to be associated with a VPC ID that matches one of the values specified by 718 this parameter. This constraint is only checked by the ec2 auth method as well 719 as the iam auth method only when inferring an ec2 instance. This is a 720 comma-separated string or JSON array. 721- `bound_subnet_id` `(list: [])` - If set, defines a constraint on the EC2 722 instance to be associated with a subnet ID that matches one of the values specified 723 by this parameter. This constraint is only checked by the ec2 auth method as 724 well as the iam auth method only when inferring an ec2 instance. This is a 725 comma-separated string or a JSON array. 726- `bound_iam_role_arn` `(list: [])` - If set, defines a constraint on the 727 authenticating EC2 instance that it must match one of the IAM role ARNs specified by 728 this parameter. Wildcards are supported at the end of the ARN to allow for 729 prefix matching. The configured IAM user or EC2 instance role must be allowed to 730 execute the `iam:GetInstanceProfile` action if this is specified. This 731 constraint is checked by the ec2 auth method as well as the iam auth method 732 only when inferring an EC2 instance. This is a comma-separated string or a 733 JSON array. 734- `bound_iam_instance_profile_arn` `(list: [])` - If set, defines a constraint 735 on the EC2 instances to be associated with an IAM instance profile ARN. 736 Wildcards are supported at the end of the ARN to allow for prefix matching. 737 This constraint is 738 checked by the ec2 auth method as well as the iam auth method only when 739 inferring an ec2 instance. This is a comma-separated string or a JSON array. 740- `bound_ec2_instance_id` `(list: [])` - If set, defines a constraint on the 741 EC2 instances to have one of these instance IDs. This constraint is checked by 742 the ec2 auth method as well as the iam auth method only when inferring an ec2 743 instance. This is a comma-separated string or a JSON array. 744- `role_tag` `(string: "")` - If set, enables the role tags for this role. The 745 value set for this field should be the 'key' of the tag on the EC2 instance. 746 The 'value' of the tag should be generated using `role/<role>/tag` endpoint. 747 Defaults to an empty string, meaning that role tags are disabled. This 748 constraint is valid only with the ec2 auth method and is not allowed when 749 `auth_type` is iam. 750- `bound_iam_principal_arn` `(list: [])` - Defines the list of IAM principals 751 that are permitted to login to the role using the iam auth method. Individual 752 values should look like "arn:aws:iam::123456789012:user/MyUserName" or 753 "arn:aws:iam::123456789012:role/MyRoleName". Wildcards are supported at the 754 end of the ARN, e.g., "arn:aws:iam::123456789012:\*" will match any IAM 755 principal in the AWS account 123456789012. When `resolve_aws_unique_ids` is 756 `false` and you are binding to IAM roles (as opposed to users) and you are not 757 using a wildcard at the end, then you must specify the ARN by omitting any 758 path component; see the documentation for `resolve_aws_unique_ids` below. 759 This constraint is only checked by 760 the iam auth method. Wildcards are supported at the end of the ARN, e.g., 761 "arn:aws:iam::123456789012:role/\*" will match all roles in the AWS account. 762 This is a comma-separated string or JSON array. 763- `inferred_entity_type` `(string: "")` - When set, instructs Vault to turn on 764 inferencing. The only current valid value is "ec2_instance" instructing Vault 765 to infer that the role comes from an EC2 instance in an IAM instance profile. 766 This only applies to the iam auth method. If you set this on an existing role 767 where it had not previously been set, tokens that had been created prior will 768 not be renewable; clients will need to get a new token. 769- `inferred_aws_region` `(string: "")` - When role inferencing is activated, the 770 region to search for the inferred entities (e.g., EC2 instances). Required if 771 role inferencing is activated. This only applies to the iam auth method. 772- `resolve_aws_unique_ids` `(bool: true)` - When set, resolves the 773 `bound_iam_principal_arn` to the 774 [AWS Unique ID](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers#identifiers-unique-ids) 775 for the bound principal ARN. This field is ignored when 776 `bound_iam_principal_arn` ends with a wildcard character. 777 This requires Vault to be able to call `iam:GetUser` or `iam:GetRole` on the 778 `bound_iam_principal_arn` that is being bound. Resolving to internal AWS IDs 779 more closely mimics the behavior of AWS services in that if an IAM user or 780 role is deleted and a new one is recreated with the same name, those new users 781 or roles won't get access to roles in Vault that were permissioned to the 782 prior principals of the same name. The default value for new roles is true, 783 while the default value for roles that existed prior to this option existing 784 is false (you can check the value for a given role using the GET method on the 785 role). Any authentication tokens created prior to this being supported won't 786 verify the unique ID upon token renewal. When this is changed from false to 787 true on an existing role, Vault will attempt to resolve the role's bound IAM 788 ARN to the unique ID and, if unable to do so, will fail to enable this option. 789 Changing this from `true` to `false` is not supported; if absolutely 790 necessary, you would need to delete the role and recreate it explicitly 791 setting it to `false`. However; the instances in which you would want to do 792 this should be rare. If the role creation (or upgrading to use this) succeed, 793 then Vault has already been able to resolve internal IDs, and it doesn't need 794 any further IAM permissions to authenticate users. If a role has been deleted 795 and recreated, and Vault has cached the old unique ID, you should just call 796 this endpoint specifying the same `bound_iam_principal_arn` and, as long as 797 Vault still has the necessary IAM permissions to resolve the unique ID, Vault 798 will update the unique ID. (If it does not have the necessary permissions to 799 resolve the unique ID, then it will fail to update.) If this option is set to 800 false, then you MUST leave out the path component in `bound_iam_principal_arn` 801 for **roles** that do not specify a wildcard at the end, but not IAM users or 802 role bindings that have a wildcard. That is, if your IAM role ARN is of the 803 form `arn:aws:iam::123456789012:role/some/path/to/MyRoleName`, and 804 `resolve_aws_unique_ids` is `false`, you **must** specify a 805 `bound_iam_principal_arn` of `arn:aws:iam::123456789012:role/MyRoleName` for 806 authentication to work. 807- `allow_instance_migration` `(bool: false)` - If set, allows migration of the 808 underlying instance where the client resides. This keys off of pendingTime in 809 the metadata document, so essentially, this disables the client nonce check 810 whenever the instance is migrated to a new host and pendingTime is newer than 811 the previously-remembered time. Use with caution. This only applies to 812 authentications via the ec2 auth method. This is mutually exclusive with 813 `disallow_reauthentication`. 814- `disallow_reauthentication` `(bool: false)` - If set, only allows a single 815 token to be granted per instance ID. In order to perform a fresh login, the 816 entry in the access list for the instance ID needs to be cleared using 817 `auth/aws/identity-accesslist/<instance_id>` endpoint. Defaults to 'false'. 818 This only applies to authentications via the ec2 auth method. This is mutually 819 exclusive with `allow_instance_migration`. 820 821@include 'tokenfields.mdx' 822 823### Sample Payload 824 825```json 826{ 827 "bound_ami_id": ["ami-fce36987"], 828 "bound_ec2_instance_id": ["i-12345678901234567"], 829 "role_tag": "", 830 "policies": ["default", "dev", "prod"], 831 "max_ttl": 1800000, 832 "disallow_reauthentication": false, 833 "allow_instance_migration": false 834} 835``` 836 837### Sample Request 838 839```shell-session 840$ curl \ 841 --header "X-Vault-Token: ..." \ 842 --request POST \ 843 --data @payload.json \ 844 http://127.0.0.1:8200/v1/auth/aws/role/dev-role 845``` 846 847## Read Role 848 849Returns the previously registered role configuration. 850 851| Method | Path | 852| :----- | :--------------------- | 853| `GET` | `/auth/aws/role/:role` | 854 855### Parameters 856 857- `role` `(string: <required>)` - Name of the role. 858 859### Sample Request 860 861```shell-session 862$ curl \ 863 --header "X-Vault-Token: ..." \ 864 http://127.0.0.1:8200/v1/auth/aws/role/dev-role 865``` 866 867### Sample Response 868 869```json 870{ 871 "data": { 872 "bound_ami_id": ["ami-fce36987"], 873 "role_tag": "", 874 "policies": ["default", "dev", "prod"], 875 "max_ttl": 1800000, 876 "disallow_reauthentication": false, 877 "allow_instance_migration": false 878 } 879} 880``` 881 882## List Roles 883 884Lists all the roles that are registered with the method. 885 886| Method | Path | 887| :----- | :---------------- | 888| `LIST` | `/auth/aws/roles` | 889 890### Sample Request 891 892```shell-session 893$ curl \ 894 --header "X-Vault-Token: ..." \ 895 --request LIST \ 896 http://127.0.0.1:8200/v1/auth/aws/roles 897``` 898 899### Sample Response 900 901```json 902{ 903 "data": { 904 "keys": ["dev-role", "prod-role"] 905 } 906} 907``` 908 909## Delete Role 910 911Deletes the previously registered role. 912 913| Method | Path | 914| :------- | :--------------------- | 915| `DELETE` | `/auth/aws/role/:role` | 916 917### Parameters 918 919- `role` `(string: <required>)` - Name of the role. 920 921### Sample Request 922 923```shell-session 924$ curl \ 925 --header "X-Vault-Token: ..." \ 926 --request DELETE \ 927 http://127.0.0.1:8200/v1/auth/aws/role/dev-role 928``` 929 930## Create Role Tags 931 932Creates a role tag on the role, which help in restricting the capabilities 933that are set on the role. Role tags are not tied to any specific ec2 934instance unless specified explicitly using the `instance_id` parameter. By 935default, role tags are designed to be used across all instances that 936satisfies the constraints on the role. Regardless of which instances have 937role tags on them, capabilities defined in a role tag must be a strict 938subset of the given role's capabilities. Note that, since adding and 939removing a tag is often a widely distributed privilege, care needs to be 940taken to ensure that the instances are attached with correct tags to not 941let them gain more privileges than what were intended. If a role tag is 942changed, the capabilities inherited by the instance will be those defined 943on the new role tag. Since those must be a subset of the role 944capabilities, the role should never provide more capabilities than any 945given instance can be allowed to gain in a worst-case scenario. 946 947| Method | Path | 948| :----- | :------------------------- | 949| `POST` | `/auth/aws/role/:role/tag` | 950 951### Parameters 952 953- `role` `(string: <required>)` - Name of the role. 954- `policies` `(array: [])` - Policies to be associated with the tag. If set, 955 must be a subset of the role's policies. If set, but set to an empty value, 956 only the 'default' policy will be given to issued tokens. 957- `max_ttl` `(string: "")` - The maximum allowed lifetime of tokens issued using 958 this role. 959- `instance_id` `(string: "")` - Instance ID for which this tag is intended for. 960 If set, the created tag can only be used by the instance with the given ID. 961- `allow_instance_migration` `(bool: false)` - If set, allows migration of the 962 underlying instance where the client resides. This keys off of pendingTime in 963 the metadata document, so essentially, this disables the client nonce check 964 whenever the instance is migrated to a new host and pendingTime is newer than 965 the previously-remembered time. Use with caution. Defaults to 'false'. 966 Mutually exclusive with `disallow_reauthentication`. 967- `disallow_reauthentication` `(bool: false)` - If set, only allows a single 968 token to be granted per instance ID. This can be cleared with the 969 auth/aws/identity-accesslist endpoint. Defaults to 'false'. Mutually exclusive 970 with `allow_instance_migration`. 971 972### Sample Payload 973 974```json 975{ 976 "policies": ["default", "dev-api"] 977} 978``` 979 980### Sample Request 981 982```shell-session 983$ curl \ 984 --header "X-Vault-Token: ..." \ 985 --request POST \ 986 --data @payload.json \ 987 http://127.0.0.1:8200/v1/auth/aws/role/dev-api-and-web-role/tag 988``` 989 990### Sample Response 991 992```json 993{ 994 "data": { 995 "tag_value": "v1:09Vp0qGuyB8=:r=dev-role:p=default,dev-api:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/pJIdVyOI=", 996 "tag_key": "VaultRole" 997 } 998} 999``` 1000 1001## Login 1002 1003Fetch a token. This endpoint verifies the pkcs7 signature of the instance 1004identity document or the signature of the signed GetCallerIdentity request. 1005With the ec2 auth method, or when inferring an EC2 instance, verifies that 1006the instance is actually in a running state. Cross checks the constraints 1007defined on the role with which the login is being performed. With the ec2 1008auth method, as an alternative to pkcs7 signature, the identity document 1009along with its RSA digest can be supplied to this endpoint. 1010 1011| Method | Path | 1012| :----- | :---------------- | 1013| `POST` | `/auth/aws/login` | 1014 1015### Sample Payload 1016 1017- `role` `(string: "")` - Name of the role against which the login is being 1018 attempted. If `role` is not specified, then the login endpoint looks for a 1019 role bearing the name of the AMI ID of the EC2 instance that is trying to 1020 login if using the ec2 auth method, or the "friendly name" (i.e., role name or 1021 username) of the IAM principal authenticated. If a matching role is not found, 1022 login fails. 1023- `identity` `(string: <required-ec2>)` - Base64 encoded EC2 instance identity 1024 document. This needs to be supplied along with the `signature` parameter. If 1025 using `curl` for fetching the identity document, consider using the option 1026 `-w 0` while piping the output to `base64` binary. 1027- `signature` `(string: <required-ec2>)` - Base64 encoded SHA256 RSA signature of 1028 the instance identity document. This needs to be supplied along with 1029 `identity` parameter when using the ec2 auth method. 1030- `pkcs7` `(string: <required-ec2>)` - PKCS7 signature of the identity document with 1031 all `\n` characters removed. Either this needs to be set _OR_ both `identity` 1032 and `signature` need to be set when using the ec2 auth method. 1033- `nonce` `(string: "")` - The nonce to be used for subsequent login requests. 1034 If this parameter is not specified at all and if reauthentication is allowed, 1035 then the method will generate a random nonce, attaches it to the instance's 1036 identity-accesslist entry and returns the nonce back as part of auth metadata. 1037 This value should be used with further login requests, to establish client 1038 authenticity. Clients can choose to set a custom nonce if preferred, in which 1039 case, it is recommended that clients provide a strong nonce. If a nonce is 1040 provided but with an empty value, it indicates intent to disable 1041 reauthentication. Note that, when `disallow_reauthentication` option is 1042 enabled on either the role or the role tag, the `nonce` holds no significance. 1043 This is ignored unless using the ec2 auth method. 1044- `iam_http_request_method` `(string: <required-iam>)` - HTTP method used in the 1045 signed request. Currently only POST is supported, but other methods may be 1046 supported in the future. This is required when using the iam auth method. 1047- `iam_request_url` `(string: <required-iam>)` - Base64-encoded HTTP URL used in 1048 the signed request. Most likely just `aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8=` 1049 (base64-encoding of `https://sts.amazonaws.com/`) as most requests will 1050 probably use POST with an empty URI. This is required when using the iam auth 1051 method. 1052- `iam_request_body` `(string: <required-iam>)` - Base64-encoded body of the 1053 signed request. Most likely 1054 `QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ==` which is the 1055 base64 encoding of `Action=GetCallerIdentity&Version=2011-06-15`. This is 1056 required when using the iam auth method. 1057- `iam_request_headers` `(string: <required-iam>)` - Key/value pairs of headers 1058 for use in the `sts:GetCallerIdentity` HTTP requests headers. Can be either a 1059 Base64-encoded, JSON-serialized string, or a JSON object of key/value pairs. The 1060 JSON serialization assumes that each header key maps to either a string value or 1061 an array of string values (though the length of that array will probably only be 1062 one). If the `iam_server_id_header_value` is configured in Vault for the aws 1063 auth mount, then the headers must include the X-Vault-AWS-IAM-Server-ID header, 1064 its value must match the value configured, and the header must be included in 1065 the signed headers. This is required when using the iam auth method. 1066 1067### Sample Payload 1068 1069```json 1070{} 1071``` 1072 1073### Sample Request 1074 1075```shell-session 1076$ curl \ 1077 --request POST \ 1078 --data @payload.json \ 1079 http://127.0.0.1:8200/v1/auth/aws/login 1080``` 1081 1082### Sample Response 1083 1084```json 1085{ 1086 "auth": { 1087 "renewable": true, 1088 "lease_duration": 1800000, 1089 "metadata": { 1090 "role_tag_max_ttl": "0", 1091 "instance_id": "i-de0f1344", 1092 "ami_id": "ami-fce36983", 1093 "role": "dev-role", 1094 "auth_type": "ec2" 1095 }, 1096 "policies": ["default", "dev"], 1097 "accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e", 1098 "client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a" 1099 } 1100} 1101``` 1102 1103## Place Role Tags in Deny List 1104 1105Places a valid role tag in a deny list. This ensures that the role tag 1106cannot be used by any instance to perform a login operation again. Note 1107that if the role tag was previously used to perform a successful login, 1108placing the tag in the deny list does not invalidate the already issued 1109token. 1110 1111| Method | Path | 1112| :----- | :------------------------------------- | 1113| `POST` | `/auth/aws/roletag-denylist/:role_tag` | 1114 1115### Parameters 1116 1117- `role_tag` `(string: <required>)` - Role tag to be deny listed. This is the `tag_value` returned when the role tag is 1118 created. The tag can be supplied as-is. In order to avoid any encoding problems, it can be base64 1119 encoded. 1120 1121### Sample Request 1122 1123```shell-session 1124$ curl \ 1125 --header "X-Vault-Token: ..." \ 1126 --request POST \ 1127 http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= 1128``` 1129 1130### Read Role Tag Deny List Information 1131 1132Returns the deny list entry of a previously deny listed role tag. 1133 1134| Method | Path | 1135| :----- | :------------------------------------- | 1136| `GET` | `/auth/aws/roletag-denylist/:role_tag` | 1137 1138### Parameters 1139 1140- `role_tag` `(string: <required>)` - Role tag to be deny listed. The tag can be 1141 supplied as-is. In order to avoid any encoding problems, it can be base64 1142 encoded. 1143 1144### Sample Request 1145 1146```shell-session 1147$ curl \ 1148 --header "X-Vault-Token: ..." \ 1149 http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= 1150``` 1151 1152### Sample Response 1153 1154```json 1155{ 1156 "data": { 1157 "expiration_time": "2016-04-25T10:35:20.127058773-04:00", 1158 "creation_time": "2016-04-12T22:35:01.178348124-04:00" 1159 } 1160} 1161``` 1162 1163## List Deny List Tags 1164 1165Lists all the role tags that are deny listed. 1166 1167| Method | Path | 1168| :----- | :--------------------------- | 1169| `LIST` | `/auth/aws/roletag-denylist` | 1170 1171### Sample Request 1172 1173```shell-session 1174$ curl \ 1175 --header "X-Vault-Token: ..." \ 1176 --request LIST \ 1177 http://127.0.0.1:8200/v1/auth/aws/roletag-denylist 1178``` 1179 1180### Sample Response 1181 1182```json 1183{ 1184 "data": { 1185 "keys": [ 1186 "v1:09Vp0qGuyB8=:a=ami-fce3c696:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/" 1187 ] 1188 } 1189} 1190``` 1191 1192## Delete Deny List Tags 1193 1194Deletes a deny listed role tag. 1195 1196| Method | Path | 1197| :------- | :------------------------------------- | 1198| `DELETE` | `/auth/aws/roletag-denylist/:role_tag` | 1199 1200### Parameters 1201 1202- `role_tag` `(string: <required>)` - Role tag to be deny listed. The tag can be 1203 supplied as-is. In order to avoid any encoding problems, it can be base64 1204 encoded. 1205 1206### Sample Request 1207 1208```shell-session 1209$ curl \ 1210 --header "X-Vault-Token: ..." \ 1211 --request DELETE \ 1212 http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= 1213``` 1214 1215## Tidy Deny List Tags 1216 1217Cleans up the entries in the deny listed based on expiration time on the entry and 1218`safety_buffer`. 1219 1220| Method | Path | 1221| :----- | :-------------------------------- | 1222| `POST` | `/auth/aws/tidy/roletag-denylist` | 1223 1224### Parameters 1225 1226- `safety_buffer` `(string: "72h")` - The amount of extra time that must have 1227 passed beyond the `roletag` expiration, before it is removed from the method 1228 storage. Defaults to 72h. 1229 1230### Sample Request 1231 1232```shell-session 1233$ curl \ 1234 --header "X-Vault-Token: ..." \ 1235 --request POST \ 1236 http://127.0.0.1:8200/v1/auth/aws/tidy/roletag-denylist 1237``` 1238 1239### Read Identity Access List Information 1240 1241Returns an entry in the identity access list. An entry will be created/updated by every 1242successful login. 1243 1244| Method | Path | 1245| :----- | :------------------------------------------- | 1246| `GET` | `/auth/aws/identity-accesslist/:instance_id` | 1247 1248### Parameters 1249 1250- `instance_id` `(string: <required>)` - EC2 instance ID. A successful login 1251 operation from an EC2 instance gets cached in th access list, keyed off of 1252 instance ID. 1253 1254### Sample Request 1255 1256```shell-session 1257$ curl \ 1258 --header "X-Vault-Token: ..." \ 1259 http://127.0.0.1:8200/v1/auth/aws/identity-accesslist/i-aab47d37 1260``` 1261 1262### Sample Response 1263 1264```json 1265{ 1266 "data": { 1267 "pending_time": "2016-04-14T01:01:41Z", 1268 "expiration_time": "2016-05-05 10:09:16.67077232 +0000 UTC", 1269 "creation_time": "2016-04-14 14:09:16.67077232 +0000 UTC", 1270 "client_nonce": "5defbf9e-a8f9-3063-bdfc-54b7a42a1f95", 1271 "role": "dev-role" 1272 } 1273} 1274``` 1275 1276## List Identity Access List Entries 1277 1278Lists all the instance IDs that are in the access list of successful logins. 1279 1280| Method | Path | 1281| :----- | :------------------------------ | 1282| `LIST` | `/auth/aws/identity-accesslist` | 1283 1284### Sample Request 1285 1286```shell-session 1287$ curl \ 1288 --header "X-Vault-Token: ..." \ 1289 --request LIST \ 1290 http://127.0.0.1:8200/v1/auth/aws/identity-accesslist 1291``` 1292 1293### Sample Response 1294 1295```json 1296{ 1297 "data": { 1298 "keys": ["i-aab47d37"] 1299 } 1300} 1301``` 1302 1303## Delete Identity Access List Entries 1304 1305Deletes a cache of the successful login from an instance. 1306 1307| Method | Path | 1308| :------- | :------------------------------------------- | 1309| `DELETE` | `/auth/aws/identity-accesslist/:instance_id` | 1310 1311### Parameters 1312 1313- `instance_id` `(string: <required>)` - EC2 instance ID. A successful login 1314 operation from an EC2 instance gets cached in this access list, keyed off of 1315 instance ID. 1316 1317### Sample Request 1318 1319```shell-session 1320$ curl \ 1321 --header "X-Vault-Token: ..." \ 1322 --request DELETE \ 1323 http://127.0.0.1:8200/v1/auth/aws/identity-accesslist/i-aab47d37 1324``` 1325 1326## Tidy Identity Access List Entries 1327 1328Cleans up the entries in the access list based on expiration time and 1329`safety_buffer`. 1330 1331| Method | Path | 1332| :----- | :----------------------------------- | 1333| `POST` | `/auth/aws/tidy/identity-accesslist` | 1334 1335### Parameters 1336 1337- `safety_buffer` `(string: "72h")` - The amount of extra time that must have 1338 passed beyond the `roletag` expiration, before it is removed from the method 1339 storage. Defaults to 72h. 1340 1341### Sample Request 1342 1343```shell-session 1344$ curl \ 1345 --header "X-Vault-Token: ..." \ 1346 --request POST \ 1347 http://127.0.0.1:8200/v1/auth/aws/tidy/identity-accesslist 1348``` 1349 1350## Deprecations effective in Vault 1.7 1351 1352Vault 1.7 introduced new URLs for a number of AWS Auth APIs. The previous 1353URLs are deprecated. The affected APIs include: 1354 1355| Current | Deprecated in 1.7 | 1356| :------------------------------------------ | :----------------------------------------- | 1357| `/auth/aws/roletag-denylist` | `/auth/aws/roletag-blacklist` | 1358| `/auth/aws/identity-accesslist` | `/auth/aws/identity-whitelist` | 1359| `/auth/aws/tidy/identity-accesslist` | `/auth/aws/tidy/identity-whitelist` | 1360| `/auth/aws/tidy/roletag-denylist` | `/auth/aws/tidy/roletag-blacklist` | 1361| `/auth/aws/config/tidy/identity-accesslist` | `/auth/aws/config/tidy/identity-whitelist` | 1362| `/auth/aws/config/tidy/roletag-denylist` | `/auth/aws/config/tidy/roletag-blacklist` | 1363