使用 Amazon 凭证 - Amazon Tools for PowerShell
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

使用 Amazon 凭证

每条Amazon Tools for PowerShell命令均必须包含一组 Amazon 凭证,这些凭证用于以加密方式对相应的 Web 服务请求进行签名。您可以为每条命令、每个会话或所有会话指定凭证。

作为最佳实践,为了避免公开您的凭证,请不要在命令中输入凭证文本。相反,为要使用的每组凭证创建一个配置文件,并将该配置文件存储在两个凭证存储中的任一凭证存储中。在命令中按名称指定正确的配置文件,Amazon Tools for PowerShell将检索关联的凭证。有关如何安全地管理Amazon凭证的一般讨论,请参阅亚马逊云科技一般参考中的管理Amazon访问密钥的最佳实践

注意

您需要一个 Amazon 账户来获取凭证并使用Amazon Tools for PowerShell。有关如何注册账户的更多信息,请参阅 Amazon账户与访问密钥

凭证存储位置

Amazon Tools for PowerShell可以使用两个凭证存储中的任意一个:

  • Amazon 开发工具包存储,可加密您的凭证并将其存储在主文件夹中。在 Windows 中,此存储位于:C:\Users\username\AppData\Local\AWSToolkit\RegisteredAccounts.json

    Amazon SDK for .NETToolkit for Visual Studio 也可以使用Amazon开发工具包存储。

  • 共享的凭证文件也位于主文件夹中,但以纯文本形式存储凭证。

    默认情况下,凭证文件存储在以下位置:

    • 在 Windows 上: C:\Users\username\.aws\credentials

    • 在 Mac/Linux 上:~/.aws/credentials

    Amazon 开发工具包和 Amazon Command Line Interface 也可以使用凭证文件。如果您在 Amazon 用户上下文外部运行脚本,请确保将包含凭证的文件复制到可供所有用户账户(本地系统和用户)访问凭证的位置。

管理配置文件

配置文件允许您使用 Amazon Tools for PowerShell 引用不同的凭证集。您可以使用 Amazon Tools for PowerShell cmdlet 管理 Amazon SDK 存储中的配置文件。您也可以使用 Toolkit for Visual Studio 或使用 Amazon SDK for .NET 以编程方式,在Amazon开发工具包存储中管理配置文件。有关如何管理凭证文件中的配置文件的说明,请参阅管理Amazon访问密钥的最佳实践

添加新的配置文件

要将新配置文件添加到Amazon开发工具包存储,请运行 Set-AWSCredential 命令。它将您的访问密钥和秘密密钥存储在您指定的配置文件名称下的默认凭证文件中。

