Using sharedconfig andcredentials files to globally configure AWS SDKs and tools
The shared AWSconfig andcredentials files are the most common way that you can specify authentication and configuration to an AWS SDK or tool.
The sharedconfig andcredentials files contain a set of profiles. A profile is a set of configuration settings, in key–value pairs, that is used by AWS SDKs, the AWS Command Line Interface (AWS CLI), and other tools. 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.
Both the sharedconfig andcredentials files are plaintext files that contain only ASCII characters (UTF-8 encoded). They take the form of what are generally referred to asINI files.
Profiles
Settings within the sharedconfig andcredentials files are associated with a specific profile. Multiple profiles can be defined within the file to create different setting configurations to apply in different development environments.
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 profile can use different settings and values as needed by your application and scenario.
[default] is simply an unnamed profile. This profile is nameddefault 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. 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
The[default] profile and multiple named profiles can exist in the same file. Use the following setting to select which profile's settings are used by your SDK or tool when running your code. Profiles can also be selected within code, or per-command when working with the AWS CLI.
Configure this functionality by setting one of the following:
AWS_PROFILE- environment variableWhen this environment variable is set to a named profile or "default", all SDK code and AWS CLI commands use the settings in that 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 propertyFor SDK for Kotlin on the JVM and the SDK for Java 2.x, you canset 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. The SDK for Java 1.x does not support this system property.
If your application is on a server running multiple applications, we recommend you always used named profiles rather than the default profile. The default profile is automatically picked up by any AWS application in the environment and is shared amongst them. Thus, if someone else updates the default profile for their application it can unintentionally impact the others. To safeguard against this, define a named profile in the sharedconfig file and then use that named profile in your application by setting the named profile in your code. You can use the environment variable or JVM system property to set the named profile if you know that it's scope only affects your application.
Format of the config file
Theconfig file is organized into sections. A section is a named collection of settings, and continues until another section definition line is encountered.
Theconfig 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:default
Example section definition line:[default]
[default] is the only profile that does not require theprofile section identifier.
The following example shows a basicconfig file with a[default] profile. It sets theregion setting. All settings that follow this line, up until another section definition is encountered, are part of this profile.
[default]#Full line comment, this text is ignored.region = us-east-2Section type:profile
Example section definition line:[profiledev]
Theprofile section definition line is a named configuration grouping that you can apply for different development scenarios. To better understand named profiles, see the preceding section on Profiles.
The following example shows aconfig file with aprofile section definition line and a named profile calledfoo. All settings that follow this line, up until another section definition is encountered, are part of this named profile.
[profilefoo]...settings...Some settings have their own nested group of subsettings, such as thes3 setting and subsettings in the following example. Associate the subsettings with the group by indenting them by one or more spaces.
[profile test]region = us-west-2s3 = max_concurrent_requests=10 max_queue_size=1000Section type:sso-session
Example section definition line:[sso-sessionmy-sso]
Thesso-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, seeUsing IAM Identity Center to authenticate AWS SDK and tools. A profile is linked to asso-session section by a key-value pair wheresso-session is the key and the name of yoursso-session section is the value, such assso-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 theprofile section by name using thesso-session key.
[profiledev]sso_session =my-ssosso_account_id =111122223333sso_role_name =SampleRole[sso-sessionmy-sso]sso_region =us-east-1sso_start_url =https://my-sso-portal.awsapps.com/startSection type:services
Example section definition line:[servicesdev]
Theservices 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, seeSupport by AWS SDKs and tools for service-specific endpoints.
Theservices section definition line names a group of settings that configures custom endpoints for AWS service requests. A profile is linked to aservices section by a key-value pair whereservices is the key and the name of yourservices section is the value, such asservices = <name-of-services-section>.
Theservices 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'sserviceId by replacing all spaces with underscores and lowercasing all letters. For a list of all service identifier keys to use in theservices section, seeIdentifiers 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 aservices definition to configure the endpoint to use for requests made only to the Amazon DynamoDB service. The"local-dynamodb"services section is referenced in theprofile section by name using theservices key. The AWS service identifier key isdynamodb. The Amazon DynamoDB service subsection begins on the linedynamodb =. Any immediately following lines that are indented are included in that subsection and apply to that service.
[profiledev]services =local-dynamodb[serviceslocal-dynamodb]dynamodb = endpoint_url =http://localhost:8000For more information on custom endpoint configuration, seeService-specific endpoints.
Format of the credentials file
The rules for thecredentials file are generally identical to those for theconfig file, except that profile sections don't begin with the wordprofile. Use only the profile name itself between square brackets. The following example shows acredentials file with a named profile section calledfoo.
[foo]...credential settings...Only the following settings that are considered "secrets" or sensitive can be stored in thecredentials file:aws_access_key_id,aws_secret_access_key, andaws_session_token. Although these settings can alternatively be placed in the sharedconfig file, we recommend that you keep these sensitive values in the separatecredentials file. This way, you can provide separate permissions for each file, if necessary.
The following example shows a basiccredentials file with a[default] profile. It sets theaws_access_key_id,aws_secret_access_key, and aws_session_token global settings.
[default]aws_access_key_id=AKIAIOSFODNN7EXAMPLEaws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYaws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLERegardless of whether you use a named profile or "default" in yourcredentials file, any settings here will be combined with any settings from yourconfig file that uses the same profile name. If there are credentials in both files for a profile sharing the same name, the keys in the credentials file take precedence.
