Vault
HomeDocumentationTutorialsTry Cloud!
  • Vault
  • Documentation
    • What is Vault?
    • Use Cases
    • Setup
      • Install
      • Configuration
    • Get Started
      • Starting the server
      • Your first secret
      • Deploying Vault on VMs with Let's encrypt! TLS certs
    • Concepts
      • Operations
        • Seal/Unseal
        • "Dev" server mode
        • Namespace lock and unlock
        • Lease, renew, and revoke
        • Lease Explosions
        • Mount migration
        • Client count
        • Resource quotas
        • Response wrapping
      • Authentication
        • Identity
        • Tokens
        • OIDC provider
        • Username templating
        • Passwordless
      • Secrets
      • Storage
        • Integrated storage
        • High availability mode (HA)
        • Recovery mode
      • Policies
  • Tutorials
    • CLI
      • Operations
        • Deploy Vault
        • Using the HTTP API
        • Unseal/Seal
      • Authentication
        • Token
        • GitHub authentication
        • Username/Password
        • TLS Client Certificates
        • SSH Keys
        • AWS, Azure, GCP and external auth methods
          • Azure
          • AWS
          • GCP
          • Github
          • Terraform
      • Secrets
        • Secrets engines
        • Built-in help
      • Access Control
        • Policies
    • UI
      • Authentication
        • Username/Password
        • Passwordless
      • Operations
        • Unseal / Seal
        • API Explorer
      • Secrets
        • Secrets engines
      • Access Control
        • Policies
    • Use Cases
      • Namespaces
      • MongoDB admin password
      • VM Disk Encryption Keys
      • VM SSH Keys
      • Kubernetes Configuration
      • GitHub Actions
      • Dynamic credentials for cloud providers
        • AWS
        • Azure
        • GCP
  • CLI
    • agent
    • audit
    • auth
    • debug
    • delete
    • events
    • kv
    • lease
    • license
    • list
    • login
    • monitor
    • namespace
    • operator
    • patch
    • path-help
    • pki
    • plugin
    • policy
    • print
    • proxy
    • read
    • secrets
    • server
    • ssh
    • status
    • token
    • transit
    • unwrap
    • version
    • version-history
    • write
  • API
    • Secrets engines
      • AliCloud secrets engine (API)
      • AWS secrets engine (API)
      • Azure secrets engine (API)
      • Cubbyhole secrets engine (API)
      • Database
        • Cassandra database plugin HTTP API
        • Elasticsearch database plugin HTTP API
        • Influxdb database plugin HTTP API
        • MongoDB database plugin HTTP API
        • MSSQL database plugin HTTP API
        • MySQL/MariaDB database plugin HTTP API
        • Oracle database plugin HTTP API
        • PostgreSQL database plugin HTTP API
        • Redis database plugin HTTP API
        • Redis ElastiCache database plugin HTTP API
        • Redshift database plugin HTTP API
        • Snowflake database plugin HTTP API
      • Google Cloud secrets engine (API)
      • Google Cloud KMS secrets engine (API)
      • Identity
        • entity
        • entity-alias
        • group
        • group-alias
        • tokens
        • lookup
        • oidc-provider
        • MFA
          • duo
          • okta
          • pingid
          • totp
          • login-enforcement
      • KV secrets engine (API)
      • Buckypaper secrets engine
      • Kubernetes secrets engine (API)
      • Nomad secrets engine (API)
      • LDAP secrets engine (API)
      • PKI secrets engine (API)
      • RabbitMQ secrets engine (API)
      • SSH secrets engine (API)
      • TOTP secrets engine (API)
      • Transit secrets engine (API)
    • Auth engines
      • AliCloud auth method (API)
      • AppRole auth method (API)
      • AWS auth method (API)
      • Azure auth method (API)
      • Pivotal Cloud Foundry (CF) auth method (API)
      • GitHub auth method (API)
      • Google Cloud auth method (API)
      • JWT/OIDC auth method (API)
      • Kerberos auth method (API)
      • Kubernetes auth method (API)
      • LDAP auth method (API)
      • OCI auth method (API)
      • Okta auth method (API)
      • Passwordless auth method (API)
      • RADIUS auth method (API)
      • TLS certificate auth method (API)
      • Token auth method (API)
      • Userpass auth method (HTTP API)
    • Service engines
      • Licence Manager
    • System backend
      • /sys/audit
      • /sys/audit-hash
      • /sys/auth
      • /sys/capabilities
      • /sys/capabilities-accessor
      • /sys/capabilities-self
      • /sys/config/auditing/request-headers
      • /sys/config/control-group
      • /sys/config/cors
      • /sys/config/reload
      • /sys/config/state
      • /sys/config/ui
      • /sys/decode-token
      • /sys/experiments
      • /sys/generate-recovery-token
      • /sys/generate-root
      • /sys/health
      • /sys/host-info
      • /sys/in-flight-req
      • /sys/init
      • /sys/internal/counters
      • /sys/internal/inspect
        • /sys/internal/inspect/router
      • /sys/internal/specs/openapi
      • /sys/internal/ui/feature-flags
      • /sys/internal/ui/mounts
      • /sys/internal/ui/namespaces
      • /sys/internal/ui/resultant-acl
      • /sys/key-status
      • /sys/ha-status
      • /sys/leader
      • /sys/leases
      • /sys/license/status
      • /sys/locked-users
      • /sys/loggers
      • /sys/metrics
      • /sys/monitor
      • /sys/mounts
      • /sys/namespaces
      • /sys/plugins/reload/backend
      • /sys/plugins/catalog
      • /sys/plugins/runtimes/catalog
      • /sys/policy
      • /sys/policies/
      • /sys/policies/password/
      • /sys/pprof
      • /sys/quotas/config
      • /sys/quotas/rate-limit
      • /sys/quotas/lease-count
      • /sys/raw
      • /sys/rekey
      • /sys/rekey-recovery-key
      • /sys/remount
      • /sys/rotate
      • /sys/rotate/config
      • /sys/seal
      • /sys/seal-status
      • /sys/seal-backend-status
      • /sys/step-down
      • /sys/storage
        • /sys/storage/raft
        • /sys/storage/raft/autopilot
      • /sys/tools
      • /sys/unseal
      • /sys/version-history
      • /sys/wrapping/lookup
      • /sys/wrapping/rewrap
      • /sys/wrapping/unwrap
      • /sys/wrapping/wrap
  • Resources
    • Blog
    • GitHub
    • Youtube
    • CCx101
