AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Saves AWS credentials to persistent store (-StoreAs) or temporarily for the shell using shell variable $StoredAWSCredentials.Note that temporary session-based credentials cannot be saved to the persistent store.

Syntax

StoredProfile

Set-AWSCredential
-StoreAs <String>
-Scope <VariableScope>

BasicOrSession

Set-AWSCredential
-StoreAs <String>
-Scope <VariableScope>

AssumeRole

Set-AWSCredential
-StoreAs <String>
-Scope <VariableScope>
-ExternalID <String>
-MfaSerial <String>
-RoleArn <String>
-SourceProfile <String>

AWSCredentialsObject

Set-AWSCredential
-StoreAs <String>
-Scope <VariableScope>

Description

Saves AWS credentials to persistent store (-StoreAs) or temporarily for the shell using shell variable $StoredAWSCredentials. Note: For scripts written against earlier versions of this module this cmdlet can also be invoked with the alias Set-AWSCredentials.

Note: For scripts written against earlier versions of this module this cmdlet can also be invoked with the alias, Set-AWSCredentials.

Parameters

-ExternalID <String>
The user-defined external ID to be used when assuming a role, if required by the role.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-MfaSerial <String>
The MFA serial number to be used when assuming a role, if required by the role.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RoleArn <String>
The ARN of the role to assume for assume role credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Scope <VariableScope>
When saving AWS credentials to the shell variable $StoredAWSCredentials, this parameter allows to specify the scope of the variable. For details about variables scopes see https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scopes. This parameter cannot be used when StoreAs is specified.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-SourceProfile <String>
The name of the source profile to be used by assume role credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-StoreAs <String>
The name to be used to identity the credentials in local storage. Use this with the -ProfileName parameter on cmdlets to load the stored credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAK
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ProfileLocation <String>
Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials.If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.
Required?False
Position?202
Accept pipeline input?True (ByPropertyName)
AliasesAWSProfilesLocation, ProfilesLocation
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required?False
Position?201
Accept pipeline input?True (ByPropertyName)
AliasesStoredCredentials, AWSProfileName
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSK, SecretAccessKey
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesST

Outputs

None
This cmdlet does not generate any output.

Examples

Example 1

Set-AWSCredential -ProfileName myCredentials
Loads the credentials contained in the specified profile and sets them active for all cmdlets in the current shell (the parameter name can be omitted for brevity). The cmdlet first searches the encrypted credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. If this file does not contain a matching profile the cmdlet will attempt to load the profile from the text-format credential file shared with the AWS CLI, looking in its default location (%USERPROFILE%\.aws\credentials). If this file has been renamed, or does not exist in the default location, use the -ProfileLocation parameter to point to the credential file. Note that using -ProfileLocation disables profile lookup in the encrypted .NET store file.

Example 2

Set-AWSCredential -AccessKey AKIAIOSFODNN7EXAMPLE -SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY -StoreAs myCredentials
Saves the specified credentials as a profile named 'myCredentials'. The cmdlet does not affect any credentials currently set as active in the shell. To update the shell run the cmdlet again specifying the name of the profile (Set-AWSCredential -ProfileName myCredentials). On platforms that support the encrypted credential file the profile is written to the encrypted store. If the platform does not support the encrypted store (Linux, MacOS, Windows Nano Server) the profile is written to the plain text ini-format shared credential file at %HOME%\.aws\credentials. To force the profile to be written to the shared credential file on systems that support both stores, specify the path and filename of the credential file using the -ProfileLocation parameter.

Example 3

Set-AWSCredential -AccessKey AKIAIOSFODNN7EXAMPLE -SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY -SessionToken SamPleTokeN.....
Sets the temporary session-based credentials as active in the current shell. Note that temporary credentials cannot be saved as a profile.

Example 4

Set-AWSCredential -ProfileName myCredentials -ProfileLocation C:\myAWSCredentials.ini
Loads the specified credentials from the ini-format credential file (with a non-default name and location) shared with the AWS CLI and sets the credentials in the profile active in the current shell. The -ProfileLocation parameter can be omitted if the credential file is named 'credentials' and is stored in the default location (%USERPROFILE%\.aws).

Example 5

$credential = Get-Credential -Message "Enter your domain credentials for federated identity"
Set-AWSCredential -ProfileName mySamlCredentialProfile -NetworkCredential $credential
Loads the specifed SAML federated credential profile (created with Set-AWSSAMLRoleProfile). The -NetworkCredential parameter is only needed if the logged-in user acount is not joined to the domain used for federation. In this scenario, when temporary credential generated is attempted and the user must be authenticated, caching the identity with the -NetworkCredential parameter value avoids a pop-up credential demand. For systems where the logged-in user account belongs to the domain the logged-in identity is used automatically and no credential demand is made. In this scenario you do not need to supply a credential value.

Example 6

Set-AWSCredential -AccessKey AKIAIOSFODNN7EXAMPLE -SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY -StoreAs sourceAccountProfile
Set-AWSCredential -SourceProfile sourceAccountProfile -RoleArn arn:aws:iam::123456789012:role/my_role -StoreAs myRoleProfile
Creates a cross-account role profile for the specified role. First you create a source profile that can be referenced by multiple role profiles. Then create the role profile for the specified role(s). When the role profile is loaded for use, the role described in the profile will be assumed and temporary credentials for the role set as active in the shell.

Example 7

Set-AWSCredential -SourceProfile sourceAccountProfile -RoleArn arn:aws:iam::123456789012:role/my_role -MfaSerial 124345 -StoreAs myRoleProfile
Creates a cross-account role profile for the specified role that requires use of a two-factor MFA device during credential generation. When credentials for the role are generated the user is prompted to enter the value on the MFA device.

Example 8

Set-AWSCredential -SourceProfile sourceAccountProfile -RoleArn arn:aws:iam::123456789012:role/my_role -ExternalId idValue -StoreAs myRoleProfile
Creates a cross-account role profile for the specified role that requires a unique identifier to be specified. The identifier is used by third parties when assuming roles in their customers' accounts.

Supported Version

AWS Tools for PowerShell: 2.x.y.z