PDF Edit on GitHub

Using AWS Credentials

Each Tools for Windows 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 credentials stores. Specify the correct profile by name in your command, and the Tools for Windows PowerShell retrieve the associated credentials. For a general discussion of how to safely manage AWS credentials, see Best Practices for Managing AWS Access Keys.

Note

If you do not yet have an AWS account, you will need one in order to obtain credentials and use the Tools for Windows PowerShell. For information about how to sign up for an account, see AWS Account and Access Keys.

Managing Profiles

The Tools for Windows PowerShell can use either of two credentials stores.

  • The AWS SDK store, which encrypts your credentials and stores them in your home folder.

    The AWS SDK for .NET and Toolkit for Visual Studio can also use the AWS SDK store.

  • The credentials file, which is also located in your home folder, but stores credentials as plain text.

    By default, the credentials file is stored here: C:\Users\username\.aws. The AWS SDKs and the AWS Command Line Interface can also use the credentials file. If you are running a script outside of your AWS user context, be sure that the file that contains your credentials is copied to a location where all user accounts (local system and user) can access your credentials.

This topic describes how to use the Tools for Windows PowerShell to manage your profiles in the AWS SDK store. You can also manage 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, call Set-AWSCredentials as follows:

PS C:\> Set-AWSCredentials -AccessKey {AKIAIOSFODNN7EXAMPLE} -SecretKey {wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY} -StoreAs {MyProfileName}
  • -AccessKey – The access key.

  • -SecretKey – The secret key.

  • -StoreAs – The profile name, which must be unique.

    To specify the default profile, set the profile name to default.

Update a profile

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

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

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

List profiles

You can check the current list of names as follows:

PS C:\> Get-AWSCredentials -ListStoredCredentials

Remove a profile

To remove a profile, use the following command:

PS C:\> Clear-AWSCredentials -StoredCredentials {MyProfileName}

The -StoredCredentials parameter specifies the profile name.

Specifying Credentials

There are several ways to specify credentials. The preferred approach is to use a profile rather than incorporating literal credentials into your command line. The Tools for Windows PowerShell locates the profile using a search order that is described in Credentials Search Order. This section describes the most common ways to specify a profile.

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

Note

You use the -ProfileName parameter to specify a profile. This parameter is equivalent to the -StoredCredentials parameter used by earlier Tools for Windows PowerShell releases. For backward compatibility, -StoredCredentials is still supported.

Default profile (recommended)

Use Initialize-AWSDefaults to specify a default profile for every PowerShell session.

PS C:\> Initialize-AWSDefaults -ProfileName {MyProfileName} -Region {us-west-2}

Note

The default credentials are included in the AWS SDK store under the default profile name. The command overwrites any existing profile with that name.

Session profile

Use Set-AWSCredentials to specify a default profile for a particular session. This profile overrides any default profile for the duration of the session.

PS C:\> Set-AWSCredentials -ProfileName {MyProfileName}

Note

In versions of the Tools for Windows PowerShell that are older than 1.1, the Set-AWSCredentials command did not work correctly, and would overwrite the profile specified by {MyProfileName}. We recommend using a more recent version of the Tools for Windows PowerShell.

Command profile

Add the -ProfileName parameter to specify a profile for a particular command. This profile overrides any default or session profiles. For example:

PS C:\> Get-EC2Instance -ProfileName {MyProfileName}

Tip

When you specify a default or session profile, you can also add a -Region parameter to specify a default or session region. For more information, see Specifying AWS Regions. The following example specifies a default profile and region.

PS C:\> Initialize-AWSDefaults -ProfileName {MyProfileName} -Region {us-west-2}

By default, the credentials file is assumed to be in the user’s home folder (C:usersusername.aws). To specify a credentials file in another location, include a -ProfilesLocation parameter, set to the credentials file path. The following example specifies a non-default credentials file for a specific command.

PS C:\> Get-EC2Instance -ProfileName {MyProfileName} -ProfilesLocation C:\aws_service_credentials\credentials

Tip

If you are running a PowerShell script during a time that you are not normally signed in to AWS—for example, you are running a PowerShell script as a scheduled task outside of your normal work hours—add the -ProfilesLocation parameter when you specify the profile that you want to use, and set the value to the path of the file that stores your credentials. To be certain that your Tools for Windows PowerShell script runs with the correct account credentials, you should add the -ProfilesLocation parameter whenever your script runs in a context or process that does not use an AWS account. You can also copy your credentials file to a location that is accessible to the local system or other account that your scripts use to perform tasks.

Credentials Search Order

When you run a command, the Tools for Windows PowerShell search for credentials in the following order, and uses the first available set.

  1. Use literal credentials that are embedded in the command line.

    We strongly recommend using profiles rather than putting literal credentials in your command lines.

  2. Use a specified profile name or profile location.

    • If you specify only a profile name, use a specified profile from the AWS SDK store and, if that does not exist, the specified profile from the credentials file in the default location.
    • If you specify only a profile location, use the default profile from that credentials file.
    • If you specify a name and a location, use the specified profile from that credentials file.

    If the specified profile or location is not found, the command throws an exception. Search proceeds to the following steps only if you have not specified a profile or location.

  3. Use credentials specified by the -Credentials parameter.

  4. Use a session profile.

  5. Use a default profile, in the following order:

    1. The default profile in the AWS SDK store.
    2. The default profile in the credentials file.
    3. Use the AWS PS Default profile in the AWS SDK store.
  6. If you are using running the command on an Amazon EC2 instance that is configured for an IAM role, use EC2 instance credentials stored in an instance profile.

    For more information about using IAM roles for Amazon EC2 Instances, see the AWS SDK for .NET.

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. The AWS Tools for PowerShell module does not currently support writing credentials to other files or locations.

Both modules can read profiles from the ini-format 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 -ProfilesLocation 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 ini-format shared credentials file exclusively, and supports writing new credential profiles to the shared credential file. This support is slated for a future release of the AWS Tools for Windows PowerShell.

The following examples that use the Set-AWSCredentials 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-AWSCredentials -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-AWSCredentials -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-AWSCredentials -ProfileName myProfileName -ProfilesLocation C:MyCustomPathmycredentials

The following examples show the behavior of the AWSPowerShell.NetCore module on the Linux or Mac OS X operating systems:


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

Set-AWSCredentials -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-AWSCredentials -AccessKey akey -SecretKey skey -StoreAs myProfileName -ProfilesLocation ~/mycustompath/mycredentials

# Reads the default shared credential file looking for the profile “myProfileName”

Set-AWSCredentials -ProfileName myProfileName

# Reads the specified credential file looking for the profile “myProfileName”

Set-AWSCredentials -ProfileName myProfileName -ProfilesLocation ~/mycustompath/mycredentials