本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用第 3 適用於 PHP 的 AWS SDK 版登入資料提供者
如需 AWS SDKs 可用登入資料機制的參考資訊，請參閱 *AWS SDKs和工具參考指南中的*[登入資料和存取權](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)。
**重要**
為了安全起見，*強烈建議*您**不要**使用根帳戶進行 AWS 存取。如需最新的[安全建議，請務必參閱《IAM 使用者指南》中的 IAM 中的安全最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。 **
第 3 適用於 PHP 的 AWS SDK 版中登入資料提供者的角色是為開發套件的 AWS 服務 用戶端提供登入資料。SDK 會使用其來源的登入資料，透過密碼編譯方式簽署每個請求來驗證服務。登入資料通常包含存取金鑰 - 存取金鑰 ID 和私密存取金鑰。
當您使用臨時登入資料時，例如當您[設定 IAM Identity Center 身分驗證](credentials.md#use-idc-for-auth)或設定執行時間以[擔任 IAM 角色](assumerole-provider.md)時，工作階段字符會新增至存取金鑰，以提供對 AWS 資源的限時存取。
## 第 3 適用於 PHP 的 AWS SDK 版中的登入資料提供者是什麼？
登入資料供應商是一個函數，會傳回一個 `GuzzleHttp\Promise\PromiseInterface`，其中包含 `Aws\Credentials\CredentialsInterface` 執行個體，或被退回並包含 `Aws\Exception\CredentialsException`。[開發套件提供登入資料提供者函數的數個實作](built-in-providers-in-the-sdk.md)，或者您可以[實作自己的](creating-a-custom-provider.md)自訂邏輯來建立登入資料或最佳化登入資料載入。
登入資料供應商會傳送至 `credentials` 用戶端建構函式選項。登入資料供應商為非同步，會在每次叫用 API 操作時，強制其進行延遲評估。因此，將登入資料提供者函數傳遞到軟體開發套件用戶端建構函數，不會立即驗證登入資料。如果登入資料提供者未傳回登入資料物件，API 操作將會遭到拒絕，並且其回應為 `Aws\Exception\CredentialsException`。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
// Use the ECS credential provider.
$provider = CredentialProvider::ecsCredentials();
// Be sure to memoize the credentials.
$memoizedProvider = CredentialProvider::memoize($provider);
// Pass the provider to the client
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $memoizedProvider
]);
```
# 了解第 3 適用於 PHP 的 AWS SDK 版中的預設登入資料提供者鏈結
預設登入資料提供者鏈結是由 SDK 調用的一系列內建登入資料提供者組成。它由 [defaultProvider](defaultprovider-provider.md) 登入資料提供者函數實作，沒有參數。找到有效的憑證後，系統就會停止搜尋。
會依下列順序 適用於 PHP 的 AWS SDK 執行登入資料提供者：
+ [**`env` provider**](env-provider.md) - 開發套件會搜尋[AWS 已設定為環境變數的存取金鑰](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html)。
+ [**`assumeRoleWithWebIdentityCredentialProvider` provider**](assume-role-with-web-identity-provider.md) - SDK 會搜尋 IAM 角色和 Web 身分字符檔案設定。
+ 在鏈結的這個時間點，軟體開發套件會尋找共用 AWS `config` 和 `credentials` 檔案中的組態。軟體開發套件會在「預設」設定檔下尋找組態，但如果已設定`AWS_PROFILE`環境變數，軟體開發套件會使用其具名設定檔值。
+ [**`sso` provider**](sso-provider.md) - SDK 會在共用`config`檔案中尋找 [IAM Identity Center 組態設定](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-token-config)。
+ [**`login provider` **](login-provider.md) - SDK 會在共用`config`檔案中尋找 AWS 主控台登入工作階段組態設定。
+ [**`process` provider **](process-provider.md) - SDK 會在共用`credentials`檔案中尋找 `credential_process`設定。
+ [**`ini` provider**](ini-provider.md) - SDK 會在共用`credentials`檔案中尋找 AWS 登入資料或 IAM 角色資訊。
+ [**`process` provider**](process-provider.md) - SDK 會在共用`config`檔案中尋找 `credential_process`設定。
+ [**`ini` provider**](ini-provider.md) - SDK 會在共用`config`檔案中尋找 AWS 登入資料或 IAM 角色資訊。
+ [**`ecsCredentials` provider**](ecscredentials-provider.md) - SDK 會尋找環境變數`AWS_CONTAINER_CREDENTIALS_FULL_URI`，`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI `或提供取得臨時登入資料的資訊。
+ [**`instanceProfile` provider**](instanceprofile-provider.md) - SDK 使用 EC2 執行個體中繼資料服務來取得執行個體描述檔中指定的 IAM 角色。開發套件會使用角色資訊來取得臨時登入資料。
**注意**
預設供應商的結果會自動記憶。
您可以在 GitHub [原始程式碼中檢閱鏈結的程式碼](https://github.com/aws/aws-sdk-php/blob/0a99dab427f0a1c082775301141aeac3558691ad/src/Credentials/CredentialProvider.php#L77)。
# 第 3 適用於 PHP 的 AWS SDK 版中的內建登入資料提供者
開發套件提供數個內建登入資料提供者，您可以個別使用或合併在[自訂登入資料提供者鏈](chaining-providers.md)中。
當您在服務用戶端建立期間指定登入資料提供者時，開發套件會嘗試僅使用指定的登入資料提供者載入登入資料。它不使用[預設登入資料提供者鏈結](guide_credentials_default_chain.md)。如果您知道希望服務用戶端使用`instanceProfile`提供者，您可以透過在服務用戶端建構函數中指定`instanceProfile`提供者來使預設鏈結發生短路：
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$provider = CredentialProvider::instanceProfile();
// Be sure to memoize the credentials
$memoizedProvider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'credentials' => $memoizedProvider // The default credential provider chain is not used.
]);
```
**重要**
每次執行 API 操作時，都會叫用登入資料供應商。如果載入登入資料是昂貴的任務 (例如，從磁碟或網路資源載入)，或如果登入資料並未由您的供應商快取，請考慮將登入資料供應商封裝在 `Aws\Credentials\CredentialProvider::memoize` 函數中。開發套件使用的預設登入資料供應商會自動記憶。
**Topics**
+ [`login` 適用於 PHP 的 SDK 中的 提供者](login-provider.md)
+ [`assumeRole` 適用於 PHP 的 SDK 中的 提供者](assumerole-provider.md)
+ [`sso` 適用於 PHP 的 SDK 中的 提供者](sso-provider.md)
+ [`defaultProvider` 適用於 PHP 的 SDK 中的 提供者](defaultprovider-provider.md)
+ [`ecsCredentials` 適用於 PHP 的 SDK 中的 提供者](ecscredentials-provider.md)
+ [`env` 適用於 PHP 的 SDK 中的 提供者](env-provider.md)
+ [`assumeRoleWithWebIdentityCredentialProvider` 適用於 PHP 的 SDK 中的 提供者](assume-role-with-web-identity-provider.md)
+ [`ini` 適用於 PHP 的 SDK 中的 提供者](ini-provider.md)
+ [`process` 適用於 PHP 的 SDK 中的 提供者](process-provider.md)
+ [`instanceProfile` 適用於 PHP 的 SDK 中的 提供者](instanceprofile-provider.md)
# `login` 適用於 PHP 的 SDK 中的 提供者
`Aws\Credentials\CredentialProvider::login` 會嘗試載入瀏覽器型登入工作階段所設定的登入資料，這些登入工作階段是由 CLI AWS 等工具所協助。身分驗證後， AWS 會產生跨 AWS SDKs和工具運作的臨時登入資料。
透過此程序，您可以使用在初始帳戶設定期間建立的根登入資料、IAM 使用者或身分提供者的聯合身分進行身分驗證，而適用於 PHP 的 AWS SDK 會自動為您管理臨時登入資料。這種方法消除了在本機存放長期登入資料的需求，進而增強安全性。
當您執行 `aws login`命令時，您可以從作用中主控台工作階段中選取 ，或透過瀏覽器型身分驗證流程登入，這會自動產生臨時登入資料。適用於 PHP 的 AWS SDK 會使用登入服務自動重新整理這些登入資料，最長可達 12 小時。
登入提供者會根據提供的設定檔，嘗試載入先前提及的登入工作階段工作流程所產生的存取權杖。如果呼叫提供者時未提供任何設定檔，它會先檢查`AWS_PROFILE`環境變數來嘗試解析設定檔，然後再返回設定檔 `default`。程式碼內組態可以傳遞給提供者，其中會尋找用於重新整理登入資料之登入服務用戶端`region`的值。如果組態陣列中未提供任何區域，提供者將嘗試透過檢查`AWS_REGION`環境變數來解析區域，然後在解析的設定檔中設定區域值。如果找不到區域，提供者將傳回拒絕承諾，其中包含如何設定區域的指示。
提供者稱為預設鏈結的一部分，可以直接呼叫。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$provider = CredentialProvider::login(, ['region' => ]);
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'credentials' => $provider
]);
```
根據預設，如果您想要使用的服務用戶端上未提供登入資料組態，則會呼叫此提供者做為`defaultProvider()`登入資料鏈結的一部分。在此案例中，服務用戶端的區域會自動傳遞給`login()`供應商。此外，在此案例中，傳遞給登入供應商的設定檔值將先檢查`AWS_PROFILE`環境變數，再返回設定檔 來解析`default`。
# `assumeRole` 適用於 PHP 的 SDK 中的 提供者
如果您使用 `Aws\Credentials\AssumeRoleCredentialProvider` 藉由採用角色來建立登入資料，您必須提供 `'client'` 資訊以及 `StsClient` 物件和 `'assume_role_params'` 詳細資訊，如下所示。
**注意**
為了避免在每個 API 操作上不必要的擷取 AWS STS 登入資料，您可以使用 `memoize`函數來處理過期時自動重新整理登入資料。如需範例，請參閱下列程式碼。
```
use Aws\Credentials\CredentialProvider;
use Aws\Credentials\InstanceProfileProvider;
use Aws\Credentials\AssumeRoleCredentialProvider;
use Aws\S3\S3Client;
use Aws\Sts\StsClient;
// Passing Aws\Credentials\AssumeRoleCredentialProvider options directly
$profile = new InstanceProfileProvider();
$ARN = "arn:aws:iam::123456789012:role/xaccounts3access";
$sessionName = "s3-access-example";
$assumeRoleCredentials = new AssumeRoleCredentialProvider([
'client' => new StsClient([
'region' => 'us-east-2',
'version' => '2011-06-15',
'credentials' => $profile
]),
'assume_role_params' => [
'RoleArn' => $ARN,
'RoleSessionName' => $sessionName,
],
]);
// To avoid unnecessarily fetching STS credentials on every API operation,
// the memoize function handles automatically refreshing the credentials when they expire
$provider = CredentialProvider::memoize($assumeRoleCredentials);
$client = new S3Client([
'region' => 'us-east-2',
'version' => '2006-03-01',
'credentials' => $provider
]);
```
如需 `'assume_role_params'` 的詳細資訊，請參閱 [AssumeRole](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerole)。
# `sso` 適用於 PHP 的 SDK 中的 提供者
`Aws\Credentials\CredentialProvider::sso` 是單一登入憑證提供者。此提供者也稱為 AWS IAM Identity Center 登入資料提供者。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$credentials = CredentialProvider::sso('profile default');
$s3 = new Aws\S3\S3Client([
'version' => 'latest',
'region' => 'us-west-2',
'credentials' => $credentials
]);
```
如果您使用具名設定檔，請在上一個範例中將設定檔的名稱替換為「`default`」。若要進一步了解如何設定具名設定檔，請參閱 SDK [`config`和工具參考指南中的共用和`credentials`檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。 *AWS SDKs * 或者，您可以使用 [https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile)環境變數來指定要使用的設定檔設定。
若要進一步了解 IAM Identity Center 提供者的運作方式，請參閱 *AWS SDKs和工具參考指南*中的[了解 IAM Identity Center 身分驗證](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html)。
# `defaultProvider` 適用於 PHP 的 SDK 中的 提供者
`Aws\Credentials\CredentialProvider::defaultProvider` 是預設登入資料提供者，也稱為[預設登入資料提供者鏈結](guide_credentials_default_chain.md)。如果在建立用戶端時省略 `credentials` 選項，將會使用此供應商。例如，如果您建立 S3Client，如以下程式碼片段所示，開發套件會使用預設提供者：
```
$client = new S3Client([
'region' => 'us-west-2'
]);
```
如果您想要將參數提供給鏈中的特定登入資料提供者，也可以在程式碼中使用 defaultProvider。例如，如果使用`ecsCredentials`提供者函數，以下範例會提供自訂連線逾時和重試設定。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$provider = CredentialProvider::defaultProvider([
'timeout' => '1.5',
'retries' => 5
]);
$client = new S3Client([
'region' => 'us-west-2',
'credentials' => $provider
]);
```
# `ecsCredentials` 適用於 PHP 的 SDK 中的 提供者
`Aws\Credentials\CredentialProvider::ecsCredentials` 嘗試以 `GET` 請求載入登入資料，其 URI 由容器中的環境變數 `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` 指定。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$provider = CredentialProvider::ecsCredentials();
// Be sure to memoize the credentials
$memoizedProvider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $memoizedProvider
]);
```
# `env` 適用於 PHP 的 SDK 中的 提供者
使用環境變數來包含您的登入資料，可防止您不小心共用 AWS 私密存取金鑰。建議您絕對不要在任何生產檔案中將 AWS 存取金鑰直接新增至用戶端。
若要向 Amazon Web Services 進行身分驗證，軟體開發套件會先檢查您環境變數中的登入資料。開發套件使用 `getenv()` 函數來尋找 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 環境變數。這類登入資料稱為環境登入資料。如需如何取得這些值的說明，請參閱 *AWS SDKs和工具參考指南*中的[使用短期憑證進行身分驗證](https://docs.aws.amazon.com/sdkref/latest/guide/access-temp-idc.html)。
如果您在 上託管應用程式[AWS Elastic Beanstalk](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_PHP_eb.html)，您可以透過 [AWS Elastic Beanstalk 主控台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-cfg-softwaresettings.html#environments-cfg-softwaresettings-console)設定 `AWS_SECRET_KEY`、 `AWS_ACCESS_KEY_ID`和 `AWS_SESSION_TOKEN`環境變數，讓 SDK 可以自動使用這些登入資料。
如需如何設定環境變數的詳細資訊，請參閱 *AWS SDKs和工具參考指南*中的[環境變數支援](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html)。此外，如需 AWS SDKs支援的所有環境變數清單，請參閱[環境變數清單](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#EVarSettings)。
您也可以在命令列中設定環境變數，如下所示。
**Linux**
```
$ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
# The access key for your AWS 帳戶.
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# The secret access key for your AWS 帳戶.
$ export AWS_SESSION_TOKEN=AQoDYXdzEJr...
# The temporary session key for your AWS 帳戶.
# The AWS_SECURITY_TOKEN environment variable can also be used, but is only supported for backward compatibility purposes.
# AWS_SESSION_TOKEN is supported by multiple AWS SDKs other than PHP.
```
**Windows**
```
C:\> SET AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
# The access key for your AWS 帳戶.
C:\> SET AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# The secret access key for your AWS 帳戶.
C:\> SET AWS_SESSION_TOKEN=AQoDYXdzEJr...
# The temporary session key for your AWS 帳戶.
# The AWS_SECURITY_TOKEN environment variable can also be used, but is only supported for backward compatibility purposes.
# AWS_SESSION_TOKEN is supported by multiple AWS SDKs besides PHP.
```
`Aws\Credentials\CredentialProvider::env` 嘗試從環境變數載入登入資料。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => CredentialProvider::env()
]);
```
# `assumeRoleWithWebIdentityCredentialProvider` 適用於 PHP 的 SDK 中的 提供者
`Aws\Credentials\CredentialProvider::assumeRoleWithWebIdentityCredentialProvider` 嘗試透過擔任角色載入登入資料。如果環境變數 `AWS_ROLE_ARN` 和 `AWS_WEB_IDENTITY_TOKEN_FILE` 存在，供應商將嘗試使用磁碟上的字符擔任 `AWS_ROLE_ARN` 中指定的角色，而此字符位於 `AWS_WEB_IDENTITY_TOKEN_FILE` 中指定的完整路徑。如果使用環境變數，供應商將嘗試從 `AWS_ROLE_SESSION_NAME` 環境變數設定工作階段。
如果未設定環境變數，提供者將使用預設設定檔，或設定為 `AWS_PROFILE` 的設定檔。根據預設，供應商會從 `~/.aws/config` 和 `~/.aws/credentials` 讀取設定檔，而且可從 `filename` 組態選項中指定的設定檔讀取。供應商將擔任設定檔的 `role_arn` 中的角色，從 `web_identity_token_file` 中設定的完整路徑讀取字符。如果設定在設定檔上，將使用 `role_session_name`。
供應商會做為預設鏈的一部分進行呼叫，也可以直接呼叫。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$provider = CredentialProvider::assumeRoleWithWebIdentityCredentialProvider();
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $provider
]);
```
在預設情況下，這位登入資料供應商會繼承將由 StsClient 用來擔任該角色的已設定區域。您可以選擇提供完整的 StsClient。在任何提供的 StsClient 上，登入資料應設定為 `false`。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
use Aws\Sts\StsClient;
$stsClient = new StsClient([
'region' => 'us-west-2',
'version' => 'latest',
'credentials' => false
])
$provider = CredentialProvider::assumeRoleWithWebIdentityCredentialProvider([
'stsClient' => $stsClient
]);
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $provider
]);
```
# `ini` 適用於 PHP 的 SDK 中的 提供者
`Aws\Credentials\CredentialProvider::ini` 會嘗試從共用 `config`和 `credentials` 檔案載入登入資料。根據預設，軟體開發套件會嘗試從位於 的共用 AWS `credentials`檔案載入「預設」設定檔`~/.aws/credentials`。如果 SDK 找到`AWS_SDK_LOAD_NONDEFAULT_CONFIG`環境變數，也會在位於 的共用 AWS `config`檔案中檢查「預設」設定檔`~/.aws/config`。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$provider = CredentialProvider::ini();
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $provider
]);
```
您可以將引數提供給建立供應商的函數，以使用自訂描述檔或 .ini 檔案位置。
```
$profile = 'production';
$path = '/full/path/to/credentials.ini';
$provider = CredentialProvider::ini($profile, $path);
$provider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $provider
]);
```
# `process` 適用於 PHP 的 SDK 中的 提供者
`Aws\Credentials\CredentialProvider::process` 會嘗試透過執行[共用 AWS 組態檔案中](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)設定檔中指定的`credential_process`值來載入登入資料。
根據預設，軟體開發套件會先嘗試從位於 的共用 AWS `credentials`檔案載入「預設」描述檔`~/.aws/credentials`。如果在共用`credentials`檔案中找不到「預設」設定檔，軟體開發套件會在共用`config`檔案中尋找預設設定檔。以下是共用`credentials`檔案的組態範例。
```
[default]
credential_process = /path/to/file/credential_returning_executable.sh --custom-command custom_parameter
```
SDK 會使用 PHP 的 `shell_exec`函數完全呼叫 `credential_process`命令，然後從 stdout 讀取 JSON 資料。`credential_process` 必須以下列格式將登入資料寫入 stdout：
```
{
"Version": 1,
"AccessKeyId": "",
"SecretAccessKey": "",
"SessionToken": "",
"Expiration": ""
}
```
`SessionToken` 和 `Expiration` 為選用。如果存在，則該登入資料會被視為臨時。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$provider = CredentialProvider::process();
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $provider
]);
```
您可以將引數提供給建立供應商的函數，以使用自訂描述檔或 .ini 檔案位置。
```
$profile = 'production';
$path = '/full/path/to/credentials.ini';
$provider = CredentialProvider::process($profile, $path);
$provider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $provider
]);
```
# `instanceProfile` 適用於 PHP 的 SDK 中的 提供者
`Aws\Credentials\CredentialProvider::instanceProfile` 會嘗試載入 Amazon EC2 執行個體設定檔中指定之 IAM 角色的登入資料。
```
use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
$provider = CredentialProvider::instanceProfile();
// Be sure to memoize the credentials
$memoizedProvider = CredentialProvider::memoize($provider);
$client = new S3Client([
'region' => 'us-west-2',
'version' => '2006-03-01',
'credentials' => $memoizedProvider
]);
```
根據預設，供應商會重試擷取登入資料，最多三次。您可以使用 `retries`選項設定重試次數，並將 選項設定為 以完全停用`0`，如下列程式碼所示。
```
use Aws\Credentials\CredentialProvider;
$provider = CredentialProvider::instanceProfile([
'retries' => 0
]);
$memoizedProvider = CredentialProvider::memoize($provider);
```
如果環境變數`AWS_METADATA_SERVICE_NUM_ATTEMPTS`可用，其值會優先於先前顯示的「重試」選項。
**注意**
您可以將`AWS_EC2_METADATA_DISABLED`環境變數設定為 ，以停用從 Amazon EC2 執行個體設定檔載入的嘗試`true`。
# 鏈結適用於 PHP 的 SDK 中的登入資料提供者
您可使用 `Aws\Credentials\CredentialProvider::chain()` 函數來鏈結登入資料供應商。此函數接受 variadic 數量的引數，每個引數皆為登入資料供應商函數。此函數會傳回一個新的函數，這個新函數由提供的函數組成，並且會逐一呼叫，直到其中一個提供者傳回已成功履行的 promise。
`defaultProvider` 使用此結構在失敗之前檢查多個供應商。`defaultProvider` 的來源示範如何使用 `chain` 函數。
```
// This function returns a provider
public static function defaultProvider(array $config = [])
{
// This function is the provider, which is actually the composition
// of multiple providers. Notice that we are also memoizing the result by
// default.
return self::memoize(
self::chain(
self::env(),
self::ini(),
self::instanceProfile($config)
)
);
}
```
# 建立自訂登入資料提供者以搭配適用於 PHP 的 SDK 使用
登入資料供應商是簡單的函數，被叫用時會傳回承諾 (`GuzzleHttp\Promise\PromiseInterface`)，其中包含 `Aws\Credentials\CredentialsInterface` 物件，或被退回並包含 `Aws\Exception\CredentialsException`。
建立供應商的最佳實務是建立函數，此函數被叫用時間和建立實際的登入資料供應商。例如，以下是 `env` 提供者的來源 (為了示範用途而有稍做修改)。請注意，這是一個函數，會傳回實際的供應商函數。這可讓您輕鬆地撰寫登入資料供應商，並傳遞它們做為值。
```
use GuzzleHttp\Promise;
use GuzzleHttp\Promise\RejectedPromise;
// This function CREATES a credential provider
public static function env()
{
// This function IS the credential provider
return function () {
// Use credentials from environment variables, if available
$key = getenv(self::ENV_KEY);
$secret = getenv(self::ENV_SECRET);
if ($key && $secret) {
return Create::promise_for(
new Credentials($key, $secret, getenv(self::ENV_SESSION))
);
}
$msg = 'Could not find environment variable '
. 'credentials in ' . self::ENV_KEY . '/' . self::ENV_SECRET;
return new RejectedPromise(new CredentialsException($msg));
};
}
```
# 在適用於 PHP 的 SDK 中記住登入資料
有時您可能需要建立能記憶先前傳回值的登入資料供應商。如果載入登入資料是昂貴的操作，或使用 `Aws\Sdk` 類別跨多個用戶端共用登入資料供應商時，這將會很有用。您可以藉由將登入資料供應商函數包裝在 `memoize` 函數中，將記憶功能新增至登入資料供應商。
```
use Aws\Credentials\CredentialProvider;
$provider = CredentialProvider::instanceProfile();
// Wrap the actual provider in a memoize function
$provider = CredentialProvider::memoize($provider);
// Pass the provider into the Sdk class and share the provider
// across multiple clients. Each time a new client is constructed,
// it will use the previously returned credentials as long as
// they haven't yet expired.
$sdk = new Aws\Sdk(['credentials' => $provider]);
$s3 = $sdk->getS3(['region' => 'us-west-2', 'version' => 'latest']);
$ec2 = $sdk->getEc2(['region' => 'us-west-2', 'version' => 'latest']);
assert($s3->getCredentials() === $ec2->getCredentials());
```
當記憶的登入資料過期時，記憶包裝函式會叫用包裝的供應商，以嘗試重新整理登入資料。
# 使用第 3 適用於 PHP 的 AWS SDK 版擔任 IAM 角色
## 針對 Amazon EC2 執行個體變數登入資料使用 IAM 角色
如果您在 Amazon EC2 執行個體上執行應用程式，提供憑證以呼叫 的偏好方法是 AWS 使用 [IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)來取得臨時安全憑證。
使用 IAM 角色時，您不需要擔心應用程式的登入資料管理。它們允許執行個體從 Amazon EC2 執行個體的中繼資料伺服器擷取臨時憑證，以「擔任」角色。
暫時登入資料通常稱為**執行個體設定檔登入**資料，允許存取角色政策允許的動作和資源。Amazon EC2 會處理安全向 IAM 服務驗證執行個體以擔任角色的所有工作，並定期重新整理擷取的角色登入資料。這讓您幾乎無需執行任何工作，即可確保應用程式安全。如需可接受臨時安全憑證的服務清單，請參閱《IAM 使用者指南》中的[可搭配 IAM 運作的AWS 服務](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)。**
**注意**
為避免每次都必須連接中繼資料服務，您可將 `Aws\CacheInterface` 執行個體做為 `'credentials'` 選項傳遞至用戶端建構函式。如此可讓開發套件改為使用快取的執行個體描述檔登入資料。如需詳細資訊，請參閱第 [3 版的 適用於 PHP 的 AWS SDK 組態](guide_configuration.md)。
如需使用 SDKs 開發 Amazon EC2 應用程式的詳細資訊，請參閱 *AWS SDKs和工具參考指南*中的[為 Amazon EC2 執行個體使用 IAM 角色](https://docs.aws.amazon.com/sdkref/latest/guide/access-iam-roles-for-ec2.html)。
### 建立 IAM 角色並將其指派給 Amazon EC2 執行個體
1. 建立 IAM 用戶端。
**匯入**
```
require 'vendor/autoload.php';
use Aws\Iam\IamClient;
```
**範例程式碼**
```
$client = new IamClient([
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
```
1. 建立具有您將使用之動作和資源許可的 IAM 角色。
**範例程式碼**
```
$result = $client->createRole([
'AssumeRolePolicyDocument' => 'IAM JSON Policy', // REQUIRED
'Description' => 'Description of Role',
'RoleName' => 'RoleName', // REQUIRED
]);
```
1. 建立 IAM 執行個體描述檔，並從結果中存放 Amazon Resource Name (ARN)。
**注意**
如果您使用 IAM 主控台而非 適用於 PHP 的 AWS SDK，主控台會自動建立執行個體描述檔，並為其提供與其對應之角色相同的名稱。
**範例程式碼**
```
$IPN = 'InstanceProfileName';
$result = $client->createInstanceProfile([
'InstanceProfileName' => $IPN ,
]);
$ARN = $result['Arn'];
$InstanceID = $result['InstanceProfileId'];
```
1. 建立 Amazon EC2 用戶端。
**匯入**
```
require 'vendor/autoload.php';
use Aws\Ec2\Ec2Client;
```
**範例程式碼**
```
$ec2Client = new Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
]);
```
1. 將執行個體描述檔新增至執行中或已停止的 Amazon EC2 執行個體。使用 IAM 角色的執行個體描述檔名稱。
**範例程式碼**
```
$result = $ec2Client->associateIamInstanceProfile([
'IamInstanceProfile' => [
'Arn' => $ARN,
'Name' => $IPN,
],
'InstanceId' => $InstanceID
]);
```
如需更多詳細資訊，請參閱 *Amazon EC2 使用者指南*中的 [Amazon EC2 的 IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)。
## 針對 Amazon ECS 任務使用 IAM 角色
Amazon Elastic Container Service (Amazon ECS) 中的任務可以擔任 IAM 角色來進行 AWS API 呼叫。這是管理應用程式要使用之登入資料的策略，類似於 Amazon EC2 執行個體描述檔如何提供登入資料給 Amazon EC2 執行個體。
您可以將使用臨時 AWS 憑證的 IAM 角色與 ECS 任務定義或 `RunTask` [API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ecs-2014-11-13.html#runtask) 操作建立關聯，而不是建立和分發長期憑證至容器或使用 Amazon EC2 執行個體的 角色。
如需使用容器任務可擔任之 IAM 角色的詳細資訊，請參閱《*Amazon ECS 開發人員指南*》中的[任務 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)主題。如需在任務定義`taskRoleArn`中以 形式使用任務 IAM 角色的範例，請參閱《*Amazon ECS 開發人員指南*》中的[任務定義範例](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/firelens-example-taskdefs.html)。
## 在另一個 中擔任 IAM 角色 AWS 帳戶
當您使用 AWS 帳戶 （帳戶 A) 並想要在另一個帳戶 （帳戶 B) 中擔任角色時，您必須先在帳戶 B 中建立 IAM 角色。此角色允許帳戶 （帳戶 A) 中的實體在帳戶 B 中執行特定動作。如需跨帳戶存取的詳細資訊，請參閱[教學課程：使用 IAM 角色跨 AWS 帳戶委派存取權](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)。
在帳戶 B 中建立角色後，請記下角色 ARN。當您從帳戶 A 擔任角色時，您將使用此 ARN。您使用帳戶 A 中與您的實體相關聯的 AWS 登入資料來擔任角色。
使用 的登入資料建立 AWS STS 用戶端 AWS 帳戶。在下文中我們使用登入資料設定檔，但您可以使用任何方法。對於新建立的 AWS STS 用戶端，呼叫 assume-role 並提供自訂 sessionName。擷取結果中的新臨時登入資料。根據預設，登入資料會持續一小時。
**範例程式碼**
```
$stsClient = new Aws\Sts\StsClient([
'profile' => 'default',
'region' => 'us-east-2',
'version' => '2011-06-15'
]);
$ARN = "arn:aws:iam::123456789012:role/xaccounts3access";
$sessionName = "s3-access-example";
$result = $stsClient->AssumeRole([
'RoleArn' => $ARN,
'RoleSessionName' => $sessionName,
]);
$s3Client = new S3Client([
'version' => '2006-03-01',
'region' => 'us-west-2',
'credentials' => [
'key' => $result['Credentials']['AccessKeyId'],
'secret' => $result['Credentials']['SecretAccessKey'],
'token' => $result['Credentials']['SessionToken']
]
]);
```
如需詳細資訊，請參閱 適用於 PHP 的 AWS SDK API [參考中的使用 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)或 [AssumeRole](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerole)。
## 使用具有 Web 身分的 IAM 角色
Web Identity Federation 可讓客戶在存取 AWS 資源時使用第三方身分提供者進行身分驗證。您必須先建立 IAM 角色並設定 Web 身分提供者 (IdP)，然後才能擔任具有 Web 身分的角色。如需詳細資訊，請參閱[建立 Web 身分的角色或 OpenID Connect 聯合身分 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)。
[建立身分提供者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)並[為您的 Web 身分建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)之後，請使用 AWS STS 用戶端來驗證使用者。為您的身分提供 webIdentityToken 和 ProviderId，以及為使用者提供具有許可之 IAM 角色的角色 ARN。
**範例程式碼**
```
$stsClient = new Aws\Sts\StsClient([
'profile' => 'default',
'region' => 'us-east-2',
'version' => '2011-06-15'
]);
$ARN = "arn:aws:iam::123456789012:role/xaccounts3access";
$sessionName = "s3-access-example";
$duration = 3600;
$result = $stsClient->AssumeRoleWithWebIdentity([
'WebIdentityToken' => "FACEBOOK_ACCESS_TOKEN",
'ProviderId' => "graph.facebook.com",
'RoleArn' => $ARN,
'RoleSessionName' => $sessionName,
]);
$s3Client = new S3Client([
'version' => '2006-03-01',
'region' => 'us-west-2',
'credentials' => [
'key' => $result['Credentials']['AccessKeyId'],
'secret' => $result['Credentials']['SecretAccessKey'],
'token' => $result['Credentials']['SessionToken']
]
]);
```
如需詳細資訊，請參閱 適用於 PHP 的 AWS SDK API 參考中的 [AssumeRoleWithWebIdentity—透過 Web 型身分提供者的聯合](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_assumerolewithwebidentity.html)或 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerolewithwebidentity)。
## 使用設定檔擔任角色
### 在 中定義設定檔 `~/.aws/credentials`
您可以透過在 中定義設定檔， 適用於 PHP 的 AWS SDK 將 設定為使用 IAM 角色`~/.aws/credentials`。
使用您要擔任之角色`role_arn`的設定建立新的設定檔。也包含另一個設定檔`source_profile`的設定，其登入資料具有擔任 IAM 角色的許可。如需這些組態設定的詳細資訊，請參閱 *AWS SDKs和工具參考指南*中的[擔任角色登入](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html)資料。
例如，在下列 中`~/.aws/credentials`，`project1`設定檔會設定 `role_arn`，並將`default`設定檔指定為登入資料的來源，以確認與其相關聯的實體可以擔任該角色。
```
[project1]
role_arn = arn:aws:iam::123456789012:role/testing
source_profile = default
role_session_name = OPTIONAL_SESSION_NAME
[default]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY
aws_session_token= YOUR_AWS_SESSION_TOKEN
```
如果您設定`AWS_PROFILE`環境變數，或在執行個體化服務用戶端時使用 `profile` 參數，`project1`則會使用`default`設定檔做為來源登入資料，擔任 中指定的角色。
下列程式碼片段顯示 `S3Client`建構函數中使用 `profile` 參數。`S3Client` 將具有與`project1`設定檔相關聯之角色相關聯的許可。
```
$s3 = new Aws\S3\S3Client([
'region' => 'us-east-1',
'version' => '2006-03-01',
'profile' => 'project1'
]);
```
### 在 中定義設定檔 `~/.aws/config`
`~/.aws/config` 檔案也可以包含您要擔任的設定檔。如果您設定環境變數 `AWS_SDK_LOAD_NONDEFAULT_CONFIG`，適用於 PHP 的 SDK 會從 `config` 檔案載入設定檔。設定 `AWS_SDK_LOAD_NONDEFAULT_CONFIG` 時，軟體開發套件會從 `~/.aws/config`和 載入設定檔`~/.aws/credentials`。來自 的設定檔`~/.aws/credentials`最後載入，優先於`~/.aws/config`具有相同名稱的 設定檔。來自任一位置的設定檔都能做為 `source_profile` 或要擔任的設定檔。
下列範例使用 `config` 檔案中定義的 `project1` 設定檔和 `credentials` 檔案中的 `default`設定檔。`AWS_SDK_LOAD_NONDEFAULT_CONFIG` 也會設定 。
```
# Profile in ~/.aws/config.
[profile project1]
role_arn = arn:aws:iam::123456789012:role/testing
source_profile = default
role_session_name = OPTIONAL_SESSION_NAME
```
```
# Profile in ~/.aws/credentials.
[default]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY
aws_session_token= YOUR_AWS_SESSION_TOKEN
```
當`S3Client`建構函數執行並顯示下列程式碼片段時，將使用與`project1`設定檔相關聯的登入資料來擔任`default`設定檔中定義的 角色。
```
$s3 = new Aws\S3\S3Client([
'region' => 'us-east-1',
'version' => '2006-03-01',
'profile' => 'project1'
]);
```
# 在適用於 PHP 的 SDK AWS STS 中使用 的臨時登入資料
AWS Security Token Service (AWS STS) 可讓您為 IAM 使用者或您透過聯合身分驗證的使用者請求有限權限、**臨時憑證**。如需進一步了解，請參閱《*IAM 使用者指南*》中的[暫時安全登入](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)資料。您可以使用臨時安全登入資料來存取大多數 AWS 服務。如需可接受臨時安全憑證的服務清單，請參閱《IAM 使用者指南》中的[可搭配 IAM 運作的AWS 服務](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)。**
臨時憑證的一個常見使用案例是透過第三方身分提供者驗證使用者，授予行動或用戶端應用程式存取 AWS 資源的權限 （請參閱 [Web Identity Federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html))。
## 取得臨時登入資料
AWS STS 有數個 操作會傳回暫時登入資料，但`GetSessionToken`操作是最簡單的示範。下列程式碼片段會透過呼叫 PHP 開發套件 STS 用戶端的 `getSessionToken`方法來擷取臨時憑證。
```
$sdk = new Aws\Sdk([
'region' => 'us-east-1',
]);
$stsClient = $sdk->createSts();
$result = $stsClient->getSessionToken();
```
`GetSessionToken` 和其他 AWS STS 操作的結果一律包含 `'Credentials'`值。如果您列印 `$result`（例如使用 `print_r($result)`)，它看起來如下所示。
```
Array
(
...
[Credentials] => Array
(
[SessionToken] => ''
[SecretAccessKey] => ''
[Expiration] => 2013-11-01T01:57:52Z
[AccessKeyId] => ''
)
...
)
```
## 提供臨時登入資料給 適用於 PHP 的 AWS SDK
您可以透過執行個體化 AWS 用戶端並 AWS STS 直接傳入從 接收的值，將暫時登入資料與其他用戶端搭配使用。
```
use Aws\S3\S3Client;
$result = $stsClient->getSessionToken();
$s3Client = new S3Client([
'version' => '2006-03-01',
'region' => 'us-west-2',
'credentials' => [
'key' => $result['Credentials']['AccessKeyId'],
'secret' => $result['Credentials']['SecretAccessKey'],
'token' => $result['Credentials']['SessionToken']
]
]);
```
您也可以建構 `Aws\Credentials\Credentials` 物件，並在個體化用戶端時使用它。
```
use Aws\Credentials\Credentials;
use Aws\S3\S3Client;
$result = $stsClient->getSessionToken();
$credentials = new Credentials(
$result['Credentials']['AccessKeyId'],
$result['Credentials']['SecretAccessKey'],
$result['Credentials']['SessionToken']
);
$s3Client = new S3Client([
'version' => '2006-03-01',
'region' => 'us-west-2',
'credentials' => $credentials
]);
```
不過，提供臨時登入資料的*最佳*方式是使用隨附於 `StsClient` 的 `createCredentials()` helper 方法。此方法會從 AWS STS 結果中擷取資料，並為您建立 `Credentials` 物件。
```
$result = $stsClient->getSessionToken();
$credentials = $stsClient->createCredentials($result);
$s3Client = new S3Client([
'version' => '2006-03-01',
'region' => 'us-west-2',
'credentials' => $credentials
]);
```
如需有關為什麼您可能需要在應用程式或專案中使用暫時登入資料的詳細資訊，請參閱 AWS STS 文件中的[授予暫時存取權的案例](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。
# 在適用於 PHP 的 SDK 中建立匿名用戶端
在某些情況下，您可能會希望建立未與任何登入資料關聯的用戶端。如此可讓您對服務進行匿名請求。
例如，您可以同時設定 Amazon S3 物件和 Amazon CloudSearch 網域，以允許匿名存取。
若要建立匿名用戶端，請將 `'credentials'` 選項設定為 `false`。
```
$s3Client = new S3Client([
'version' => 'latest',
'region' => 'us-west-2',
'credentials' => false
]);
// Makes an anonymous request. The object would need to be publicly
// readable for this to succeed.
$result = $s3Client->getObject([
'Bucket' => 'amzn-s3-demo-bucket',
'Key' => 'my-key',
]);
```