AWS Tools and SDKs Shared Configuration and Credentials Reference Guide - AWS SDKs and Tools Shared Configuration and Credentials

AWS Tools and SDKs Shared Configuration and Credentials Reference Guide

Go right to the list of global settings.

Go right to the list of per-service settings.

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 tool or SDK 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 tool or SDK, 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 tools and SDKs 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 – 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 tool or SDK 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 tools and SDKs check the credential providers in the following order:

  1. Per-operation parameter

  2. Environment variable

  3. Shared credentials file

  4. Shared config file


Some tools and SDKs might check in a different order. Also, some tools and SDKs 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 tool or SDK, see the documentation for that tool or SDK.

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's 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 (CLI command-line parameter or API parameter), would override all other values for that one command.