Shared AWSconfig and credentials files - AWS SDKs and Tools

Shared AWSconfig 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.

We recommend downloading these files from the AWS Management Console by following the instructions for Managing access keys in the IAM User Guide.

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_named_profile";

Windows example of setting environment variables via command line:

setx AWS_PROFILE "my_named_profile"

Format of the config file

The config file must be a plaintext file that uses the following format:

  • Each section begins with the profile name in square brackets [ ].

  • 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 (#).

The following example shows a basic config file having a [default] profile. It sets the region global setting.

[default] #Full line comment, this text is ignored. region = us-east-2

To create a named profile in the config file, create a section with a new header, similar to the following example. You must use the word profile and follow it with a unique name. You can use letters, numbers, hyphens ( - ), and underscores ( _ ), but no spaces.

[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

Format of the credentials 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

The rules for the credentials file are generally identical to those for the config file, with the following exceptions:

  • The section names don't begin with the word profile. Use only the profile name itself between square brackets.

    [developers] ...settings...
  • You can store only a 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.

Example files

In summary, each profile can have some settings in each file. The majority of settings go in the config file, while the sensitive information settings go in the credentials file.

The following example shows three profiles stored in these two files:

  • default profile – Provides access by using the long-term credentials of an AWS Identity and Access Management (IAM) user. Tools or code that use this profile send requests to the US West (Oregon) Region (us-west-2). AWS CLI commands invoked using this profile output the results as JSON.

  • dev-user profile – Uses the long-term credentials of a different IAM user. Tools or code that use this profile send requests to the US West (N. California) Region (us-west-1). AWS CLI commands invoked using this profile output the results as text.

  • developers profile – Uses short-term credentials from assuming the specified role. It uses the long-term credentials in the dev-user source profile only to assume the role and retrieve the short-term credentials for the role. Tools or code that use this profile send requests to the US West (Oregon) Region (us-west-2). AWS CLI commands invoked using this profile output the results as JSON. This profile doesn't store any of its values in the credentials file.

Contents of the config file

[default] region = us-west-2 output = json [profile dev-user] region = us-west-1 output = text [profile developers] role_arn = arn:aws:iam::123456789012:role/developers source_profile = dev-user region = us-west-2 output = json

Contents of the credentials file

[default] aws_access_key_id = AKIAIOSFODNN7EXAMPLE aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY [dev-user] aws_access_key_id = AKIAI44QH8DHBEXAMPLE aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY