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. These files are "shared" in that the values take affect for any applications, processes, or SDKs on the local environment for a user.

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.

Set a named profile

Instead of using the [default] profile, you can set a named profile.

Configure this functionality by setting one of the following:

AWS_PROFILE - environment variable

All SDK code and AWS CLI commands use the settings in this named profile.

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"

aws.profile - JVM system property

For SDKs that run on a JVM, you can set the aws.profile system property. When the SDK creates a service client, it uses the settings in the named profile unless the setting is overridden in code.

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. 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-session my-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

[services local-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