本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 第 3 適用於 PHP 的 AWS SDK 版中的內建登入資料提供者
<a name="built-in-providers-in-the-sdk"></a>

開發套件提供數個內建登入資料提供者，您可以個別使用或合併在[自訂登入資料提供者鏈](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 中的 提供者
<a name="login-provider"></a>

`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(<profile_name>, ['region' => <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 中的 提供者
<a name="assumerole-provider"></a>

如果您使用 `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 中的 提供者
<a name="sso-provider"></a>

`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 中的 提供者
<a name="defaultprovider-provider"></a>

 `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 中的 提供者
<a name="ecscredentials-provider"></a>

 `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 中的 提供者
<a name="env-provider"></a>

使用環境變數來包含您的登入資料，可防止您不小心共用 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...<remainder of security token>
   # 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...<remainder of security token>
   # 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 中的 提供者
<a name="assume-role-with-web-identity-provider"></a>

 `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 中的 提供者
<a name="ini-provider"></a>

 `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 中的 提供者
<a name="process-provider"></a>

 `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 中的 提供者
<a name="instanceprofile-provider"></a>

 `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`。