The shared config and credentials files - AWS SDKs and Tools

The shared config and credentials files

AWS SDKs and other AWS developer tools, such as the AWS Command Line Interface (AWS CLI) enable you to interact with AWS service APIs. Before attempting that, however, you must configure the SDK or tool with the information it needs to perform the requested operation.

This information includes the following items:

  • Credentials information that identifies who is calling the API. The credentials are used to encrypt the request to the AWS servers. Using this information, AWS confirms your identity and can retrieve permission policies associated with it. Then it can determine what actions you're allowed to perform.

  • Other configuration details that enable you to tell the AWS CLI or SDK how to process the request, where to send the request (to which AWS service endpoint), and how to interpret or display the response.

About credential providers

Each SDK or tool can provide multiple methods, called credential providers, that you can use to supply the required credential and configuration information. Some credential providers are unique to the SDK or tool, and you must refer to the documentation for that tool or SDK for the details on how to use that method.

However, most of the AWS SDKs and tools share a few common credential providers for finding the required information. These methods are the subject of this guide.

  • Shared AWS config and credentials files – The shared config and credentials files are the most common way that you can specify authentication and configuration to an AWS SDK or tool. These files enable you to store settings that your tools and applications can use. The primary file is config, and you can put all settings into it. However, by default and as a security best practice, sensitive values such as secret keys are stored in a separate credentials file. This enables you to separately protect those settings with different permissions. Together, these files enable you to configure multiple groups of settings. Each group of settings is called a profile. When you use an AWS tool to invoke a command or use an SDK to invoke an AWS API, you can specify which profile, and thus which configuration settings, to use for that action. One of the profiles is designated as the default profile and is used automatically when you don't explicitly specify a profile to use. The settings that you can store in these files are documented in this reference guide.

  • Environment variables – Some of the settings can alternatively be stored in the environment variables of your operating system. While you can have only one set of environment variables in effect at a time, they are easily modified dynamically as your program runs and your requirements change.

  • Per-operation parameters – A few settings can be set on a per-operation basis, and thus changed as needed for each operation you invoke. For the AWS CLI or AWS Tools for PowerShell, these take the form of parameters that you enter on the command line. For an SDK, they can take the form of a parameter that you set when you instantiate an AWS client session or service object, or sometimes when you call an individual API.

Precedence and credential provider order

When an AWS SDK or tool looks for credentials or a configuration setting, it invokes each credential provider in a certain order, and stops when it finds a value that it can use. Most AWS SDKs and tools check the credential providers in the following order:

  1. Per-operation parameter

  2. Environment variable

  3. Shared credentials file

  4. Shared config file

Note

If a setting exists in both the config file and the credentials file for the same profile, the value in the credentials file is used instead of the value in the config file.

Note

Some SDKs and tools might check in a different order. Also, some SDKs and tools support other methods of storing and retrieving parameters. For example, the AWS SDK for .NET supports an additional credential provider called the SDK Store. For more information about the credential provider order or credential providers that are unique to a SDK or tool, see the documentation for that SDK or tool.

The order determines which methods take precedence and override others. For example, if you set up a default profile in the shared config file, it's only found and used after the SDK or tool checks the other credential providers first. This means that if you put a setting in the credentials file, it is used instead of one found in the config file. If you configure an environment variable with a setting and value, it would override that setting in both the credentials and config files. And finally, a setting on the individual operation (AWS CLI command-line parameter or API parameter), would override all other values for that one command.

Additional topics in this section