Config

AWS config file

aws-vault uses your ~/.aws/config to load AWS config. This should work identically to the config specified by the aws-cli docs.

include_profile

(Note: aws-vault v5 calls this parent_profile)

AWS Vault also recognises an extra config variable, include_profile, which is not recognised by the aws-cli. This variable allows a profile to load configuration horizontally from another profile.

This is a flexible mechanism for more complex configurations.

For example you can use it in “mixin” style where you import a common fragment. In this example, the root, order-dev and order-staging-admin profiles include the region, mfa_serial and source_profile configuration from common.

; The "common" profile here operates as a "config fragment" rather than a profile
[profile common]
region=eu-west-1
mfa_serial=arn:aws:iam::123456789:mfa/johnsmith
source_profile = root

[profile root]
include_profile = common

[profile order-dev]
include_profile = common
role_arn=arn:aws:iam::123456789:role/developers

[profile order-staging-admin]
include_profile = common
role_arn=arn:aws:iam::123456789:role/administrators

Or you could use it in “parent” style where you conflate the fragment with the profile. In this example the order-dev and order-staging-admin profiles include the region, mfa_serial and source_profile configuration from root, while also using the credentials stored against the root profile as the source credentials source_profile = root

; The "root" profile here operates as a profile, a config fragment as well as a source_profile
[profile root]
region=eu-west-1
mfa_serial=arn:aws:iam::123456789:mfa/johnsmith
source_profile = root

[profile order-dev]
include_profile = root
role_arn=arn:aws:iam::123456789:role/developers

[profile order-staging-admin]
include_profile = root
role_arn=arn:aws:iam::123456789:role/administrators

session_tags and transitive_session_tags

It is possible to set session tags when AssumeRole is used. Two custom config variables could be defined for that: session_tags and transitive_session_tags. The former defines a comma separated key=value list of tags and the latter is a comma separated list of tags that should be persisted during role chaining:

[profile root]
region=eu-west-1

[profile order-dev]
source_profile = root
role_arn=arn:aws:iam::123456789:role/developers
session_tags = key1=value1,key2=value2,key3=value3
transitive_session_tags = key1,key2

source_identity

It is possible to set source identity when AssumeRole is used. Custom config variable source_identity allows you to set the value.

[profile root]
region=eu-west-1

[profile order-dev]
source_profile = root
role_arn=arn:aws:iam::123456789:role/developers
source_identity=your_user_name

mfa_process

If you have a method to generate an MFA token, you can use it with aws-vault by specifying the mfa_process option in a profile of your ~/.aws/config file. The value of mfa_process should be a command that will output the MFA token to stdout.

For example, to use pass to retrieve an MFA token from a password store entry, you could use the following:

[profile foo]
mfa_serial=arn:aws:iam::123456789:mfa/johnsmith
mfa_process=pass otp my_aws_mfa

Or another example using 1Password

[profile foo]
mfa_serial=arn:aws:iam::123456789:mfa/johnsmith
mfa_process=op item get my_aws_mfa --otp

WARNING: Use of this option runs against security best practices. It is recommended that you use a dedicated MFA device.

Environment variables

To configure the default flag values of aws-vault and its subcommands:

To override the AWS config file (used in the exec, login and rotate subcommands):

To override session durations (used in exec and login):

Note that the session durations above expect a unit after the number (e.g. 12h or 43200s).

To override or set session tagging (used in exec):

To override or set the source identity (used in exec and login):