Authentication and access credentials for the Amazon CLI - Amazon Command Line Interface
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.

Authentication and access credentials for the Amazon CLI

You must establish how the Amazon CLI authenticates with Amazon when you develop with Amazon services. To configure credentials for programmatic access for the Amazon CLI, choose one of the following options. The options are in order of recommendation.

Authentication type Purpose Instructions
IAM user short-term credentials Use IAM user short-term credentials, which are more secure than long-term credentials. If your credentials are compromised, there is a limited time they can be used before they expire. Authenticating with short-term credentials for the Amazon CLI
IAM on an Amazon EC2 instance. Use Amazon EC2 instance metadata to query for temporary credentials using the role assigned to the Amazon EC2 instance. Using Amazon EC2 instance metadata as credentials in the Amazon CLI
Assume roles for permissions Pair another credential method and assume a role for temporary access to Amazon Web Services services your user might not have access to. Using an IAM role in the Amazon CLI
IAM user long-term credentials (Not recommended) Use long-term credentials, which have no expiration. Authenticating using IAM user credentials for the Amazon CLI
External storage of IAM (Not recommended) Pair another credential method but store credential values in a location outside of the Amazon CLI. This method is only as secure as the external location the credentials are stored. Sourcing credentials with an external process in the Amazon CLI

Configuration and credential precedence

Credentials and configuration settings are located in multiple places, such as the system or user environment variables, local Amazon configuration files, or explicitly declared on the command line as a parameter. Certain locations take precedence over others. The Amazon CLI credentials and configuration settings take precedence in the following order:

  1. Command line options – Overrides settings in any other location, such as the --region, --output, and --profile parameters.

  2. Environment variables – You can store values in your system's environment variables.

  3. Assume role – Assume the permissions of an IAM role through configuration or the assume-role command.

  4. Assume role with web identity – Assume the permissions of an IAM role using web identity through configuration or the assume-role-with-web-identity command.

  5. Credentials file – The credentials and config file are updated when you run the command aws configure. The credentials file is located at ~/.aws/credentials on Linux or macOS, or at C:\Users\USERNAME\.aws\credentials on Windows.

  6. Custom process – Get your credentials from an external source.

  7. Configuration file – The credentials and config file are updated when you run the command aws configure. The config file is located at ~/.aws/config on Linux or macOS, or at C:\Users\USERNAME\.aws\config on Windows.

  8. Container credentials – You can associate an IAM role with each of your Amazon Elastic Container Service (Amazon ECS) task definitions. Temporary credentials for that role are then available to that task's containers. For more information, see IAM Roles for Tasks in the Amazon Elastic Container Service Developer Guide.

  9. Amazon EC2 instance profile credentials – You can associate an IAM role with each of your Amazon Elastic Compute Cloud (Amazon EC2) instances. Temporary credentials for that role are then available to code running in the instance. The credentials are delivered through the Amazon EC2 metadata service. For more information, see IAM Roles for Amazon EC2 in the Amazon EC2 User Guide and Using Instance Profiles in the IAM User Guide.

Additional topics in this section