Shared config
and
credentials
files
The shared AWS config
and credentials
files contain a set of profiles. A profile is a set of configuration values that
can be referenced from the SDK/tool using its profile name. Configuration values are
attached to a profile in order to configure some aspect of the SDK/tool when that profile is
used.
As a general rule, any value that you can place in the shared credentials
file can alternatively be
placed in the shared config
file. The reverse isn't true; only a few settings can be placed in
the credentials
file. However, as a security best practice, we
recommend that you keep any sensitive values, such as access key IDs and secret keys, in the
separate credentials
file. This way, you can provide separate
permissions for each file, if necessary.
Both the shared config
and credentials
files are plaintext files that contain only ASCII characters (UTF-8 encoded).
They take the form of what are generally referred to as INI files
Profiles
Settings within the shared config
and credentials
files are associated with a specific profile. With multiple
profiles, you can create different settings configurations to apply in different
scenarios.
The [default]
profile contains the values that are used by an
SDK or tool operation if a specific named profile is not specified. You can also create
separate profiles that you can explicitly reference by name. Each named profile can have
a different group of settings.
[default]
is simply an unnamed profile. This profile is named
default
because it is the default profile used by the SDK if the user
does not specify a profile. It does not provide inherited default values to other
profiles. For example, if you set something in the [default]
profile and you don't set it in a named profile, then the value isn't set when you use
the named profile.
Optionally, set a named profile that you want to use through your SDK code or AWS CLI
commands. Alternatively, you can use the environment variable AWS_PROFILE
to specify which profile's settings to
use.
Linux/macOS example of setting environment variables via command line:
export AWS_PROFILE="my_default_profile_name";
Windows example of setting environment variables via command line:
setx AWS_PROFILE "my_default_profile_name"
Format of the config file
The config
file is organized into sections. A section is a named
collection of settings, and continues until another section definition line is
encountered.
The config
file is a plaintext file that uses the following
format:
-
All entries in a section take the general form of
setting-name=value
. -
Lines can be commented out by starting the line with a hashtag character (
#
).
Section types
A section definition is a line that applies a name to a collection of settings.
Section definition lines start and end with square brackets ([
]
). Inside the brackets, there is a section type identifier and a
custom name for the section. You can use letters, numbers, hyphens ( -
), and underscores ( _
), but no spaces.
Section type: profile
Example section definition line: [profile
dev
]
The profile
section definition line names a configuration
grouping that you can apply in different scenarios. [default]
is
the only profile that does not require the profile
section
identifier. To better understand named profiles, see the preceding section on
Profiles.
The following example shows a basic config
file with a
[default]
profile. It sets the region setting.
[default] #Full line comment, this text is ignored. region = us-east-2
The following example shows a config
file with a
profile
section definition line. It uses the identifier
profile
followed by a unique name for the profile. All settings
that follow this line, up until another section definition is encountered, will
be included with this named profile.
[profile
developers
] ...settings...
Some settings have their own nested group of subsettings, such as the
s3
setting and subsettings in the following example. Associate
the subsettings with the group by indenting them by one or more spaces.
[profile testers] region = us-west-2 s3 = max_concurrent_requests=10 max_queue_size=1000
Section type: sso-session
Example section definition line: [sso-session
my-sso
]
The sso-session
section definition line names a group of settings
that you use to configure a profile to resolve AWS credentials using
AWS IAM Identity Center (successor to AWS Single Sign-On). For more information on configuring single sign-on authentication,
see IAM Identity Center authentication. A profile is linked
to a sso-session
section by a key-value pair where
sso-session
is the key and the name of your
sso-session
section is the value, such as sso-session =
<name-of-sso-session-section>
.
The following example configures a profile that will get short-term AWS
credentials for the "SampleRole" IAM role in the "111122223333"
account using a token from the "my-sso". The "my-sso"
sso-session
section is referenced in the profile
section by name using the sso-session
key.
[profile
dev
] sso_session =my-sso
sso_account_id =111122223333
sso_role_name =SampleRole
[sso-sessionmy-sso
] sso_region =us-east-1
sso_start_url =https://my-sso-portal.awsapps.com/start
Section type: services
Example section definition line: [services
dev
]
Note
The services
section supports service-specific endpoint
customizations and is only available in SDKs and tools that include this
feature. To see if this feature is available for your SDK, see Compatibility with AWS SDKS for service-specific
endpoints.
The services
section definition line names a group of settings
that configures custom endpoints for AWS service requests. A profile is linked
to a services
section by a key-value pair where
services
is the key and the name of your services
section is the value, such as services =
<name-of-services-section>
.
The services
section is further separated into subsections by
<SERVICE> =
lines, where <SERVICE>
is
the AWS service identifier key. The AWS service identifier is based on the
API model’s serviceId
by replacing all spaces with underscores and
lowercasing all letters. For a list of all service identifier keys to use in the
services
section, see Identifiers for service-specific endpoints. The service identifier key is followed
by nested settings with each on its own line and indented by two spaces.
The following example uses a services
definition to configure
the endpoint to use for requests made only to the Amazon DynamoDB
service. The "local-dynamodb"
services
section is referenced in the profile
section
by name using the services
key. The AWS service identifier key is
dynamodb
. The Amazon DynamoDB service subsection begins
on the line dynamodb =
. Any immediately following lines that are
indented are included in that subsection and apply to that service.
[profile
dev
] services =local-dynamodb
[serviceslocal-dynamodb
] dynamodb = endpoint_url =http://localhost:8000
For more information on custom endpoint configuration, see Service-specific endpoints.
Format of the credentials file
The rules for the credentials
file are generally identical to
those for the config
file, except that profile sections don't begin
with the word profile
. Use only the unique profile name itself between
square brackets.
[
dev
] ...settings...
You can store only a small subset of settings and values in the
credentials
file. Generally, it's only those with values that
would be considered "secrets" or sensitive, such as access key IDs and secret keys. The
page for each setting in this guide states whether it can be stored in the
credentials
file or only in the config
file.
The following example shows a basic credentials
file with a
[default]
profile. It sets the aws_access_key_id and
aws_secret_access_key global settings.
[default] aws_access_key_id=
AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE