AWS secrets engine (API)
This is the API documentation for the Vault AWS secrets engine. For general information about the usage and operation of the AWS secrets engine, please see the Vault AWS documentation.
This documentation assumes the AWS secrets engine is enabled at the /aws
path in Vault. Since it is possible to enable secrets engines at any location, please update your API calls accordingly.
Configure root IAM credentials
This endpoint configures the root IAM credentials to communicate with AWS. There are multiple ways to pass root IAM credentials to the Vault server, specified below with the highest precedence first. If credentials already exist, this will overwrite them.
The official AWS SDK is used for sourcing credentials from env vars, shared files, or IAM/ECS instances.
Static credentials provided to the API as a payload
Credentials in the
AWS_ACCESS_KEY
,AWS_SECRET_KEY
, andAWS_REGION
environment variables on the serverShared credentials files
Assigned IAM role or ECS task role credentials
At present, this endpoint does not confirm that the provided AWS credentials are valid AWS credentials with proper permissions.
POST
/aws/config/root
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: <required>)
– Specifies the AWS access key ID.secret_key
(string: <required>)
– Specifies the AWS secret access key.region
(string: <optional>)
– Specifies the AWS region. If not set it will use theAWS_REGION
env var,AWS_DEFAULT_REGION
env var, orus-east-1
in that order.iam_endpoint
(string: <optional>)
– Specifies a custom HTTP IAM endpoint to use.sts_endpoint
(string: <optional>)
– Specifies a custom HTTP STS endpoint to use.username_template
(string: <optional>)
- Template describing how dynamic usernames are generated. The username template is used to generate both IAM usernames (capped at 64 characters) and STS usernames (capped at 32 characters). Longer usernames result in a 500 error.To ensure generated usernames are within length limits for both STS/IAM, the template must adequately handle both conditional cases (see Conditional Templates). As an example, if no template is provided the field defaults to the template below. It is to be noted that, DisplayName is the name of the vault authenticated user running the AWS credential generation and PolicyName is the name of the Role for which the credential is being generated for:
Sample payload
Sample request
Read root configuration
This endpoint allows you to read non-secure values that have been configured in the config/root
endpoint. In particular, the secret_key
parameter is never returned.
GET
/aws/config/root
Sample request
Sample response
Rotate root IAM credentials
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.
POST
/aws/config/rotate-root
Parameters
There are no parameters to this operation.
Sample request
Sample response
The new access key Vault uses is returned by this operation.
Configure lease
This endpoint configures lease settings for the AWS secrets engine. It is optional, as there are default values for lease
and lease_max
.
POST
/aws/config/lease
Parameters
lease
(string: <required>)
– Specifies the lease value provided as a string duration with time suffix. "h" (hour) is the largest suffix.lease_max
(string: <required>)
– Specifies the maximum lease value provided as a string duration with time suffix. "h" (hour) is the largest suffix.
Sample payload
Sample request
Read lease
This endpoint returns the current lease settings for the AWS secrets engine.
GET
/aws/config/lease
Sample request
Sample response
Create/Update role
This endpoint creates or updates the role with the given name
. If a role with the name does not exist, it will be created. If the role exists, it will be updated with the new attributes.
POST
/aws/roles/:name
Parameters
name
(string: <required>)
– Specifies the name of the role to create. This is part of the request URL.credential_type
(string: <required>)
– Specifies the type of credential to be used when retrieving credentials from the role. Must be one ofiam_user
,assumed_role
, orfederation_token
.role_arns
(list: [])
– Specifies the ARNs of the AWS roles this Vault role is allowed to assume. Required whencredential_type
isassumed_role
and prohibited otherwise. This is a comma-separated string or JSON array.policy_arns
(list: [])
– Specifies a list of AWS managed policy ARN. The behavior depends on the credential type. Withiam_user
, the policies will be attached to IAM users when they are requested. Withassumed_role
andfederation_token
, the policy ARNs will act as a filter on what the credentials can do, similar topolicy_document
. Whencredential_type
isiam_user
orfederation_token
, at least one ofpolicy_arns
orpolicy_document
must be specified. This is a comma-separated string or JSON array.policy_document
(string)
– The IAM policy document for the role. The behavior depends on the credential type. Withiam_user
, the policy document will be attached to the IAM user generated and augment the permissions the IAM user has. Withassumed_role
andfederation_token
, the policy document will act as a filter on what the credentials can do, similar topolicy_arns
.iam_groups
(list: [])
- A list of IAM group names. IAM users generated against this vault role will be added to these IAM Groups. For a credential type ofassumed_role
orfederation_token
, the policies sent to the corresponding AWS call (sts:AssumeRole or sts:GetFederation) will be the policies from each group iniam_groups
combined with thepolicy_document
andpolicy_arns
parameters.iam_tags
(list: [])
- A list of strings representing a key/value pair to be used as a tag for anyiam_user
user that is created by this role. Format is a key and value separated by an=
(e.g.test_key=value
). Note: when using the CLI multiple tags can be specified in the role configuration by adding anotheriam_tags
assignment in the same command.default_sts_ttl
(string)
- The default TTL for STS credentials. When a TTL is not specified when STS credentials are requested, and a default TTL is specified on the role, then this default TTL will be used. Valid only whencredential_type
is one ofassumed_role
orfederation_token
.max_sts_ttl
(string)
- The max allowed TTL for STS credentials (credentials TTL are capped tomax_sts_ttl
). Valid only whencredential_type
is one ofassumed_role
orfederation_token
.user_path
(string)
- The path for the user name. Valid only whencredential_type
isiam_user
. Default is/
permissions_boundary_arn
(string)
- The ARN of the AWS Permissions Boundary to attach to IAM users created in the role. Valid only whencredential_type
isiam_user
. If not specified, then no permissions boundary policy will be attached.
Legacy parameters:
These parameters are supported for backwards compatibility only. They cannot be mixed with the parameters listed above.
policy
(string: <required unless arn provided>)
– Specifies the IAM policy in JSON format.arn
(string: <required unless policy provided>)
– Specifies the full ARN reference to the desired existing policy.
Sample request
Sample payloads
Using an inline IAM policy:
Using an ARN:
Using groups:
Using tags:
or
Read role
This endpoint queries an existing role by the given name. If the role does not exist, a 404 is returned.
GET
/aws/roles/:name
If invalid role data was supplied to the role from an earlier version of Vault, then it will show up in the response as invalid_data
.
Parameters
name
(string: <required>)
– Specifies the name of the role to read. This is part of the request URL.
Sample request
Sample responses
For an inline IAM policy:
For a role ARN:
For IAM groups:
List roles
This endpoint lists all existing roles in the secrets engine.
LIST
/aws/roles
Sample request
Sample response
Delete role
This endpoint deletes an existing role by the given name. If the role does not exist, a 404 is returned.
DELETE
/aws/roles/:name
Parameters
name
(string: <required>)
– Specifies the name of the role to delete. This is part of the request URL.
Sample request
Generate credentials
This endpoint generates credentials based on the named role. This role must be created before queried.
GET
/aws/creds/:name
POST
/aws/sts/:name
The /aws/creds
and /aws/sts
endpoints are almost identical. The exception is when retrieving credentials for a role that was specified with the legacy arn
or policy
parameter. In this case, credentials retrieved through /aws/sts
must be of either the assumed_role
or federation_token
types, and credentials retrieved through /aws/creds
must be of the iam_user
type.
Parameters
name
(string: <required>)
– Specifies the name of the role to generate credentials against. This is part of the request URL.role_arn
(string)
– The ARN of the role to assume ifcredential_type
on the Vault role isassumed_role
. Must match one of the allowed role ARNs in the Vault role. Optional if the Vault role only allows a single AWS role ARN; required otherwise.role_session_name
(string)
- The role session name to attach to the assumed role ARN.role_session_name
is limited to 64 characters; if exceeded, therole_session_name
in the assumed role ARN will be truncated to 64 characters. Ifrole_session_name
is not provided, then it will be generated dynamically by default.ttl
(string: "3600s")
– Specifies the TTL for the use of the STS token. This is specified as a string with a duration suffix. Valid only whencredential_type
isassumed_role
orfederation_token
. When not specified, thedefault_sts_ttl
set for the role will be used. If that is also not set, then the default value of3600s
will be used. AWS places limits on the maximum TTL allowed. See the AWS documentation on theDurationSeconds
parameter for AssumeRole (forassumed_role
credential types) and GetFederationToken (forfederation_token
credential types) for more details.
Sample request
Sample response
Create/Update static role
This endpoint creates or updates static role definitions. A static role is a 1-to-1 mapping with an AWS IAM User, which will be adopted and managed by Vault, including rotating it according to the configured rotation_period
.
Note
Vault will create a new credential upon configuration, and if the maximum number of access keys already exist, Vault will rotate the oldest one. Vault must do this to know the credential.
At each rotation, Vault will rotate the oldest existing credential.
POST
/aws/static-roles/:name
Parameters
name
(string: <required>)
– Specifies the name of the role to create. This is specified as part of the URL.username
(string: <required>)
– Specifies the username of the IAM user.rotation_period
(string/int: <required>)
– Specifies the amount of time Vault should wait before rotating the password. The minimum is 1 minute. Can be specified in either24h
or86400
format (see duration format strings). Updating the rotation period will 'reset' the next rotation to occur atnow
+rotation_period
.
Sample payload
Sample request
Sample response
Read static role
This endpoint queries the static role definition.
GET
/aws/static-roles/:name
Parameters
name
(string: <required>)
– Specifies the name of the static role to read. This is specified as part of the URL.
Sample request
Sample response
Delete static role
This endpoint deletes the static role definition. The user, having been defined externally, must be cleaned up manually.
DELETE
/aws/static-roles/:name
Parameters
name
(string: <required>)
– Specifies the name of the static role to delete. This is specified as part of the URL.
Sample request
Get static credentials
This endpoint returns the current credentials based on the named static role.
GET
/aws/static-creds/:name
Parameters
name
(string: <required>)
– Specifies the name of the static role to get credentials for. This is specified as part of the URL.
Sample request
Sample response
Last updated