Using AWS Credentials

Each AWS Tools for PowerShell command must include a set of AWS credentials, which are used to cryptographically sign the corresponding web service request. You can specify credentials per command, per session, or for all sessions.

As a best practice, to avoid exposing your credentials, do not put literal credentials in a command. Instead, create a profile for each set of credentials that you want to use, and store the profile in either of two credential stores. Specify the correct profile by name in your command, and the AWS Tools for PowerShell retrieves the associated credentials. For a general discussion of how to safely manage AWS credentials, see Best Practices for Managing AWS Access Keys in the Amazon Web Services General Reference.

Credentials Store Locations

The AWS Tools for PowerShell can use either of two credentials stores:

Managing Profiles

Profiles enable you to reference different sets of credentials with AWS Tools for PowerShell. You can use AWS Tools for PowerShell cmdlets to manage your profiles in the AWS SDK store. You can also manage profiles in the AWS SDK store by using the Toolkit for Visual Studio or programmatically by using the AWS SDK for .NET. For directions about how to manage profiles in the credentials file, see Best Practices for Managing AWS Access Keys.

Add a New profile

To add a new profile to the AWS SDK store, run the command Set-AWSCredential. It stores your access key and secret key in your default credentials file under the profile name you specify.

PS > Set-AWSCredential `
                 -AccessKey AKIA0123456787EXAMPLE `
                 -SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY `
                 -StoreAs MyNewProfile

Update a Profile

The AWS SDK store must be maintained manually. If you later change credentials on the service—for example, by using the IAM console—running a command with the locally stored credentials fails with the following error message:

The Access Key Id you provided does not exist in our records.

You can update a profile by repeating the Set-AWSCredential command for the profile, and passing it the new access and secret keys.

List Profiles

You can check the current list of names with the following command. In this example, a user named Shirley has access to three profiles that are all stored in the shared credentials file (~/.aws/credentials).

PS > Get-AWSCredential -ListProfileDetail

ProfileName  StoreTypeName         ProfileLocation
-----------  -------------         ---------------
default      SharedCredentialsFile /Users/shirley/.aws/credentials
production   SharedCredentialsFile /Users/shirley/.aws/credentials
test         SharedCredentialsFile /Users/shirley/.aws/credentials

Remove a Profile

To remove a profile that you no longer require, use the following command.

PS > Remove-AWSCredentialProfile -ProfileName an-old-profile-I-do-not-need

The -ProfileName parameter specifies the profile that you want to delete.

The deprecated command Clear-AWSCredential is still available for backward compatibility, but Remove-AWSCredentialProfile is preferred.

Specifying Credentials

There are several ways to specify credentials. The preferred way is to identify a profile instead of incorporating literal credentials into your command line. AWS Tools for PowerShell locates the profile using a search order that is described in Credentials Search Order.

On Windows, AWS credentials stored in the AWS SDK store are encrypted with the logged-in Windows user identity. They cannot be decrypted by using another account, or used on a device that's different from the one on which they were originally created. To perform tasks that require the credentials of another user, such as a user account under which a scheduled task will run, set up a credential profile, as described in the preceding section, that you can use when you log in to the computer as that user. Log in as the task-performing user to complete the credential setup steps, and create a profile that works for that user. Then log out and log in again with your own credentials to set up the scheduled task.

Default Profile (Recommended)

All AWS SDKs and management tools can find your credentials automatically on your local computer if the credentials are stored in a profile named default. For example, if you have a profile named default on the local computer, you don't have to run either the Initialize-AWSDefaultConfiguration cmdlet or the Set-AWSCredential cmdlet. The tools automatically use the access and secret key data stored in that profile. To use an AWS Region other than your default Region (the results of Get-DefaultAWSRegion), you can run Set-DefaultAWSRegion and specify a Region.

If your profile is not named default, but you want to use it as the default profile for the current session, run Set-AWSCredential to set it as the default profile.

Although running Initialize-AWSDefaultConfiguration lets you specify a default profile for every PowerShell session, the cmdlet loads credentials from your custom-named profile, but overwrites the default profile with the named profile.

We recommend that you do not run Initialize-AWSDefaultConfiguration unless you are running a PowerShell session on an Amazon EC2 instance that was not launched with an instance profile, and you want to set up the credential profile manually. Note that the credential profile in this scenario would not contain credentials. The credential profile that results from running Initialize-AWSDefaultConfiguration on an EC2 instance doesn't directly store credentials, but instead points to instance metadata (that provides temporary credentials that automatically rotate). However, it does store the instance's Region. Another scenario that might require running Initialize-AWSDefaultConfiguration occurs if you want to run a call against a Region other than the Region in which the instance is running. Running that command permanently overrides the Region stored in the instance metadata.

PS > Initialize-AWSDefaultConfiguration -ProfileName MyProfileName -Region us-west-2

If your EC2 instance was launched with an instance profile, PowerShell automatically gets the AWS credentials and Region information from the instance profile. You don't need to run Initialize-AWSDefaultConfiguration. Running the Initialize-AWSDefaultConfiguration cmdlet on an EC2 instance launched with an instance profile isn't necessary, because it uses the same instance profile data that PowerShell already uses by default.

Session Profile

Use Set-AWSCredential to specify a default profile for a particular session. This profile overrides any default profile for the duration of the session. We recommend this if you want to use a custom-named profile in your session instead of the current default profile.

PS > Set-AWSCredential -ProfileName MyProfileName

Command Profile

On individual commands, you can add the -ProfileName parameter to specify a profile that applies to only that one command. This profile overrides any default or session profiles, as shown in the following example.

PS > Get-EC2Instance -ProfileName MyProfileName

PS > Initialize-AWSDefaultConfiguration -ProfileName MyProfileName -Region us-west-2

By default, the AWS shared credentials file is assumed to be in the user's home folder (C:\Users\username\.aws on Windows, or ~/.aws on Linux). To specify a credentials file in a different location, include the -ProfileLocation parameter and specify the credentials file path. The following example specifies a non-default credentials file for a specific command.

PS > Get-EC2Instance -ProfileName MyProfileName -ProfileLocation C:\aws_service_credentials\credentials

Credentials Search Order

When you run a command, AWS Tools for PowerShell searches for credentials in the following order. It stops when it finds usable credentials.

If this search fails to locate the specified credentials, the command throws an exception.

Credential Handling in AWS Tools for PowerShell Core

Cmdlets in AWS Tools for PowerShell Core accept AWS access and secret keys or the names of credential profiles when they run, similarly to the AWS Tools for Windows PowerShell. When they run on Windows, both modules have access to the AWS SDK for .NET credential store file (stored in the per-user AppData\Local\AWSToolkit\RegisteredAccounts.json file).

This file stores your keys in encrypted format, and cannot be used on a different computer. It is the first file that the AWS Tools for PowerShell searches for a credential profile, and is also the file where the AWS Tools for PowerShell stores credential profiles. For more information about the AWS SDK for .NET credential store file, see Configuring AWS Credentials. The Tools for Windows PowerShell module does not currently support writing credentials to other files or locations.

Both modules can read profiles from the AWS shared credentials file that is used by other AWS SDKs and the AWS CLI. On Windows, the default location for this file is C:\Users\<userid>\.aws\credentials. On non-Windows platforms, this file is stored at ~/.aws/credentials. The -ProfileLocation parameter can be used to point to a non-default file name or file location.

The SDK credential store holds your credentials in encrypted form by using Windows cryptographic APIs. These APIs are not available on other platforms, so the AWS Tools for PowerShell Core module uses the AWS shared credentials file exclusively, and supports writing new credential profiles to the shared credential file.

The following example scripts that use the Set-AWSCredential cmdlet show the options for handling credential profiles on Windows with either the AWSPowerShell or AWSPowerShell.NetCore modules.

# Writes a new (or updates existing) profile with name "myProfileName"
# in the encrypted SDK store file

Set-AWSCredential -AccessKey akey -SecretKey skey -StoreAs myProfileName

# Checks the encrypted SDK credential store for the profile and then
# falls back to the shared credentials file in the default location

Set-AWSCredential -ProfileName myProfileName

# Bypasses the encrypted SDK credential store and attempts to load the
# profile from the ini-format credentials file "mycredentials" in the
# folder C:\MyCustomPath

Set-AWSCredential -ProfileName myProfileName -ProfileLocation C:\MyCustomPath\mycredentials

The following examples show the behavior of the AWSPowerShell.NetCore module on the Linux or macOS operating systems.

# Writes a new (or updates existing) profile with name "myProfileName"
# in the default shared credentials file ~/.aws/credentials

Set-AWSCredential -AccessKey akey -SecretKey skey -StoreAs myProfileName

# Writes a new (or updates existing) profile with name "myProfileName"
# into an ini-format credentials file "~/mycustompath/mycredentials"

Set-AWSCredential -AccessKey akey -SecretKey skey -StoreAs myProfileName -ProfileLocation ~/mycustompath/mycredentials

# Reads the default shared credential file looking for the profile "myProfileName"

Set-AWSCredential -ProfileName myProfileName

# Reads the specified credential file looking for the profile "myProfileName"

Set-AWSCredential -ProfileName myProfileName -ProfileLocation ~/mycustompath/mycredentials