PS > Set-AWSCredential ` -AccessKey AKIA0123456787EXAMPLE ` -SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ` -StoreAs MyNewProfile
  • -AccessKey – 访问密钥 ID。

  • -SecretKey - 私有密钥。

  • -StoreAs - 配置文件名称,该名称必须是唯一的。要指定默认配置文件,请使用名称 default

更新配置文件

必须手动维护Amazon开发工具包存储。如果您稍后更改服务凭证,例如使用 IAM 控制台进行更改 - 使用本地存储凭证运行命令失败,并出现以下错误消息:

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

您可以通过对配置文件重复 Set-AWSCredential 命令并为它传递给新的访问密钥和秘密密钥来更新配置文件。

列出配置文件

您可以使用以下命令检查当前名称列表。在此示例中,名为 Shirley 的用户可以访问三个配置文件,这些配置文件都存储在共享凭证文件 (~/.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

删除配置文件

要删除不再需要的配置文件,请使用以下命令。

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

-ProfileName 参数指定要删除的配置文件。

弃用的命令 Clearar-AWScredential 仍可用于向后兼容,但首选使用 Remove-AWSCredentialProfile

指定凭证

可通过多种方式指定凭证。首选方法是确定配置文件,而不是将文字凭证合并到命令行中。Amazon Tools for PowerShell使用凭证搜索顺序中描述的搜索顺序查找配置文件。

在 Windows 上,存储在Amazon开发工具包存储中的Amazon凭证使用已登录的 Windows 用户身份进行加密。它们不能通过使用另一个账户进行解密,也不能在与最初创建它们的设备不同的设备上使用。要执行需要另一个用户的凭证(例如,将在其下运行计划任务的用户账户)的任务,请设置一个凭证配置文件(如上一部分中所述),您可在以该用户身份登录到计算机时使用该配置文件。以执行任务的用户身份登录以完成凭证设置步骤,并创建适用于该用户的配置文件。然后注销,并使用您自己的凭证重新登录以设置计划的任务。

注意

使用 -ProfileName 通用参数指定配置文件。此参数等同于早期-StoredCredentials版本中的 Amazon Tools for PowerShell 参数。为了实现向后兼容性,仍支持 -StoredCredentials

如果凭证存储在名为 Amazon 的配置文件中,所有 default 开发工具包和管理工具可以自动在您的本地计算机上查找您的凭证。例如,如果您在本地计算机上有一个名为 default 的配置文件,则不必运行 Initialize-AWSDefaultConfiguration cmdlet 或 Set-AWSCredential cmdlet。这些工具会自动使用该配置文件中的访问权限和秘密密钥数据。要使用默认区域之外的 Amazon 区域(Get-DefaultAWSRegion 的结果),您可以运行 Set-DefaultAWSRegion 并指定一个区域。

如果您的配置文件未命名为 default,但您要将其用作当前会话的默认配置文件,请运行 Set-AWSCredential 以将其设置为默认配置文件。

尽管运行 Initialize-AWSDefaultConfiguration 会让您为每个 PowerShell 会话指定默认配置文件,cmdlet 从您自定义命名的配置文件加载凭证,但会使用指定的配置文件覆盖 default 配置文件。

我们建议您不要运行 Initialize-AWSDefaultConfiguration,除非您在未使用实例配置文件启动的 Amazon EC2 实例上运行 PowerShell 会话,并且您希望手动设置凭证配置文件。请注意,在这种情况下凭证配置文件不包含凭证。在 EC2 实例上运行 Initialize-AWSDefaultConfiguration 而产生的凭证配置文件不会直接存储凭证,而是指向实例元数据(提供自动轮换的临时凭证)。但是,它确实存储实例的区域。如果您希望针对实例运行所在区域之外的区域运行调用,则会发生可能需要运行 Initialize-AWSDefaultConfiguration 的另一个场景。运行该命令将永久覆盖存储在实例元数据中的区域。

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

默认凭证包含在 default 配置文件名下的Amazon开发工具包存储中。该命令将覆盖任何具有该名称的现有配置文件。

如果您的 EC2 实例是使用实例配置文件启动的,PowerShell 会从实例配置文件获取 Amazon 凭证和区域信息。您不需要运行 Initialize-AWSDefaultConfiguration。在使用实例配置文件启动的 EC2 实例上运行 Initialize-AWSDefaultConfiguration cmdlet 不是必需的,因为它使用 PowerShell 在默认情况下已经使用的相同实例配置文件数据。

会话配置文件

使用 Set-AWSCredential 指定特定会话的默认配置文件。此配置文件将在会话持续时间内覆盖任何默认配置文件。如果您想要在会话中使用自定义命名的配置文件,而不是当前 default 配置文件,我们建议您使用会话配置文件。

PS > Set-AWSCredential -ProfileName MyProfileName
注意

在 Tools for Windows PowerShell 1.1 之前的版本中,Set-AWSCredential cmdlet 无法正常工作并覆盖“MyProfileName”指定的配置文件。我们建议使用更新版本的 Tools for Windows PowerShell。

命令配置文件

在单个命令上,您可以添加 -ProfileName 参数以指定仅适用于该一个命令的配置文件。此配置文件将覆盖任何默认配置文件或会话配置文件,如以下示例所示。

PS > Get-EC2Instance -ProfileName MyProfileName
注意

当您指定默认配置文件或会话配置文件时,也可以添加 -Region 参数以覆盖默认区域或会话区域。有关更多信息,请参阅指定 Amazon 区域。以下示例指定默认配置文件和区域。

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

默认情况下,假定 Amazon 共享凭证文件位于用户的主文件夹(Windows:C:\Users\username\.aws;或者 Linux:~/.aws)中。要在其他位置指定凭证文件,请包含 -ProfileLocation 参数并指定凭证文件路径。以下示例为特定命令指定非默认凭证文件。

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

如果您在通常不会登录Amazon的时段内运行 PowerShell 脚本(例如,您在非正常工作时间内将 PowerShell 脚本作为计划任务运行),请在您指定要使用的配置文件时添加 -ProfileLocation 参数,并将值设置为用于存储凭证的文件的路径。要确保您的Amazon Tools for PowerShell脚本使用正确的账户凭证运行,那么只要您的脚本在未使用 -ProfileLocation 账户的上下文或过程中运行,您均应添加 Amazon 参数。您也可以将凭证文件复制到供脚本用来执行任务的本地系统或其他账户可访问的位置。

凭证搜索顺序

运行命令时,Amazon Tools for PowerShell 按照以下顺序搜索凭证。它在找到可用凭证时停止。

  1. 作为参数嵌入在命令行中的文字凭证。

    我们强烈建议您使用配置文件,而不是将文字凭证输入到命令行中。

  2. 指定的配置文件名称或配置文件位置。

    • 如果您仅指定配置文件名称,此命令将在Amazon开发工具包存储中查找指定的配置文件;如果该配置文件不存在,则使用默认位置的Amazon共享凭证文件中的指定配置文件。

    • 如果您仅指定配置文件位置,此命令将从该凭证文件中查找 default 配置文件。

    • 如果同时指定名称和位置,则该命令将在该凭证文件中查找指定的配置文件。

    如果未找到指定的配置文件或位置,则命令会引发异常。仅当您尚未指定配置文件或位置时,搜索才会继续执行以下步骤。

  3. -Credential 参数指定的凭证。

  4. 会话配置文件(如果存在)。

  5. 按以下顺序使用默认配置文件:

    1. default 开发工具包存储中的 Amazon 配置文件。

    2. default 共享凭证文件中的 Amazon 配置文件。

    3. AWS PS Default 开发工具包存储中的 Amazon 配置文件。

  6. 如果命令在配置为使用 IAM 角色的 Amazon EC2 实例上运行,那么将从实例配置文件访问 EC2 实例的临时凭证。

    有关针对 Amazon EC2 实例使用 IAM 角色的更多信息,请参阅 Amazon SDK for .NET

如果此搜索未能找到指定的凭证,则该命令会引发异常。

Amazon Tools for PowerShell Core 中的证书处理

Amazon Tools for PowerShell Core 中的 cmdlet 在运行时接受 Amazon 访问密钥和秘密密钥或凭证配置文件的名称,这与 Amazon Tools for Windows PowerShell 类似。当它们在 Windows 上运行时,这两个模块都能够访问 Amazon SDK for .NET 凭证存储文件(存储在每用户 AppData\Local\AWSToolkit\RegisteredAccounts.json 文件中)。

该文件以加密形式存储您的密钥,并且无法在其他计算机上使用。它是Amazon Tools for PowerShell在凭证配置文件中搜索到的第一个文件,并且也是Amazon Tools for PowerShell将凭证配置文件存储到的文件。有关 Amazon SDK for .NET 凭证存储文件的更多信息,请参阅配置Amazon凭证。Tools for Windows PowerShell 模块当前不支持将凭证写入其他文件或位置。

这两个模块都可以从由其他 Amazon 开发工具包和 Amazon 使用的 Amazon CLI 共享凭证文件中读取配置文件。在 Windows 上,此文件的默认位置是 C:\Users\<userid>\.aws\credentials。在非 Windows 平台上,此文件存储在 ~/.aws/credentials-ProfileLocation 参数可用于指向非默认文件名或文件位置。

开发工具包凭证存储使用 Windows 加密 API 来以加密形式保存您的凭证。这些 API 在其他平台上不可用,因此 Amazon Tools for PowerShell Core 模块以独占方式使用 Amazon 共享凭证文件,并支持将新的凭证配置文件写入共享凭证文件中。

以下使用 Set-AWSCredential cmdlet 的示例脚本说明了用于使用 AWSPowerShellAWSPowerShell.NetCore 模块处理 Windows 上的凭证配置文件的选项。

# 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

以下示例说明 AWSPowerShell.NetCore 模块在 Linux 或 Mac OS X 操作系统上的行为。

# 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