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.

aws_account_id

exec and export expose the AWS account ID of the credentials as the AWS_ACCOUNT_ID environment variable (and as AccountId / aws_account_id in the json and ini export formats) whenever it can be determined from the profile config:

• the account in role_arn when a role is assumed (including web_identity_token_file / web_identity_token_process profiles),
• sso_account_id for SSO profiles,
• the account of the source_profile for profiles that chain without a role_arn.

For profiles where none of the above applies, such as stored long-term credentials or credential_process, the account ID can be set explicitly with the aws_account_id option, which is the same option the AWS CLI uses:

[profile jonsmith]
region=eu-west-1
aws_account_id=123456789012

Unlike other settings, aws_account_id is not inherited from the [default] section, since an account ID belongs to one specific set of credentials. It applies to the default profile itself, to the profile that sets it, and to profiles that pull it in explicitly with include_profile.

When the account is unknown, exec removes any AWS_ACCOUNT_ID inherited from the parent shell rather than passing it on. Note that AWS SDKs also read AWS_ACCOUNT_ID for account-based endpoint routing, so it is only ever set to the account the exposed credentials actually belong to. If your environment cannot reach account-specific endpoints (for example a restrictive egress allowlist), set account_id_endpoint_mode = disabled in your profile or AWS_ACCOUNT_ID_ENDPOINT_MODE=disabled in the environment.

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):