Version 5 (V5) of the AWS Tools for PowerShell has been released\$1 For information about breaking changes and migrating your applications, see the [migration topic](https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html). [https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html](https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html) # Using legacy credentials The topics in this section provide information about using long-term or short-term credentials without using AWS IAM Identity Center. **Warning** To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). **Note** The information in these topics is for circumstances where you need to obtain and manage short-term or long-term credentials manually. For additional information about short-term and long-term credentials, see [Other ways to authenticate](https://docs.aws.amazon.com/sdkref/latest/guide/access-users.html) in the *AWS SDKs and Tools Reference Guide*. For best security practices, use AWS IAM Identity Center, as described in [Authenticating with AWS](creds-idc.md). ## Important warnings and guidance for credentials **Warnings for credentials** + ***Do NOT*** use your account's root credentials to access AWS resources. These credentials provide unrestricted account access and are difficult to revoke. + ***Do NOT*** put literal access keys or credential information in your commands or scripts. If you do, you create a risk of accidentally exposing your credentials. + Be aware that any credentials stored in the shared AWS `credentials` file, are stored in plaintext. **Additional guidance for securely managing credentials** For a general discussion of how to securely manage AWS credentials, see [AWS security credentials](https://docs.aws.amazon.com/general/latest/gr/Welcome.html#aws-security-credentials) in the [AWS General Reference](https://docs.aws.amazon.com/general/latest/gr/) and [Security best practices and use cases](https://docs.aws.amazon.com/IAM/latest/UserGuide/IAMBestPracticesAndUseCases.html) in the [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/). In addition to those discussions, consider the following: + Create additional users, such as users in IAM Identity Center, and use their credentials instead of using your AWS root user credentials. Credentials for other users can be revoked if necessary or are temporary by nature. In addition, you can apply a policy to each user for access to only certain resources and actions and thereby take a stance of least-privilege permissions. + Use [IAM roles for tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) for Amazon Elastic Container Service (Amazon ECS) tasks. + Use [IAM roles](shared-credentials-in-aws-powershell.md#shared-credentials-assume-role) for applications that are running on Amazon EC2 instances. **Topics** + [Important warnings and guidelines](#pstools-creds-warnings-and-guidelines) + [AWS Credentials](specifying-your-aws-credentials.md) + [Shared Credentials](shared-credentials-in-aws-powershell.md) # 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. **Warning** To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). **Note** The information in this topic is for circumstances where you need to obtain and manage short-term or long-term credentials manually. For additional information about short-term and long-term credentials, see [Other ways to authenticate](https://docs.aws.amazon.com/sdkref/latest/guide/access-users.html) in the *AWS SDKs and Tools Reference Guide*. For best security practices, use AWS IAM Identity Center, as described in [Authenticating with AWS](creds-idc.md). 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](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html) in the *Amazon Web Services General Reference*. **Note** You need an AWS account to get credentials and use the AWS Tools for PowerShell. To create an AWS account, see [Getting started: Are you a first-time AWS user?](https://docs.aws.amazon.com/accounts/latest/reference/welcome-first-time-user.html) in the *AWS Account Management Reference Guide*. **Topics** + [Credentials Store Locations](#specifying-your-aws-credentials-store) + [Managing Profiles](#managing-profiles) + [Specifying Credentials](#specifying-your-aws-credentials-use) + [Credentials Search Order](#pstools-cred-provider-chain-legacy) + [Credential Handling in AWS Tools for PowerShell Core](#credential-handling-in-aws-tools-for-powershell-core) ## Credentials Store Locations The AWS Tools for PowerShell can use either of two credentials stores: + The AWS SDK store, which encrypts your credentials and stores them in your home folder. In Windows, this store is located at: `C:\Users\username\AppData\Local\AWSToolkit\RegisteredAccounts.json`. The [AWS SDK for .NET](https://aws.amazon.com/sdk-for-net/) and [Toolkit for Visual Studio](https://aws.amazon.com/visualstudio/) can also use the AWS SDK store. + The shared credentials file, which is also located in your home folder, but stores credentials as plain text. By default, the credentials file is stored here: + On Windows: `C:\Users\username\.aws\credentials` + On Mac/Linux: `~/.aws/credentials` The AWS SDKs and the AWS Command Line Interface can also use the credentials file. If you're 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. ## 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](https://docs.aws.amazon.com/AWSToolkitVS/latest/UserGuide/tkv_setup.html) or programmatically by using the [AWS SDK for .NET](https://aws.amazon.com/sdk-for-net/). For directions about how to manage profiles in the credentials file, see [Best Practices for Managing AWS Access Keys](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html). ### 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 ``` + `-AccessKey`– The access key ID. + `-SecretKey`– The secret key. + `-StoreAs`– The profile name, which must be unique. To specify the default profile, use the name `default`. ### 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](https://console.aws.amazon.com/iam/home)—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](https://docs.aws.amazon.com/powershell/v5/reference/items/Clear-AWSCredential.html) 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](#pstools-cred-provider-chain-legacy). 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. **Note** Use the `-ProfileName` common parameter to specify a profile. This parameter is equivalent to the `-StoredCredentials` parameter in earlier AWS Tools for PowerShell releases. For backward compatibility, `-StoredCredentials` is still supported. ### 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 ``` **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. 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 ``` **Note** In versions of the Tools for Windows PowerShell that are earlier than 1.1, the `Set-AWSCredential` cmdlet 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 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 ``` **Note** When you specify a default or session profile, you can also add a `-Region` parameter to override a default or session Region. For more information, see [Specify the AWS Region for the AWS Tools for PowerShell](pstools-installing-specifying-region.md). The following example specifies a default profile and Region. ``` 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 ``` **Note** 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 `-ProfileLocation` 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 AWS Tools for PowerShell script runs with the correct account credentials, you should add the `-ProfileLocation` 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, AWS Tools for PowerShell searches for credentials in the following order. It stops when it finds usable credentials. 1. Literal credentials that are embedded as parameters in the command line. We strongly recommend using profiles instead of putting literal credentials in your command lines. 1. Credentials specified by the `-Credential` parameter. 1. A profile name or profile location that was specified by using the [Set-AWSCredential](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-AWSCredential.html) cmdlet. + If you specify only a profile name, the command looks for the specified profile in the AWS SDK store and, if that does not exist, the specified profile from the AWS shared credentials file in the default location. + If you specify only a profile location, the command looks for the `default` profile from that credentials file. + If you specify both a name and a location, the command looks for the specified profile in 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 did not specify a profile or location. 1. Credentials that are created from the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables, if all three variables have a value. 1. The credentials profile with the name specified by the `AWS_PROFILE` environment variable. 1. The default profile, in the following order: 1. The `default` profile in the AWS SDK store. 1. The `default` profile in the shared AWS `credentials` file. 1. The `AWS PS Default` profile in the AWS SDK store. 1. If the command is running on an Amazon EC2 instance that is configured to use an IAM role, the EC2 instance's temporary credentials accessed from the instance profile. For more information about using IAM roles for Amazon EC2 instances, see [Granting access with a role](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-hosm.html) in the [AWS SDK for .NET Developer Guide](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/). If this search fails to locate the specified credentials, the command throws an exception. For additional information about environment variables and credentials profiles, see the following topics in the [AWS SDKs and Tools Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/): [Environment variables](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html), [Environment variables list](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#EVarSettings), and [Shared config and credentials files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). ## 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](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-creds.html). 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\\.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 ``` # Shared Credentials in AWS Tools for PowerShell The Tools for Windows PowerShell support the use of the AWS shared credentials file, similarly to the AWS CLI and other AWS SDKs. The Tools for Windows PowerShell now support reading and writing of `basic`, `session`, and `assume role` credential profiles to both the .NET credentials file and the AWS shared credential file. This functionality is enabled by a new `Amazon.Runtime.CredentialManagement` namespace. **Warning** To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). **Note** The information in this topic is for circumstances where you need to obtain and manage short-term or long-term credentials manually. For additional information about short-term and long-term credentials, see [Other ways to authenticate](https://docs.aws.amazon.com/sdkref/latest/guide/access-users.html) in the *AWS SDKs and Tools Reference Guide*. For best security practices, use AWS IAM Identity Center, as described in [Authenticating with AWS](creds-idc.md). The new profile types and access to the AWS shared credential file are supported by the following parameters that have been added to the credentials-related cmdlets, [Initialize-AWSDefaultConfiguration](https://docs.aws.amazon.com/powershell/v5/reference/items/Initialize-AWSDefaultConfiguration.html), [New-AWSCredential](https://docs.aws.amazon.com/powershell/v5/reference/items/New-AWSCredential.html), and [Set-AWSCredential](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-AWSCredential.html). In service cmdlets, you can refer to your profiles by adding the common parameter, `-ProfileName`. ## Using an IAM Role with AWS Tools for PowerShell The AWS shared credential file enables additional types of access. For example, you can access your AWS resources by using an IAM role instead of the long term credentials of an IAM user. To do this, you must have a standard profile that has permissions to assume the role. When you tell the AWS Tools for PowerShell to use a profile that specified a role, the AWS Tools for PowerShell looks up the profile identified by the `SourceProfile` parameter. Those credentials are used to request temporary credentials for the role specified by the `RoleArn` parameter. You can optionally require the use of an multi-factor authentication (MFA) device or an `ExternalId` code when the role is assumed by a third party. **** | Parameter Name | Description | | --- | --- | | ExternalId | The user-defined external ID to be used when assuming a role, if required by the role. This is typically only required when you delegate access to your account to a third party. The third party must include the ExternalId as a parameter when assuming the assigned role. For more information, see [How to Use an External ID When Granting Access to Your AWS Resources to a Third Party](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) in the *IAM User Guide*. | | MfaSerial | The MFA serial number to be used when assuming a role, if required by the role. For more information, see [Using Multi-Factor Authentication (MFA) in AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html) in the *IAM User Guide*. | | RoleArn | The ARN of the role to assume for assume role credentials. For more information about creating and using roles, see [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *IAM User Guide*. | | SourceProfile | The name of the source profile to be used by assume role credentials. The credentials found in this profile are used to assume the role specified by the `RoleArn` parameter. | ### Setup of profiles for assuming a role The following is an example showing how to set up a source profile that enables directly assuming an IAM role. The first command creates a source profile that is referenced by the role profile. The second command creates the role profile that which role to assume. The third command shows the credentials for the role profile. ``` PS > Set-AWSCredential -StoreAs my_source_profile -AccessKey access_key_id -SecretKey secret_key PS > Set-AWSCredential -StoreAs my_role_profile -SourceProfile my_source_profile -RoleArn arn:aws:iam::123456789012:role/role-i-want-to-assume PS > Get-AWSCredential -ProfileName my_role_profile SourceCredentials RoleArn RoleSessionName Options ----------------- ------- --------------- ------- Amazon.Runtime.BasicAWSCredentials arn:aws:iam::123456789012:role/role-i-want-to-assume aws-dotnet-sdk-session-636238288466144357 Amazon.Runtime.AssumeRoleAWSCredentialsOptions ``` To use this role profile with the Tools for Windows PowerShell service cmdlets, add the `-ProfileName` common parameter to the command to reference the role profile. The following example uses the role profile defined in the previous example to access the [Get-S3Bucket](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3Bucket.html) cmdlet. AWS Tools for PowerShell looks up the credentials in `my_source_profile`, uses those credentials to call `AssumeRole` on behalf of the user, and then uses those temporary role credentials to call `Get-S3Bucket`. ``` PS > Get-S3Bucket -ProfileName my_role_profile CreationDate BucketName ------------ ---------- 2/27/2017 8:57:53 AM 4ba3578c-f88f-4d8b-b95f-92a8858dac58-bucket1 2/27/2017 10:44:37 AM 2091a504-66a9-4d69-8981-aaef812a02c3-bucket2 ``` ## Using the Credential Profile Types To set a credential profile type, understand which parameters provide the information required by the profile type. **** | Credentials Type | Parameters you must use | | --- | --- | | **Basic** These are the long term credentials for an IAM user | `-AccessKey` `-SecretKey` | | **Session**: These are the short term credentials for an IAM role that you retrieve manually, such as by directly calling the [Use-STSRole](https://docs.aws.amazon.com/powershell/v5/reference/items/Use-STSRole.html) cmdlet. | `-AccessKey` `-SecretKey` `-SessionToken` | | **Role**: These are are short term credentials for an IAM role that AWS Tools for PowerShell retrieve for you. | `-SourceProfile` `-RoleArn` optional: `-ExternalId` optional: `-MfaSerial` | ## The `ProfileLocation` Common Parameter You can use `-ProfileLocation` to write to the shared credential file as well as instruct a cmdlet to read from the credential file. Adding the `-ProfileLocation` parameter controls whether Tools for Windows PowerShell uses the shared credential file or the .NET credential file. The following table describes how the parameter works in Tools for Windows PowerShell. **** | Profile Location Value | Profile Resolution Behavior | | --- | --- | | null (not set) or empty | First, search the .NET credential file for a profile with the specified name. If the profile isn't found, search the AWS shared credentials file at `(user's home directory)\.aws\credentials`. | | The path to a file in the AWS shared credential file format | Search only the specified file for a profile with the given name. | ### Save Credentials to a Credentials File To write and save credentials to one of the two credential files, run the `Set-AWSCredential` cmdlet. The following example shows how to do this. The first command uses `Set-AWSCredential` with `-ProfileLocation` to add access and secret keys to a profile specified by the `-ProfileName` parameter. In the second line, run the [Get-Content](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content) cmdlet to display the contents of the credentials file. ``` PS > Set-AWSCredential -ProfileLocation C:\Users\auser\.aws\credentials -ProfileName basic_profile -AccessKey access_key2 -SecretKey secret_key2 PS > Get-Content C:\Users\auser\.aws\credentials aws_access_key_id=access_key2 aws_secret_access_key=secret_key2 ``` ## Displaying Your Credential Profiles Run the [Get-AWSCredential](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-AWSCredential.html) cmdlet and add the `-ListProfileDetail` parameter to return credential file types and locations, and a list of profile names. ``` PS > Get-AWSCredential -ListProfileDetail ProfileName StoreTypeName ProfileLocation ----------- ------------- --------------- source_profile NetSDKCredentialsFile assume_role_profile NetSDKCredentialsFile basic_profile SharedCredentialsFile C:\Users\auser\.aws\credentials ``` ## Removing Credential Profiles To remove credential profiles, run the new [Remove-AWSCredentialProfile](https://docs.aws.amazon.com/powershell/v5/reference/items/Remove-AWSCredentialProfile.html) cmdlet. [Clear-AWSCredential](https://docs.aws.amazon.com/powershell/v5/reference/items/Clear-AWSCredential.html) is deprecated, but still available for backward compatibility. ## Important Notes Only [Initialize-AWSDefaultConfiguration](https://docs.aws.amazon.com/powershell/v5/reference/items/Initialize-AWSDefaultConfiguration.html), [New-AWSCredential](https://docs.aws.amazon.com/powershell/v5/reference/items/New-AWSCredential.html), and [Set-AWSCredential](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-AWSCredential.html) support the parameters for role profiles. You cannot specify the role parameters directly on a command such as `Get-S3Bucket -SourceProfile source_profile_name -RoleArn arn:aws:iam::999999999999:role/role_name`. That does not work because service cmdlets do not directly support the `SourceProfile` or `RoleArn` parameters. Instead, you must store those parameters in a profile, then call the command with the `-ProfileName` parameter.