Note
This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround starting in Vault 1.12. Refer to the deprecation notices for more information.
This is the API documentation for the Vault AWS auth method. For general information about the usage and operation of the AWS method, please see the Vault AWS method documentation.
This documentation assumes the AWS method is mounted at the /auth/aws
path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly.
Vault 1.7 deprecated several AWS Auth URLs. The full list of affected endpoints and their replacements is provided at the end of this document.
Configures the credentials required to perform API calls to AWS as well as custom endpoints to talk to AWS APIs. The instance identity document fetched from the PKCS#7 signature will provide the EC2 instance ID. The credentials configured using this endpoint will be used to query the status of the instances via DescribeInstances API. If static credentials are not provided using this endpoint, or plugin workload identity federation credentials are also not provided, then the credentials will be retrieved from the environment variables AWS_ACCESS_KEY
, AWS_SECRET_KEY
and AWS_REGION
respectively. If the credentials are still not found and if the method is configured on an EC2 instance with metadata querying capabilities, the credentials are fetched automatically.
POST
/auth/aws/config/client
Parameters
max_retries
(int: -1)
- Number of max retries the client should use for recoverable errors. The default (-1
) falls back to the AWS SDK's default behavior.access_key
(string: "")
- AWS Access key with permissions to query AWS APIs. The permissions required depend on the specific configurations. If using the iam
auth method without inferencing, then no credentials are necessary. If using the ec2
auth method or using the iam
auth method with inferencing, then these credentials need access to ec2:DescribeInstances
. If additionally a bound_iam_role
is specified, then these credentials also need access to iam:GetInstanceProfile
. If, however, an alternate sts configuration is set for the target account, then the credentials must be permissioned to call sts:AssumeRole
on the configured role, and that role must have the permissions described here. Mutually exclusive with identity_token_audience
.secret_key
(string: "")
- AWS Secret key with permissions to query AWS APIs.role_arn
(string: "")
– Enterprise Enterprise Role ARN to assume for plugin workload identity federation. Required with identity_token_audience
.identity_token_audience
(string: "")
- Enterprise Enterprise The audience claim value for plugin identity tokens. Must match an allowed audience configured for the target IAM OIDC identity provider. Mutually exclusive with access_key
.identity_token_ttl
(string/int: 3600)
- Enterprise Enterprise The TTL of generated tokens. Defaults to 1 hour. Uses duration format strings.endpoint
(string: "")
- URL to override the default generated endpoint for making AWS EC2 API calls.iam_endpoint
(string: "")
- URL to override the default generated endpoint for making AWS IAM API calls.sts_endpoint
(string: "")
- URL to override the default generated endpoint for making AWS STS API calls. If set, sts_region
should also be set.sts_region
(string: "")
- Region to override the default region for making AWS STS API calls. Should only be set if sts_endpoint
is set. If so, should be set to the region in which the custom sts_endpoint
resides.use_sts_region_from_client
(boolean: false)
- If set, overrides both sts_endpoint
and sts_region
to instead use the region specified in the client request headers for IAM-based authentication . This can be useful when you have client requests coming from different regions and want flexibility in which regional STS API is used.iam_server_id_header_value
(string: "")
- The value to require in the X-Vault-AWS-IAM-Server-ID
header as part of GetCallerIdentity requests that are used in the iam auth method. If not set, then no value is required or validated. If set, clients must include an X-Vault-AWS-IAM-Server-ID header in the headers of login requests, and further this header must be among the signed headers validated by AWS. This is to protect against different types of replay attacks, for example a signed request sent to a dev server being resent to a production server. Consider setting this to the Vault server's DNS name.allowed_sts_header_values
(string: "")
A comma separated list of additional request headers permitted when providing the iam_request_headers for an IAM based login call. In any case, a default list of headers AWS STS expects for a GetCallerIdentity are allowed.rotation_period
(string/integer: 0)
– Enterprise Enterprise The amount of time, in seconds, Vault should wait before rotating the root credential. A zero value tells Vault not to rotate the root credential. The minimum rotation period is 10 seconds. You must set one of rotation_period
or rotation_schedule
, but cannot set both.rotation_schedule
(string: "")
– Enterprise Enterprise The schedule, in cron-style time format, defining the schedule on which Vault should rotate the root token. Standard cron-style time format uses five fields to define the minute, hour, day of month, month, and day of week respectively. For example, 0 0 * * SAT
tells Vault to rotate the root token every Saturday at 00:00. You must set one of rotation_schedule
or rotation_period
, but cannot set both.rotation_window
(string/integer: 0)
– Enterprise Enterprise The maximum amount of time, in seconds, allowed to complete a rotation when a scheduled token rotation occurs. If Vault cannot rotate the token within the window (for example, due to a failure), Vault must wait to try again until the next scheduled rotation. The default rotation window is unbound and the minimum allowable window is 1 hour. You cannot set a rotation window when using rotation_period
.disable_automated_rotation
(bool: false)
- Enterprise Enterprise Cancels all upcoming rotations of the root credential until unset.{
"access_key": "VKIAJBRHKH6EVTTNXDHA",
"secret_key": "vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj"
}
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/config/client
Returns the previously configured AWS access credentials.
Method PathGET
/auth/aws/config/client
Sample request
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/aws/config/client
Sample response
{
"data": {
"access_key": "VKIAJBRHKH6EVTTNXDHA",
"endpoint": "",
"iam_endpoint": "",
"sts_endpoint": "",
"sts_region": "",
"use_sts_region_from_client": false,
"iam_server_id_header_value": ""
}
}
Deletes the previously configured AWS access credentials.
Method PathDELETE
/auth/aws/config/client
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/aws/config/client
When you have configured Vault with static credentials, you can use this endpoint to have Vault rotate the access key it used. Note that, due to AWS eventual consistency, after calling this endpoint, subsequent calls from Vault to AWS may fail for a few seconds until AWS becomes consistent again.
In order to call this endpoint, Vault's AWS access key MUST be the only access key on the IAM user; otherwise, generation of a new access key will fail. Once this method is called, Vault will now be the only entity that knows the AWS secret key is used to access AWS.
Method PathPOST
/auth/aws/config/rotate-root
Parameters
There are no parameters to this operation.
Sample request --header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/auth/aws/config/rotate-root
Sample response
{
"data": {
"access_key": "AKIA..."
}
}
The new access key Vault uses is returned by this operation.
This configures the way that Vault interacts with the Identity store. The default (as of Vault 1.0.3) is role_id
for both values.
POST
/auth/aws/config/identity
Parameters
iam_alias
(string: "role_id")
- How to generate the identity alias when using the iam
auth method. Valid choices are role_id
, unique_id
, canonical_arn
and full_arn
. When role_id
is selected, the randomly generated ID of the Vault role is used. When unique_id
is selected, the IAM Unique ID of the IAM principal (either the user or role) is used as the identity alias name. When canonical_arn
is selected, the role ARN returned by the sts:GetCallerIdentity
call will be used. This will be arn:aws:iam::<account_id>:role/<role name>
. When full_arn
is selected, the ARN returned by the sts:GetCallerIdentity
call is used as the alias name. This is either arn:aws:iam::<account_id>:user/<optional_path/><user_name>
or arn:aws:sts::<account_id>:assumed-role/<role_name_without_path>/<role_session_name>
. Note: if you select canonical_arn
or full_arn
and then delete and recreate the IAM role, Vault won't be aware and any identity aliases set up for the role name will still be valid.
iam_metadata
(string: "default")
- The metadata to include on the token returned by the login
endpoint. This metadata will be added to both audit logs, and on the iam_alias
. By default, it includes account_id
and auth_type
. Additionally, canonical_arn
, client_arn
, client_user_id
, inferred_aws_region
, inferred_entity_id
, and inferred_entity_type
are available. To include no metadata, set to ""
via the CLI or []
via the API. To use only particular fields, select the explicit fields. To restore to defaults, send only a field of default
. Only select fields that will have a low rate of change for your iam_alias
because each change triggers a storage write and can have a performance impact at scale.
ec2_alias
(string: "role_id")
- Configures how to generate the identity alias when using the ec2
auth method. Valid choices are role_id
, instance_id
, and image_id
. When role_id
is selected, the randomly generated ID of the Vault role is used. When instance_id
is selected, the instance identifier is used as the identity alias name. When image_id
is selected, AMI ID of the instance is used as the identity alias name.
ec2_metadata
(string: "default")
- The metadata to include on the token returned by the login
endpoint. This metadata will be added to both audit logs, and on the ec2_alias
. By default, it includes account_id
and auth_type
. Additionally, ami_id
, instance_id
, and region
, are available. To include no metadata, set to ""
via the CLI or []
via the API. To use only particular fields, select the explicit fields. To restore to defaults, send only a field of default
. Only select fields that will have a low rate of change for your ec2_alias
because each change triggers a storage write and can have a performance impact at scale.
{
"iam_alias": "unique_id"
}
Sample request
$ curl \
-- header "X-Vault-Token:..." \
--request POST
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/config/identity
Returns the previously configured Identity integration configuration
Method PathGET
/auth/aws/config/identity
Sample request
$ curl \
--header "X-Vault-Token:..." \
http://127.0.0.1:8200/v1/auth/aws/config/identity
Sample response
{
"data": {
"iam_alias": "full_arn"
}
}
Registers an AWS public key to be used to verify the instance identity documents. Indicate the type of the public key using the type
parameter. Vault has the default documented set of AWS certificates built-in.
The pkcs7
type is used to verify PKCS#7 signatures from the AWS http://169.254.169.254/latest/dynamic/instance-identity/pkcs7
and http://169.254.169.254/latest/dynamic/instance-identity/rsa2048
endpoints. Vault does not support X.509 certificates with SHA-1 signatures. If you use AWS /rsa2048
signature endpoint credentials, you must use the pkcs7
login flow.
The identity
type is used to verify signatures from the http://169.254.169.254/latest/dynamic/instance-identity/document
and http://169.254.169.254/latest/dynamic/instance-identity/signature
endpoints.
See the AWS docs for more information on the signature types and the corresponding certificates.
Method PathPOST
/auth/aws/config/certificate/:cert_name
Parameters
cert_name
(string: <required>)
- Name of the certificate.aws_public_cert
(string: <required>)
- Base64-encoded AWS Public key required to verify PKCS#7 signature of the EC2 instance metadata.type
(string: "pkcs7")
- Takes the value of either "pkcs7" or "identity", indicating the type of document which can be verified using the given certificate. The PKCS#7 document can be a DSA digest from the /pkcs7 endpoint or an RSA-2048 signature from the /rsa2048 endpoint. The identity signature is used to validate RSA signatures from the /signature endpoint. Defaults to "pkcs7".{
"aws_public_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM3VENDQXEwQ0NRQ1d1a2paNVY0YVp6QUpCZ2NxaGtqT09BUURNRnd4Q3pBSkJnTlZCQVlUQWxWVE1Sa3cKRndZRFZRUUlFeEJYWVhOb2FXNW5kRzl1SUZOMFlYUmxNUkF3RGdZRFZRUUhFd2RUWldGMGRHeGxNU0F3SGdZRApWUVFLRXhkQmJXRjZiMjRnVjJWaUlGTmxjblpwWTJWeklFeE1RekFlRncweE1qQXhNRFV4TWpVMk1USmFGdzB6Ck9EQXhNRFV4TWpVMk1USmFNRnd4Q3pBSkJnTlZCQVlUQWxWVE1Sa3dGd1lEVlFRSUV4QlhZWE5vYVc1bmRHOXUKSUZOMFlYUmxNUkF3RGdZRFZRUUhFd2RUWldGMGRHeGxNU0F3SGdZRFZRUUtFeGRCYldGNmIyNGdWMlZpSUZObApjblpwWTJWeklFeE1RekNDQWJjd2dnRXNCZ2NxaGtqT09BUUJNSUlCSHdLQmdRQ2prdmNTMmJiMVZRNHl0LzVlCmloNU9PNmtLL24xTHpsbHI3RDhad3RRUDhmT0VwcDVFMm5nK0Q2VWQxWjFnWWlwcjU4S2ozbnNzU05wSTZiWDMKVnlJUXpLN3dMY2xuZC9Zb3pxTk5tZ0l5WmVjTjdFZ2xLOUlUSEpMUCt4OEZ0VXB0M1FieVlYSmRtVk1lZ042UApodmlZdDVKSC9uWWw0aGgzUGExSEpkc2tnUUlWQUxWSjNFUjExK0tvNHRQNm53dkh3aDYrRVJZUkFvR0JBSTFqCmsrdGtxTVZIdUFGY3ZBR0tvY1Rnc2pKZW02LzVxb216SnVLRG1iSk51OVF4dzNyQW90WGF1OFFlK01CY0psL1UKaGh5MUtIVnBDR2w5ZnVlUTJzNklMMENhTy9idXljVTFDaVlRazQwS05IQ2NIZk5pWmJkbHgxRTlycFVwN2JuRgpsUmEydjFudE1YM2NhUlZEZGJ0UEVXbWR4U0NZc1lGRGs0bVpyT0xCQTRHRUFBS0JnRWJtZXZlNWY4TElFL0dmCk1ObVA5Q001ZW92UU9HeDVobzhXcUQrYVRlYnMrazJ0bjkyQkJQcWVacXBXUmE1UC8ranJkS21sMXF4NGxsSFcKTVhyczNJZ0liNitoVUlCK1M4ZHo4L21tTzBicHI3NlJvWlZDWFlhYjJDWmVkRnV0N3FjM1dVSDkrRVVBSDVtdwp2U2VEQ09VTVlRUjdSOUxJTll3b3VISXppcVFZTUFrR0J5cUdTTTQ0QkFNREx3QXdMQUlVV1hCbGs0MHhUd1N3CjdIWDMyTXhYWXJ1c2U5QUNGQk5HbWRYMlpCclZOR3JOOU4yZjZST2swazlLCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K"
}
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert
Returns the previously configured AWS public key.
Method PathGET
/auth/aws/config/certificate/:cert_name
Parameters
cert_name
(string: <required>)
- Name of the certificate.$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert
Sample response
{
"data": {
"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",
"type": "pkcs7"
}
}
Removes the previously configured AWS public key.
Method PathDELETE
/auth/aws/config/certificate/:cert_name
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert
Lists all the AWS public certificates that are registered with the method.
Method PathLIST
/auth/aws/config/certificates
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/aws/config/certificates
Sample response
{
"data": {
"keys": ["cert1"]
}
}
Allows the explicit association of STS roles to satellite AWS accounts (i.e. those which are not the account in which the Vault server is running.) Vault will use credentials obtained by assuming these STS roles when validating IAM principals or EC2 instances in the particular AWS account.
Method PathPOST
/auth/aws/config/sts/:account_id
Parameters
account_id
(string: <required>)
- AWS account ID to be associated with STS role. If set, Vault will use assumed credentials to verify any login attempts from EC2 instances in this account.sts_role
(string: <required>)
- AWS ARN for STS role to be assumed when interacting with the account specified. The Vault server must have permissions to assume this role.external_id
(string: "")
- The external ID expected by the STS role. The associated STS role must be configured to require the external ID.{
"sts_role": "arn:aws:iam:111122223333:role/myRole"
}
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333
Returns the previously configured STS role.
Method PathGET
/auth/aws/config/sts/:account_id
Parameters
account_id
(string: <required>)
- AWS account ID that has been previously associated with STS role.$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333
Sample response
{
"data": {
"sts_role ": "arn:aws:iam:111122223333:role/myRole"
}
}
Lists all the AWS Account IDs for which an STS role is registered.
Method PathLIST
/auth/aws/config/sts
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/aws/config/sts
Sample response
{
"data": {
"keys": ["111122223333", "999988887777"]
}
}
Deletes a previously configured AWS account/STS role association.
Method PathDELETE
/auth/aws/config/sts/:account_id
Parameters
account_id
(string: <required>)
- AWS account ID that has been previously associated with STS role.$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333
Configures the periodic tidying operation of the access listed identity entries.
Method PathPOST
/auth/aws/config/tidy/identity-accesslist
Parameters
safety_buffer
(string: "72h")
- The amount of extra time that must have passed beyond the roletag
expiration, before it is removed from the method storage. Defaults to 72h.disable_periodic_tidy
(bool: false)
- If set to 'true', disables the periodic tidying of the identity-accesslist/<instance_id>
entries.{
"safety_buffer": "48h"
}
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist
Returns the previously configured periodic access list tidying settings.
Method PathGET
/auth/aws/config/tidy/identity-accesslist
Sample request
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist
Sample response
{
"data": {
"safety_buffer": 600,
"disable_periodic_tidy": false
}
}
Deletes the previously configured periodic access list tidying settings.
Method PathDELETE
/auth/aws/config/tidy/identity-accesslist
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist
Configures the periodic tidying operation of the deny listed role tag entries.
Method PathPOST
/auth/aws/config/tidy/roletag-denylist
Parameters
safety_buffer
(string: "72h")
- The amount of extra time that must have passed beyond the roletag
expiration, before it is removed from the method storage. Defaults to 72h.disable_periodic_tidy
(bool: false)
- If set to 'true', disables the periodic tidying of the roletag-denylist/<instance_id>
entries.{
"safety_buffer": "48h"
}
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist
Returns the previously configured periodic deny list tidying settings.
Method PathGET
/auth/aws/config/tidy/roletag-denylist
Sample request
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist
Sample response
{
"data": {
"safety_buffer": 600,
"disable_periodic_tidy": false
}
}
Deletes the previously configured periodic deny list tidying settings.
Method PathDELETE
/auth/aws/config/tidy/roletag-denylist
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist
Registers a role in the method. Only those instances or principals which are using the role registered using this endpoint, will be able to perform the login operation. Constraints can be specified on the role, that are applied on the instances or principals attempting to login. At least one constraint must be specified on the role. The available constraints you can choose are dependent on the auth_type
of the role and, if the auth_type
is iam
, then whether inferencing is enabled. A role will not let you configure a constraint if it is not checked by the auth_type
and inferencing configuration of that role. For the constraints which accept a list of values, the authenticating instance/principal must match any one value in the list in order to satisfy that constraint.
POST
/auth/aws/role/:role
Parameters
role
(string: <required>)
- Name of the role. Vault normalizes all role names to lower case. If you create two roles, "Web-Workers" and "WEB-WORKERS", they will both be normalized to "web-workers" and will be regarded as the same role. This is to prevent unexpected behavior due to casing differences. At all points, Vault can be provided the role in any casing, and it will internally handle sending it to lower case and seeking it inside its storage engine.auth_type
(string: "iam")
- The auth type permitted for this role. Valid choices are "ec2" or "iam". If no value is specified, then it will default to "iam" (except for legacy aws-ec2
auth types, for which it will default to "ec2"). Only those bindings applicable to the auth type chosen will be allowed to be configured on the role.bound_ami_id
(list: [])
- If set, defines a constraint on the EC2 instances that they should be using one of the AMI ID specified by this parameter. This constraint is checked during ec2 auth as well as the iam auth method only when inferring an EC2 instance. This is a comma-separated string or JSON array.bound_account_id
(list: [])
- If set, defines a constraint on the EC2 instances that the account ID in its identity document to match one of the ones specified by this parameter. This constraint is checked during ec2 auth as well as the iam auth method only when inferring an EC2 instance. This is a comma-separated string or JSON array.bound_region
(list: [])
- If set, defines a constraint on the EC2 instances that the region in its identity document must match one of the regions specified by this parameter. This constraint is only checked by the ec2 auth method as well as the iam auth method only when inferring an ec2 instance. This is a comma-separated string or JSON array.bound_vpc_id
(list: [])
- If set, defines a constraint on the EC2 instance to be associated with a VPC ID that matches one of the values specified by this parameter. This constraint is only checked by the ec2 auth method as well as the iam auth method only when inferring an ec2 instance. This is a comma-separated string or JSON array.bound_subnet_id
(list: [])
- If set, defines a constraint on the EC2 instance to be associated with a subnet ID that matches one of the values specified by this parameter. This constraint is only checked by the ec2 auth method as well as the iam auth method only when inferring an ec2 instance. This is a comma-separated string or a JSON array.bound_iam_role_arn
(list: [])
- If set, defines a constraint on the authenticating EC2 instance that it must match one of the IAM role ARNs specified by this parameter. Wildcards are supported at the end of the ARN to allow for prefix matching. The configured IAM user or EC2 instance role must be allowed to execute the iam:GetInstanceProfile
action if this is specified. This constraint is checked by the ec2 auth method as well as the iam auth method only when inferring an EC2 instance. This is a comma-separated string or a JSON array.bound_iam_instance_profile_arn
(list: [])
- If set, defines a constraint on the EC2 instances to be associated with an IAM instance profile ARN. Wildcards are supported at the end of the ARN to allow for prefix matching. This constraint is checked by the ec2 auth method as well as the iam auth method only when inferring an ec2 instance. This is a comma-separated string or a JSON array.bound_ec2_instance_id
(list: [])
- If set, defines a constraint on the EC2 instances to have one of these instance IDs. This constraint is checked by the ec2 auth method as well as the iam auth method only when inferring an ec2 instance. This is a comma-separated string or a JSON array.role_tag
(string: "")
- If set, enables the role tags for this role. The value set for this field should be the 'key' of the tag on the EC2 instance. The 'value' of the tag should be generated using role/<role>/tag
endpoint. Defaults to an empty string, meaning that role tags are disabled. This constraint is valid only with the ec2 auth method and is not allowed when auth_type
is iam.bound_iam_principal_arn
(list: [])
- Defines the list of IAM principals that are permitted to login to the role using the iam auth method. Individual values should look like "arn:aws:iam::123456789012:user/MyUserName" or "arn:aws:iam::123456789012:role/MyRoleName". Wildcards are supported at the end of the ARN, e.g., "arn:aws:iam::123456789012:*" will match any IAM principal in the AWS account 123456789012. When resolve_aws_unique_ids
is false
and you are binding to IAM roles (as opposed to users) and you are not using a wildcard at the end, then you must specify the ARN by omitting any path component; see the documentation for resolve_aws_unique_ids
below. This constraint is only checked by the iam auth method. Wildcards are supported at the end of the ARN, e.g., "arn:aws:iam::123456789012:role/*" will match all roles in the AWS account. This is a comma-separated string or JSON array.inferred_entity_type
(string: "")
- When set, instructs Vault to turn on inferencing. The only current valid value is "ec2_instance" instructing Vault to infer that the role comes from an EC2 instance in an IAM instance profile. This only applies to the iam auth method. If you set this on an existing role where it had not previously been set, tokens that had been created prior will not be renewable; clients will need to get a new token.inferred_aws_region
(string: "")
- When role inferencing is activated, the region to search for the inferred entities (e.g., EC2 instances). Required if role inferencing is activated. This only applies to the iam auth method.resolve_aws_unique_ids
(bool: true)
- When set, resolves the bound_iam_principal_arn
to the AWS Unique ID for the bound principal ARN. This field is ignored when bound_iam_principal_arn
ends with a wildcard character. This requires Vault to be able to call iam:GetUser
or iam:GetRole
on the bound_iam_principal_arn
that is being bound. Resolving to internal AWS IDs more closely mimics the behavior of AWS services in that if an IAM user or role is deleted and a new one is recreated with the same name, those new users or roles won't get access to roles in Vault that were permissioned to the prior principals of the same name. The default value for new roles is true, while the default value for roles that existed prior to this option existing is false (you can check the value for a given role using the GET method on the role). Any authentication tokens created prior to this being supported won't verify the unique ID upon token renewal. When this is changed from false to true on an existing role, Vault will attempt to resolve the role's bound IAM ARN to the unique ID and, if unable to do so, will fail to enable this option. Changing this from true
to false
is not supported; if absolutely necessary, you would need to delete the role and recreate it explicitly setting it to false
. However; the instances in which you would want to do this should be rare. If the role creation (or upgrading to use this) succeed, then Vault has already been able to resolve internal IDs, and it doesn't need any further IAM permissions to authenticate users. If a role has been deleted and recreated, and Vault has cached the old unique ID, you should just call this endpoint specifying the same bound_iam_principal_arn
and, as long as Vault still has the necessary IAM permissions to resolve the unique ID, Vault will update the unique ID. (If it does not have the necessary permissions to resolve the unique ID, then it will fail to update.) If this option is set to false, then you MUST leave out the path component in bound_iam_principal_arn
for roles that do not specify a wildcard at the end, but not IAM users or role bindings that have a wildcard. That is, if your IAM role ARN is of the form arn:aws:iam::123456789012:role/some/path/to/MyRoleName
, and resolve_aws_unique_ids
is false
, you must specify a bound_iam_principal_arn
of arn:aws:iam::123456789012:role/MyRoleName
for authentication to work.allow_instance_migration
(bool: false)
- If set, allows migration of the underlying instance where the client resides. This keys off of pendingTime in the metadata document, so essentially, this disables the client nonce check whenever the instance is migrated to a new host and pendingTime is newer than the previously-remembered time. Use with caution. This only applies to authentications via the ec2 auth method. This is mutually exclusive with disallow_reauthentication
.disallow_reauthentication
(bool: false)
- If set, only allows a single token to be granted per instance ID. In order to perform a fresh login, the entry in the access list for the instance ID needs to be cleared using auth/aws/identity-accesslist/<instance_id>
endpoint. Defaults to 'false'. This only applies to authentications via the ec2 auth method. This is mutually exclusive with allow_instance_migration
.token_ttl
(integer: 0 or string: "")
- The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time.token_max_ttl
(integer: 0 or string: "")
- The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time.token_policies
(array: [] or comma-delimited string: "")
- List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.policies
(array: [] or comma-delimited string: "")
- DEPRECATED: Please use the token_policies
parameter instead. List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.token_bound_cidrs
(array: [] or comma-delimited string: "")
- List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well.token_explicit_max_ttl
(integer: 0 or string: "")
- If set, will encode an explicit max TTL onto the token. This is a hard cap even if token_ttl
and token_max_ttl
would otherwise allow a renewal.token_no_default_policy
(bool: false)
- If set, the default
policy will not be set on generated tokens; otherwise it will be added to the policies set in token_policies
.token_num_uses
(integer: 0)
- The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0.token_period
(integer: 0 or string: "")
- The maximum allowed period value when a periodic token is requested from this role.token_type
(string: "")
- The type of token that should be generated. Can be service
, batch
, or default
to use the mount's tuned default (which unless changed will be service
tokens). For token store roles, there are two additional possibilities: default-service
and default-batch
which specify the type to return unless the client requests a different type at generation time. For machine based authentication cases, you should use batch
type tokens.{
"bound_ami_id": ["ami-fce36987"],
"bound_ec2_instance_id": ["i-12345678901234567"],
"role_tag": "",
"policies": ["default", "dev", "prod"],
"max_ttl": 1800000,
"disallow_reauthentication": false,
"allow_instance_migration": false
}
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/role/dev-role
Returns the previously registered role configuration.
Method PathGET
/auth/aws/role/:role
Parameters
role
(string: <required>)
- Name of the role.$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/aws/role/dev-role
Sample response
{
"data": {
"bound_ami_id": ["ami-fce36987"],
"role_tag": "",
"policies": ["default", "dev", "prod"],
"max_ttl": 1800000,
"disallow_reauthentication": false,
"allow_instance_migration": false
}
}
Lists all the roles that are registered with the method.
Method PathLIST
/auth/aws/roles
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/aws/roles
Sample response
{
"data": {
"keys": ["dev-role", "prod-role"]
}
}
Deletes the previously registered role.
Method PathDELETE
/auth/aws/role/:role
Parameters
role
(string: <required>)
- Name of the role.$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/aws/role/dev-role
Creates a role tag on the role, which help in restricting the capabilities that are set on the role. Role tags are not tied to any specific ec2 instance unless specified explicitly using the instance_id
parameter. By default, role tags are designed to be used across all instances that satisfies the constraints on the role. Regardless of which instances have role tags on them, capabilities defined in a role tag must be a strict subset of the given role's capabilities. Note that, since adding and removing a tag is often a widely distributed privilege, care needs to be taken to ensure that the instances are attached with correct tags to not let them gain more privileges than what were intended. If a role tag is changed, the capabilities inherited by the instance will be those defined on the new role tag. Since those must be a subset of the role capabilities, the role should never provide more capabilities than any given instance can be allowed to gain in a worst-case scenario.
POST
/auth/aws/role/:role/tag
Parameters
role
(string: <required>)
- Name of the role.policies
(array: [])
- Policies to be associated with the tag. If set, must be a subset of the role's policies. If set, but set to an empty value, only the 'default' policy will be given to issued tokens.max_ttl
(string: "")
- The maximum allowed lifetime of tokens issued using this role.instance_id
(string: "")
- Instance ID for which this tag is intended for. If set, the created tag can only be used by the instance with the given ID.allow_instance_migration
(bool: false)
- If set, allows migration of the underlying instance where the client resides. This keys off of pendingTime in the metadata document, so essentially, this disables the client nonce check whenever the instance is migrated to a new host and pendingTime is newer than the previously-remembered time. Use with caution. Defaults to 'false'. Mutually exclusive with disallow_reauthentication
.disallow_reauthentication
(bool: false)
- If set, only allows a single token to be granted per instance ID. This can be cleared with the auth/aws/identity-accesslist endpoint. Defaults to 'false'. Mutually exclusive with allow_instance_migration
.{
"policies": ["default", "dev-api"]
}
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/role/dev-api-and-web-role/tag
Sample response
{
"data": {
"tag_value": "v1:09Vp0qGuyB8=:r=dev-role:p=default,dev-api:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/pJIdVyOI=",
"tag_key": "VaultRole"
}
}
Fetch a token. This endpoint verifies the PKCS#7 signature of the instance identity document or the signature of the signed GetCallerIdentity request. With the ec2 auth method, or when inferring an EC2 instance, verifies that the instance is actually in a running state. Cross checks the constraints defined on the role with which the login is being performed. With the ec2 auth method, as an alternative to PKCS#7 signature, the identity document along with its RSA signature can be supplied to this endpoint.
See the AWS docs for more information on the signature types.
Method PathPOST
/auth/aws/login
Parameters
role
(string: "")
- Name of the role against which the login is being attempted. If role
is not specified, then the login endpoint looks for a role bearing the name of the AMI ID of the EC2 instance that is trying to login if using the ec2 auth method, or the "friendly name" (i.e., role name or username) of the IAM principal authenticated. If a matching role is not found, login fails.identity
(string: <required-ec2>)
- Base64 encoded EC2 instance identity document, which can usually be obtained from the http://169.254.169.254/latest/dynamic/instance-identity/document
endpoint. When using curl
for fetching the identity document, consider using the option -w 0
while piping the output to base64
binary. Either both of this and signature
must be set OR pkcs7
must be set when using the ec2 auth method.signature
(string: <required-ec2>)
- Base64-encoded SHA256 RSA signature of the instance identity document, which can usually be obtained from the http://169.254.169.254/latest/dynamic/instance-identity/signature
endpoint. Either both this AND identity
must be set OR pkcs7
must be set when using the ec2 auth method.pkcs7
(string: <required-ec2>)
- PKCS#7 signature of the identity document with all \n
characters removed. This supports signatures from the AWS http://169.254.169.254/latest/dynamic/instance-identity/rsa2048
or http://169.254.169.254/latest/dynamic/instance-identity/pkcs7
endpoints. Either this needs to be set OR both identity
and signature
need to be set when using the ec2 auth method.nonce
(string: "")
- The nonce to be used for subsequent login requests. If this parameter is not specified at all and if reauthentication is allowed, then the method will generate a random nonce, attaches it to the instance's identity-accesslist entry and returns the nonce back as part of auth metadata. This value should be used with further login requests, to establish client authenticity. Clients can choose to set a custom nonce if preferred, in which case, it is recommended that clients provide a strong nonce. If a nonce is provided but with an empty value, it indicates intent to disable reauthentication. Note that, when disallow_reauthentication
option is enabled on either the role or the role tag, the nonce
holds no significance. This is ignored unless using the ec2 auth method.iam_http_request_method
(string: <required-iam>)
- HTTP method used in the signed request. This is required when using the iam auth method.iam_request_url
(string: <required-iam>)
- Base64-encoded HTTP URL used in the signed request. Most likely just aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8=
(base64-encoding of https://sts.amazonaws.com/
) as most requests will probably use POST with an empty URI. If using GET method this will contain the authentication headers that have been hoisted out of the message body. This is required when using the iam auth method.iam_request_body
(string: <required-iam>)
- Base64-encoded body of the signed request. Most likely QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ==
, which is the base64 encoding of Action=GetCallerIdentity&Version=2011-06-15
. This is required when using the iam auth method with POST signed requests.iam_request_headers
(string: <required-iam>)
- Key/value pairs of headers for use in the sts:GetCallerIdentity
HTTP requests headers. Can be either a Base64-encoded, JSON-serialized string, or a JSON object of key/value pairs. The JSON serialization assumes that each header key maps to either a string value or an array of string values (though the length of that array will probably only be one). If the iam_server_id_header_value
is configured in Vault for the aws auth mount, then the headers must include the X-Vault-AWS-IAM-Server-ID header, its value must match the value configured, and the header must be included in the signed headers. This is required when using the iam auth method.{
"iam_http_request_method": "POST",
"iam_request_body": "QWN0aW9uPUdldENhbG...",
"iam_request_headers": "eyJBdXRob3JpemF0aW9uIj...",
"iam_request_url": "aHR0cHM6L...",
"role": "dev-role"
}
Sample request
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/aws/login
Sample response
{
"auth": {
"renewable": true,
"lease_duration": 1800000,
"metadata": {
"role_tag_max_ttl": "0",
"instance_id": "i-de0f1344",
"ami_id": "ami-fce36983",
"role": "dev-role",
"auth_type": "ec2"
},
"policies": ["default", "dev"],
"accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e",
"client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a"
}
}
Places a valid role tag in a deny list. This ensures that the role tag cannot be used by any instance to perform a login operation again. Note that if the role tag was previously used to perform a successful login, placing the tag in the deny list does not invalidate the already issued token.
Method PathPOST
/auth/aws/roletag-denylist/:role_tag
Parameters
role_tag
(string: <required>)
- Role tag to be deny listed. This is the tag_value
returned when the role tag is created. The tag can be supplied as-is. In order to avoid any encoding problems, it can be base64 encoded.$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo=
Read role tag deny list information
Returns the deny list entry of a previously deny listed role tag.
Method PathGET
/auth/aws/roletag-denylist/:role_tag
Parameters
role_tag
(string: <required>)
- Role tag to be deny listed. The tag can be supplied as-is. In order to avoid any encoding problems, it can be base64 encoded.$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo=
Sample response
{
"data": {
"expiration_time": "2016-04-25T10:35:20.127058773-04:00",
"creation_time": "2016-04-12T22:35:01.178348124-04:00"
}
}
Lists all the role tags that are deny listed.
Method PathLIST
/auth/aws/roletag-denylist
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/aws/roletag-denylist
Sample response
{
"data": {
"keys": [
"v1:09Vp0qGuyB8=:a=ami-fce3c696:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/"
]
}
}
Deletes a deny listed role tag.
Method PathDELETE
/auth/aws/roletag-denylist/:role_tag
Parameters
role_tag
(string: <required>)
- Role tag to be deny listed. The tag can be supplied as-is. In order to avoid any encoding problems, it can be base64 encoded.$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo=
Cleans up the entries in the deny listed based on expiration time on the entry and safety_buffer
.
POST
/auth/aws/tidy/roletag-denylist
Parameters
safety_buffer
(string: "72h")
- The amount of extra time that must have passed beyond the roletag
expiration, before it is removed from the method storage. Defaults to 72h.$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/auth/aws/tidy/roletag-denylist
Read identity access list information
Returns an entry in the identity access list. An entry will be created/updated by every successful login.
Method PathGET
/auth/aws/identity-accesslist/:instance_id
Parameters
instance_id
(string: <required>)
- EC2 instance ID. A successful login operation from an EC2 instance gets cached in th access list, keyed off of instance ID.$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/aws/identity-accesslist/i-aab47d37
Sample response
{
"data": {
"pending_time": "2016-04-14T01:01:41Z",
"expiration_time": "2016-05-05 10:09:16.67077232 +0000 UTC",
"creation_time": "2016-04-14 14:09:16.67077232 +0000 UTC",
"client_nonce": "5defbf9e-a8f9-3063-bdfc-54b7a42a1f95",
"role": "dev-role"
}
}
Lists all the instance IDs that are in the access list of successful logins.
Method PathLIST
/auth/aws/identity-accesslist
Sample request
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/aws/identity-accesslist
Sample response
{
"data": {
"keys": ["i-aab47d37"]
}
}
Deletes a cache of the successful login from an instance.
Method PathDELETE
/auth/aws/identity-accesslist/:instance_id
Parameters
instance_id
(string: <required>)
- EC2 instance ID. A successful login operation from an EC2 instance gets cached in this access list, keyed off of instance ID.$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/aws/identity-accesslist/i-aab47d37
Cleans up the entries in the access list based on expiration time and safety_buffer
.
POST
/auth/aws/tidy/identity-accesslist
Parameters
safety_buffer
(string: "72h")
- The amount of extra time that must have passed beyond the roletag
expiration, before it is removed from the method storage. Defaults to 72h.$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/auth/aws/tidy/identity-accesslist
Vault 1.7 introduced new URLs for a number of AWS Auth APIs. The previous URLs are deprecated. The affected APIs include:
Current Deprecated in 1.7/auth/aws/roletag-denylist
/auth/aws/roletag-blacklist
/auth/aws/identity-accesslist
/auth/aws/identity-whitelist
/auth/aws/tidy/identity-accesslist
/auth/aws/tidy/identity-whitelist
/auth/aws/tidy/roletag-denylist
/auth/aws/tidy/roletag-blacklist
/auth/aws/config/tidy/identity-accesslist
/auth/aws/config/tidy/identity-whitelist
/auth/aws/config/tidy/roletag-denylist
/auth/aws/config/tidy/roletag-blacklist
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4