AWS Tools for PowerShell V4 已進入維護模式。 我們建議您遷移至 [AWS Tools for PowerShell V5](https://docs.aws.amazon.com/powershell/v5/userguide/)。如需如何遷移的其他詳細資訊和資訊，請參閱我們的[維護模式公告](https://aws.amazon.com/blogs/developer/aws-tools-for-powershell-v4-maintenance-mode-announcement/)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 AWS 登入資料 每個 AWS Tools for PowerShell 命令必須包含一組 AWS 登入資料，用於以密碼編譯方式簽署對應的 Web 服務請求。您可以依命令、工作階段或針對所有工作階段指定憑證。 **警告** 為避免安全風險，在開發專用軟體或使用真實資料時，請勿使用 IAM 使用者進行身分驗證。相反地，搭配使用聯合功能和身分提供者，例如 [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)。 **注意** 本主題中的資訊適用於您需要手動取得及管理短期或長期憑證的情況。有關短期和長期憑證的其他資訊，請參閱 *AWS SDK 和工具參考指南*中的[其他驗證方法](https://docs.aws.amazon.com/sdkref/latest/guide/access-users.html)。 如需最佳實務，請使用 AWS IAM Identity Center，如 中所述[設定工具身分驗證](creds-idc.md)。 做為避免公開憑證的最佳實務，請勿在命令中輸入文字憑證。請為您要使用的每一組憑證建立一個描述檔，然後將描述檔存放在兩個憑證存放區的其中一個。在命令中依名稱指定正確的描述檔， AWS Tools for PowerShell 就會擷取相關聯的憑證。如需如何安全管理 AWS 憑證的一般討論，請參閱《》中的[管理 AWS 存取金鑰的最佳實務](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html)*Amazon Web Services 一般參考*。 **注意** 您需要 AWS 帳戶才能取得登入資料並使用 AWS Tools for PowerShell。若要建立 AWS 帳戶，請參閱 *AWS 帳戶管理 參考指南*中的[入門：您是第一次 AWS 使用嗎？](https://docs.aws.amazon.com/accounts/latest/reference/welcome-first-time-user.html)。 **Topics** + [憑證存放區位置](#specifying-your-aws-credentials-store) + [管理描述檔](#managing-profiles) + [指定憑證](#specifying-your-aws-credentials-use) + [憑證搜尋順序](#pstools-cred-provider-chain-legacy) + [中的登入資料處理 AWS Tools for PowerShell Core](#credential-handling-in-aws-tools-for-powershell-core) ## 憑證存放區位置 AWS Tools for PowerShell 可以使用兩個登入資料存放區中的任一個： + 軟體 AWS 開發套件存放區會加密您的登入資料，並將其存放在您的主資料夾中。在 Windows 中，此存放區位於：`C:\Users\username\AppData\Local\AWSToolkit\RegisteredAccounts.json`。 [適用於 .NET 的 AWS SDK](https://aws.amazon.com/sdk-for-net/) 和 [Toolkit for Visual Studio](https://aws.amazon.com/visualstudio/) 也可以使用 AWS 開發套件存放區。 + 共用憑證檔案也位在您的主資料夾中，但以純文字形式存放憑證。 根據預設，憑證檔案存放在這裡： + 在 Windows 上： `C:\Users\username\.aws\credentials` + 在 Mac/Linux 上：`~/.aws/credentials` AWS SDKs 和 AWS Command Line Interface 也可以使用登入資料檔案。如果您在 AWS 使用者內容之外執行指令碼，請確定包含登入資料的檔案會複製到所有使用者帳戶 （本機系統和使用者） 都可以存取登入資料的位置。 ## 管理描述檔 設定檔可讓您使用 參考不同的登入資料集 AWS Tools for PowerShell。您可以使用 AWS Tools for PowerShell cmdlet 來管理 AWS SDK 存放區中的設定檔。您也可以使用 [Toolkit for Visual Studio](https://docs.aws.amazon.com/AWSToolkitVS/latest/UserGuide/tkv_setup.html)，或以程式設計方式使用 [適用於 .NET 的 AWS SDK](https://aws.amazon.com/sdk-for-net/)，來管理 AWS 開發套件存放區中的描述檔。如需如何管理登入資料檔案中設定檔的指示，請參閱[管理 AWS 存取金鑰的最佳實務](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html)。 ### 新增新的描述檔 若要將新設定檔新增至 AWS SDK 存放區，請執行命令 `Set-AWSCredential`。它會將您的存取金鑰和秘密金鑰存放在您指定之描述檔名稱下的預設憑證檔案中。 ``` PS > Set-AWSCredential ` -AccessKey AKIA0123456787EXAMPLE ` -SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ` -StoreAs MyNewProfile ``` + `-AccessKey`– 存取金鑰 ID。 + `-SecretKey`– 私密金鑰。 + `-StoreAs`– 描述檔名稱，必須是唯一的。若要指定預設描述檔，請使用名稱 `default`。 ### 更新描述檔 AWS SDK 存放區必須手動維護。如果您稍後變更服務上的憑證 (例如使用 [IAM 主控台](https://console.aws.amazon.com/iam/home))，使用本機存放的憑證執行命令會失敗，並出現下列錯誤訊息： ``` 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` 參數會指定您要刪除的描述檔。 已移除的命令 [Clear-AWSCredential](https://docs.aws.amazon.com/powershell/v4/reference/items/Clear-AWSCredential.html) 仍適用於回溯相容性，但最好使用 `Remove-AWSCredentialProfile`。 ## 指定憑證 有幾種方式可以指定憑證。偏好的方法是識別設定檔，而不是將常值登入資料納入命令列。 會使用[登入資料搜尋順序](#pstools-cred-provider-chain-legacy)中所述的搜尋順序來 AWS Tools for PowerShell 尋找設定檔。 在 Windows 上，存放在 AWS SDK 存放區中的 AWS 憑證會使用登入的 Windows 使用者身分加密。它們無法使用其他帳戶解密，也無法在非最初建立帳戶的裝置上使用。若要使用其他使用者的憑證執行任務 (例如，有排程任務要執行的使用者帳戶)，請如上節所述設定憑證描述檔，以便以該使用者身分登入電腦時可以使用其憑證。以任務執行使用者身分登入，完成憑證設定步驟，並建立適用於該使用者的描述檔。登出後，再使用您自己的憑證登入，以設定排程任務。 **注意** 使用 `-ProfileName` 通用參數來指定描述檔。此參數等同於舊版中的 `-StoredCredentials` 參數 AWS Tools for PowerShell 。如需回溯相容性，`-StoredCredentials` 仍然受支援。 ### 預設描述檔 (建議) 如果登入資料存放在名為 的設定檔中， AWS SDKs和管理工具可以自動在本機電腦上找到您的登入資料`default`。例如，如果您在本機電腦上有名為 `default` 的描述檔，就不必執行 `Initialize-AWSDefaultConfiguration` cmdlet 或 `Set-AWSCredential` cmdlet。這些工具會自動使用存放在該描述檔中的存取金鑰和秘密金鑰資料。若要使用您預設區域 (`Get-DefaultAWSRegion` 的結果) 以外的 AWS 區域，您可以執行 `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 ``` **注意** 預設登入 AWS 資料包含在 SDK 存放區中的`default`設定檔名稱下。命令會以該名稱覆寫任何現有的描述檔。 如果您的 EC2 執行個體經執行個體描述檔執行，PowerShell 即會自動從執行個體描述檔取得 AWS 憑證和區域資訊。你不需要執行 `Initialize-AWSDefaultConfiguration`。不需要從經執行個體描述檔啟動的 EC2 執行個體上執行 `Initialize-AWSDefaultConfiguration` cmdlet，因為它預設會使用 PowerShell 已經使用的相同執行個體描述檔資料。 ### 工作階段描述檔 使用 `Set-AWSCredential` 指定特定工作階段的預設描述檔。此描述檔會覆寫工作階段期間內的任何預設描述檔。如果您想要在自己的工作階段中使用自訂名稱的描述檔，而不是目前的 `default` 描述檔，建議您使用此方法。 ``` PS > Set-AWSCredential -ProfileName MyProfileName ``` **注意** 在 1.1 版以前的 Tools for Windows PowerShell 版本中，`Set-AWSCredential` cmdlet 無法正常運作，而且會覆寫 "MyProfileName" 指定的描述檔。建議使用較新版本 Tools for Windows PowerShell。 ### 命令描述檔 在個別的命令中，您可以新增 `-ProfileName` 參數以指定僅適用該一個命令的描述檔。此描述檔會覆寫任何預設或工作階段描述檔，如下列範例所示。 ``` PS > Get-EC2Instance -ProfileName MyProfileName ``` **注意** 當您指定預設或工作階段描述檔時，您也可以新增 `-Region` 參數來覆寫預設或工作階段區域。如需詳細資訊，請參閱[指定 AWS 區域](pstools-installing-specifying-region.md)。以下範例指定預設的描述檔和區域。 ``` PS > Initialize-AWSDefaultConfiguration -ProfileName MyProfileName -Region us-west-2 ``` 根據預設， AWS 共用的登入資料檔案會假設在使用者的主資料夾中 (`C:\Users\username\.aws`Windows 或 Linux `~/.aws` 上）。若要指定不同位置的憑證檔案，請加上 `-ProfileLocation` 參數並指定憑證檔案路徑。以下範例指定特定命令的非預設憑證檔案。 ``` PS > Get-EC2Instance -ProfileName MyProfileName -ProfileLocation C:\aws_service_credentials\credentials ``` **注意** 如果您要在通常不會登入 AWS的時間執行 PowerShell 指令碼，例如，在非正常上班時間以排定的任務來執行 PowerShell 指令碼，當您指定要使用的描述檔時請新增 `-ProfileLocation` 參數，並將值設定為存放您憑證之檔案的路徑。為了確保您的 AWS Tools for PowerShell 指令碼使用正確的帳戶登入資料執行，每當指令碼在不使用 AWS 帳戶的內容或程序中執行時，您應該新增 `-ProfileLocation` 參數。您也可以將您的憑證檔案複製到本機系統或指令碼用於執行任務的其他帳戶可存取的位置。 ## 憑證搜尋順序 當您執行命令時， AWS Tools for PowerShell 會依下列順序搜尋登入資料。當它找到可用的憑證時就會停止。 1. 在命令列中內嵌為參數的文字憑證。 強烈建議您使用描述檔，不要在命令列中放置文字憑證。 1. 指定的描述檔名稱或描述檔位置。 + 如果您只指定設定檔名稱，命令會在 AWS SDK 存放區中尋找指定的設定檔，如果不存在，則會從預設位置的 AWS 共用登入資料檔案中尋找指定的設定檔。 + 如果您只指定描述檔位置，命令會在該憑證檔案中尋找 `default` 描述檔。 + 如果同時指定名稱和位置，命令就會在該憑證檔案中尋找指定的描述檔。 如果找不到指定的描述檔或位置，命令會擲出例外狀況。只有在您未指定描述檔或位置時，搜尋才會繼續執行下列步驟。 1. `-Credential` 參數指定的憑證。 1. 工作階段描述檔 (如果存在)。 1. 依以下順序使用預設描述檔： 1. AWS SDK 存放區中的`default`設定檔。 1. AWS 共用登入資料檔案中的`default`設定檔。 1. AWS SDK 存放區中的`AWS PS Default`設定檔。 1. 如果命令是在設定使用 IAM 角色的 Amazon EC2 執行個體上執行，就會從執行個體描述檔存取 EC2 執行個體的暫時憑證。 如需使用適用於 Amazon EC2 執行個體 的 IAM 角色詳細資訊，請參閱 [適用於 .NET 的 AWS SDK](https://aws.amazon.com/sdk-for-net/)。 如果此搜尋無法找到指定的憑證，命令會擲出例外狀況。 ## 中的登入資料處理 AWS Tools for PowerShell Core 中的 Cmdlet 在執行時 AWS Tools for PowerShell Core 接受 AWS 存取和私密金鑰或登入資料設定檔的名稱，類似於 AWS Tools for Windows PowerShell。在 Windows 上執行時，這兩個模組都能存取 適用於 .NET 的 AWS SDK 憑證存放區檔案 (存放在每個使用者的 `AppData\Local\AWSToolkit\RegisteredAccounts.json` 檔案)。 此檔案以加密格式存放您的金鑰，而且無法用於不同的電腦。這是 AWS Tools for PowerShell 搜尋登入資料設定檔的第一個檔案，也是 AWS Tools for PowerShell 存放登入資料設定檔的檔案。如需 適用於 .NET 的 AWS SDK 登入資料存放區檔案的詳細資訊，請參閱[設定 AWS 登入](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-creds.html)資料。Tools for Windows PowerShell 模組目前不支援將憑證寫入其他檔案或位置。 兩個模組都可以從其他 AWS SDKs 和 所使用的 AWS 共用登入資料檔案讀取設定檔 AWS CLI。在 Windows 上，這個檔案的預設位置是 `C:\Users\\.aws\credentials`。在非 Windows 平台上，這個檔案存放在 `~/.aws/credentials`。`-ProfileLocation` 參數可用於指向非預設檔案名稱或檔案位置。 開發套件憑證存放區使用 Windows 加密 API，以加密形式存放您的憑證。這些 APIs不適用於其他平台，因此 AWS Tools for PowerShell Core 模組只會使用 AWS 共用的登入資料檔案，並支援將新的登入資料設定檔寫入共用的登入資料檔案。 以下使用 `Set-AWSCredential` cmdlet 的範例指令碼，示範在 Windows 上使用 **AWSPowerShell** 或 **AWSPowerShell.NetCore** 模組來處理憑證描述檔的選項。 ``` # 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 ``` 以下範例說明 Linux 或 macOS 作業系統上的 **AWSPowerShell.NetCore** 模組行為。 ``` # 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 ```