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).

Login for Amazon local development using console credentials

You can use your existing Amazon Management Console sign-in credentials for programmatic access to Amazon services. After a browser-based authentication flow, Amazon generates temporary credentials that work across local development tools like the Amazon CLI, Amazon Tools for PowerShell and Amazon SDKs. This feature simplifies the process of configuring and managing Amazon CLI credentials, especially if you prefer interactive authentication over managing long-term access keys.

With this process, you can authenticate using root credentials created during initial account set up, an IAM user, or a federated identity from your identity provider, and the Amazon CLI automatically manages the temporary credentials for you. This approach enhances security by eliminating the need to store long-term credentials locally.

When you run the aws login command, you can select from your active console sessions, or sign in through the browser-based authentication flow and this will automatically generate temporary credentials. The CLI will automatically refresh these credentials for up to 12 hours.

Once configured, your session can be used in the Amazon CLI and other Amazon SDKs and Tools.

Prerequisites

Log in to the Amazon CLI with the aws login command.

Run the aws login command to authenticate using your existing Amazon Management Console credentials. If you have not previously configured a profile, you're prompted for additional information. To sign in or configure a profile follow the below steps.

Generated configuration file

These steps result in creating the default profile in the config file that looks like the following:

[default]
login_session = arn:aws:iam::0123456789012:user/username
region = us-east-1

Run a command with your profile

Once signed in, you can use your credentials to invoke Amazon CLI commands with the associated profile. The following example calls the get-caller-identity command using the default profile:

$ aws sts get-caller-identity

To sign in to a specific session, use the --profile option.

$ aws sts get-caller-identity --profile my-dev-profile

The Amazon CLI and SDKs will automatically refresh the cached credentials every 15 minutes as needed. The overall session will be valid for up to the set session duration of the IAM principal (maximum of 12 hours), after which you must run aws login again.

Sign out of your session using the aws logout command

When you are done using your session, you can let your credentials expire, or run the aws logout command to delete your cached credentials. If no profile is specified on the command line or in the AWS_PROFILE environment variable, the command signs you out of your default profile. The following example signs you out of your default profile.

$ aws logout

To sign out of a specific session, use the --profile option.

$ aws logout --profile my-dev-profile

To sign out of all profiles that use login credentials, use the --all option.

$ aws logout --all

Cached Credentials

The temporary cached credentials, as well as the metadata required to refresh them are stored by default in ~/.aws/login/cache on Linux and macOS, or %USERPROFILE%\.aws\login\cache on Windows.

To store the short-term credentails cache in an alternative location, set the AWS_LOGIN_CACHE_DIRECTORY environment variable.

Sharing Login credentials as process credentials

Older versions of the Amazon SDKs or other development tools may not support console credentials yet. As a workaround, you can configure the Amazon CLI to serve as a process credentials provider. The CLI will continue to refresh the credentials as needed, while sharing them with tools configured to use the credential_process profile.

In this example, use the Amazon CLI to login first for profile signin:

$ aws login --profile signin

Then, manually configure a profile with the credential_process option, which points back at the signin profile. Now you can configure SDKs or tools to use the process profile, which will invoke the CLI to share the credentials from the signin profile.

[profile signin]
login_session = arn:aws:iam::0123456789012:user/username
region = us-east-1

[profile process] 
credential_process = aws configure export-credentials --profile signin --format process
region = us-east-1

Troubleshooting

This page contains recommendations for toubleshooting issues with logging in for Amazon local development using console credentials for the Amazon CLI.

ExpiredToken or AccessDeniedException errors after using "aws login"

When running an Amazon CLI command after running aws login for a given profile, you may encounter an expired or invalid credentials error.

$ aws s3 ls

An error occurred (ExpiredToken) when calling the ListBuckets operation: The provided token has expired.

Possible cause: You have a mix of existing credentials and the new login credentials in that profile

Run aws configure list or aws configure list --profile <profile name> to print where the CLI is resolving credentials from for either the default or the given profile.

If the TYPE column is something other than login, this means that there is still a different type of credentials set in the target profile.

In this example, credentials are being resolved from the shared credentials file in your home directory, which has precedence over the login credentials.

$  aws configure list
NAME       : VALUE                    : TYPE             : LOCATION
profile    : <not set>                : None             : None
access_key : ****************MPLE     : shared-credentials-file :
secret_key : ****************EKEY     : shared-credentials-file :
region     : us-east-1                : config-file      : ~/.aws/config

To address this, manually remove any existing credentials from your config and credentials file for the target profile. Once you do so, you should see login credentials when running aws configure list again.

$  aws configure list
NAME       : VALUE                    : TYPE             : LOCATION
profile    : <not set>                : None             : None
access_key : ****************MPLE     : login            :
secret_key : ****************EKEY     : login            :
region     : us-east-1                : config-file      : ~/.aws/config

Alternatively using the --debug option will show where the CLI is resolving credentials from.

Firewall blocking network access when running "aws login"

When running aws login you may encounter a popup or message from your firewall software that prevents the Amazon CLI from accessing your network

Possible cause: Your firewall or security software is preventing the Amazon CLI from opening the port used to handle the OAuth callback.

To avoid this issue, use the --remote option instead. This will prompt you to copy and paste the authorization code instead of using the OAuth callback.

$ aws login --remote

Related resources

Additional resources are as follows.