Powered by GitBook
On this page
  • Configure root IAM credentials
  • Read root configuration
  • Rotate root IAM credentials
  • Configure lease
  • Read lease
  • Create/Update role
  • Read role
  • List roles
  • Delete role
  • Generate credentials
  • Create/Update static role
  • Read static role
  • Delete static role
  • Get static credentials
  1. API
  2. Secrets engines

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, and AWS_REGION environment variables on the server

  • Shared 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.

Method
Path

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 the AWS_REGION env var, AWS_DEFAULT_REGION env var, or us-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:

    {{ if (eq .Type "STS") }}
        {{ printf "vault-%s-%s" (unix_time) (random 20) | truncate 32 }}
    {{ else }}
        {{ printf "vault-%s-%s-%s" (printf "%s-%s" (.DisplayName) (.PolicyName) | truncate 42) (unix_time) (random 20) | truncate 64 }}
    {{ end }}

Sample payload

{
  "access_key": "AKIA...",
  "secret_key": "2J+...",
  "region": "us-east-1"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/aws/config/root

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.

Method
Path

GET

/aws/config/root

Sample request

$ curl
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/config/root

Sample response

{
  "data": {
    "access_key": "AKIAEXAMPLE",
    "region": "us-west-2",
    "iam_endpoint": "https://iam.amazonaws.com",
    "sts_endpoint": "https://sts.us-west-2.amazonaws.com",
    "max_retries": -1
  }
}

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.

Method
Path

POST

/aws/config/rotate-root

Parameters

There are no parameters to this operation.

Sample request

$ curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/aws/config/rotate-root

Sample response

{
  "data": {
    "access_key": "AKIA..."
  }
}

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.

Method
Path

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

{
  "lease": "30m",
  "lease_max": "12h"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/aws/config/lease

Read lease

This endpoint returns the current lease settings for the AWS secrets engine.

Method
Path

GET

/aws/config/lease

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/config/lease

Sample response

{
  "data": {
    "lease": "30m0s",
    "lease_max": "12h0m0s"
  }
}

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.

Method
Path

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 of iam_user, assumed_role, or federation_token.

  • role_arns (list: []) – Specifies the ARNs of the AWS roles this Vault role is allowed to assume. Required when credential_type is assumed_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. With iam_user, the policies will be attached to IAM users when they are requested. With assumed_role and federation_token, the policy ARNs will act as a filter on what the credentials can do, similar to policy_document. When credential_type is iam_user or federation_token, at least one of policy_arns or policy_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. With iam_user, the policy document will be attached to the IAM user generated and augment the permissions the IAM user has. With assumed_role and federation_token, the policy document will act as a filter on what the credentials can do, similar to policy_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 of assumed_role or federation_token, the policies sent to the corresponding AWS call (sts:AssumeRole or sts:GetFederation) will be the policies from each group in iam_groups combined with the policy_document and policy_arns parameters.

  • iam_tags (list: []) - A list of strings representing a key/value pair to be used as a tag for any iam_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 another iam_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 when credential_type is one of assumed_role or federation_token.

  • max_sts_ttl (string) - The max allowed TTL for STS credentials (credentials TTL are capped to max_sts_ttl). Valid only when credential_type is one of assumed_role or federation_token.

  • user_path (string) - The path for the user name. Valid only when credential_type is iam_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 when credential_type is iam_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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/aws/roles/example-role

Sample payloads

Using an inline IAM policy:

{
  "credential_type": "federation_token",
  "policy_document": "{\"Version\": \"...\"}"
}

Using an ARN:

{
  "credential_type": "assumed_role",
  "role_arns": "arn:aws:iam::123456789012:role/DeveloperRole"
}

Using groups:

{
  "credential_type": "assumed_role",
  "iam_groups": ["group1", "group2"]
}

Using tags:

{
  "credential_type": "iam_user",
  "iam_tags": [
    "first_key=first_value",
    "second_key=second_value"
  ]
}
vault write aws/roles/example-role \
credential_type=iam_user \
iam_tags="first_key=first_value" \
iam_tags="second_key=second_value"

or

{
  "credential_type": "iam_user",
  "iam_tags": {
    "first_key": "first_value",
    "second_key": "second_value"
  }
}

Read role

This endpoint queries an existing role by the given name. If the role does not exist, a 404 is returned.

Method
Path

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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/roles/example-role

Sample responses

For an inline IAM policy:

{
  "data": {
    "policy_document": "{\"Version\": \"...\"}",
    "policy_arns": [],
    "credential_types": ["assumed_role"],
    "role_arns": [],
    "iam_groups": []
  }
}

For a role ARN:

{
  "data": {
    "policy_document": "",
    "policy_arns": [],
    "credential_types": ["assumed_role"],
    "role_arns": ["arn:aws:iam::123456789012:role/example-role"],
    "iam_groups": []
  }
}

For IAM groups:

{
  "data": {
    "policy_document": "",
    "policy_arns": [],
    "credential_types": ["assumed_role"],
    "role_arns": [],
    "iam_groups": ["group1", "group2"]
  }
}

List roles

This endpoint lists all existing roles in the secrets engine.

Method
Path

LIST

/aws/roles

Sample request

$ curl
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/aws/roles

Sample response

{
  "data": {
    "keys": ["example-role"]
  }
}

Delete role

This endpoint deletes an existing role by the given name. If the role does not exist, a 404 is returned.

Method
Path

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/aws/roles/example-role

Generate credentials

This endpoint generates credentials based on the named role. This role must be created before queried.

Method
Path

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 if credential_type on the Vault role is assumed_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, the role_session_name in the assumed role ARN will be truncated to 64 characters. If role_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 when credential_type is assumed_role or federation_token. When not specified, the default_sts_ttl set for the role will be used. If that is also not set, then the default value of 3600s will be used. AWS places limits on the maximum TTL allowed. See the AWS documentation on the DurationSeconds parameter for AssumeRole (for assumed_role credential types) and GetFederationToken (for federation_token credential types) for more details.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/creds/example-role

Sample response

{
  "data": {
    "access_key": "AKIA...",
    "secret_key": "xlCs...",
    "security_token": null,
    "arn": "arn:aws:sts::123456789012:assumed-role/DeveloperRole/some-user-supplied-role-session-name"
  }
}

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.

Method
Path

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 either 24h or 86400 format (see duration format strings). Updating the rotation period will 'reset' the next rotation to occur at now + rotation_period.

Sample payload

{
  "username": "example-user",
  "rotation_period": "11h30m"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/aws/static-roles/my-static-role

Sample response

Read static role

This endpoint queries the static role definition.

Method
Path

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/aws/static-roles/my-static-role

Sample response

{
  "name": "my-static-role",
  "username": "example-user",
  "rotation_period": "11h30m"
}

Delete static role

This endpoint deletes the static role definition. The user, having been defined externally, must be cleaned up manually.

Method
Path

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/aws/static-roles/my-static-role

Get static credentials

This endpoint returns the current credentials based on the named static role.

Method
Path

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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/static-creds/my-static-role

Sample response

{
  "access_key": "AKIA...",
  "secret_key": "..."
}
PreviousAliCloud secrets engine (API)NextAzure secrets engine (API)

Last updated 1 year ago