本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 适用于 PHP 的 AWS SDK 版本 3 凭证提供商
<a name="guide_credentials"></a>

有关可用凭证机制的参考信息 AWS SDKs，请参阅[和*工具参考指南中的凭证AWS SDKs 和*访问权限](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)。

**重要**  
出于安全考虑，我们*强烈建议*您**不要**使用 root 账户进行 AWS 访问。请务必参阅 *IAM 用户指南*中的 [IAM 中的安全最佳实践](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)，了解最新安全建议。

在 适用于 PHP 的 AWS SDK 版本 3 中，凭证提供者的角色是为 SDK 的 AWS 服务 客户端获取和提供凭证。SDK 使用其获取的凭证对每个请求进行加密签名，从而向服务进行身份验证。凭证通常包含访问密钥（一个访问密钥 ID 和一个秘密访问密钥）。

当您使用临时证书时，例如[设置 IAM Identity Center 身份验证](credentials.md#use-idc-for-auth)或将运行时配置为[担任 IAM 角色](assumerole-provider.md)时，会话令牌会添加到访问密钥中，从而提供对 AWS 资源的限时访问权限。

## 适用于 PHP 的 AWS SDK 版本 3 中的凭证提供者是什么？
<a name="cred-provider-defn-php"></a>

凭证提供程序是一个函数，该函数返回一个用 `GuzzleHttp\Promise\PromiseInterface` 实例执行或因 `Aws\Credentials\CredentialsInterface` 而被拒绝的 `Aws\Exception\CredentialsException`。[SDK 提供多种凭证提供程序函数的实现方式](built-in-providers-in-the-sdk.md)，或者您可以[实现自己的](creating-a-custom-provider.md)自定义逻辑来创建凭证或优化凭证加载过程。

凭证提供程序将被传入 `credentials` 客户端构造函数选项。凭证提供程序是异步的，因此每次调用 API 操作时都会强制对其进行延迟评估。因此，将凭证提供程序函数传递给开发工具包客户端构造函数不会立即验证凭证。如果凭证提供程序未返回凭证对象，将因 `Aws\Exception\CredentialsException` 拒绝 API 操作。

```
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
]);
```

# 了解 适用于 PHP 的 AWS SDK 版本 3 中的默认凭证提供者链
<a name="guide_credentials_default_chain"></a>

默认凭证提供程序链由 SDK 调用的一系列内置凭证提供程序组成。它由 [defaultProvider](defaultprovider-provider.md) 凭证提供程序函数实现，不带任何参数。找到有效凭证后，搜索即告停止。

按以下 适用于 PHP 的 AWS SDK 顺序执行凭证提供程序：
+ [**`env` 提供程序**](env-provider.md) - SDK 搜索[已设置为环境变量的AWS 访问密钥](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html)。
+ [**`assumeRoleWithWebIdentityCredentialProvider` 提供程序**](assume-role-with-web-identity-provider.md) - SDK 搜索 IAM 角色和 Web 身份令牌文件设置。
+ 在链的此时刻，SDK 在共享 AWS `config`和`credentials`文件中查找配置。SDK 在“默认”配置文件下查找配置，但如果设置了 `AWS_PROFILE` 环境变量，SDK 将使用其命名配置文件值。
  +  [**`sso` 提供程序**](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` 提供程序**](process-provider.md) - SDK 在共享 `credentials` 文件中查找 `credential_process` 设置。
  + [**`ini`提供商**](ini-provider.md)-软件开发工具包在共享`credentials`文件中查找 AWS 证书或 IAM 角色信息。
  + [**`process` 提供程序**](process-provider.md) - SDK 在共享 `config` 文件中查找 `credential_process` 设置。
  + [**`ini`提供商**](ini-provider.md)-软件开发工具包在共享`config`文件中查找 AWS 证书或 IAM 角色信息。
+ [**`ecsCredentials` 提供程序**](ecscredentials-provider.md) - SDK 查找环境变量 `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI `或 `AWS_CONTAINER_CREDENTIALS_FULL_URI`，这些变量会提供获取临时凭证所需的信息。
+ [**`instanceProfile` 提供程序**](instanceprofile-provider.md) - SDK 使用 EC2 实例元数据服务来获取实例配置文件中指定的 IAM 角色。SDK 根据角色信息获取临时凭证。

**注意**  
系统会自动记住默认提供程序的结果。

你可以在 GitHub [源代码中查看链的代码](https://github.com/aws/aws-sdk-php/blob/0a99dab427f0a1c082775301141aeac3558691ad/src/Credentials/CredentialProvider.php#L77)。

# 适用于 PHP 的 AWS SDK 版本 3 中的内置凭证提供商
<a name="built-in-providers-in-the-sdk"></a>

SDK 提供了多个内置凭证提供程序，您可以单独使用这些提供程序，也可以在[自定义凭证提供程序链](chaining-providers.md)中结合使用。

当您在创建服务客户端期间指定凭证提供程序时，SDK 会尝试仅使用指定的凭证提供程序来加载凭证。它不使用[默认凭证提供程序链](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**
+ [适用于 PHP 的 SDK 中的 `login` 提供程序](login-provider.md)
+ [适用于 PHP 的 SDK 中的 `assumeRole` 提供程序](assumerole-provider.md)
+ [适用于 PHP 的 SDK 中的 `sso` 提供程序](sso-provider.md)
+ [适用于 PHP 的 SDK 中的 `defaultProvider` 提供程序](defaultprovider-provider.md)
+ [适用于 PHP 的 SDK 中的 `ecsCredentials` 提供程序](ecscredentials-provider.md)
+ [适用于 PHP 的 SDK 中的 `env` 提供程序](env-provider.md)
+ [适用于 PHP 的 SDK 中的 `assumeRoleWithWebIdentityCredentialProvider` 提供程序](assume-role-with-web-identity-provider.md)
+ [适用于 PHP 的 SDK 中的 `ini` 提供程序](ini-provider.md)
+ [适用于 PHP 的 SDK 中的 `process` 提供程序](process-provider.md)
+ [适用于 PHP 的 SDK 中的 `instanceProfile` 提供程序](instanceprofile-provider.md)

# 适用于 PHP 的 SDK 中的 `login` 提供程序
<a name="login-provider"></a>

`Aws\Credentials\CredentialProvider::login`尝试加载由基于浏览器的登录会话配置的凭据，这些会话由 CLI AWS 等工具提供便利。身份验证后， AWS 生成适用于本地 AWS SDKs 和工具的临时证书。

通过此流程，您可以使用在初始账户设置期间创建的根证书、IAM 用户或身份提供商提供的联合身份进行身份验证，而 AWS SDK for PHP 会自动为您管理临时证书。这种方法无需在本地存储长期凭证，从而增强了安全性。

运行 `aws login` 命令时，您可以从活动控制台会话中进行选择，也可以通过基于浏览器的身份验证流程登录，这将自动生成临时凭证。 AWS 适用于 PHP 的 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`。

# 适用于 PHP 的 SDK 中的 `assumeRole` 提供程序
<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)。

# 适用于 PHP 的 SDK 中的 `sso` 提供程序
<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`”。要了解有关设置命名配置文件的更多信息，请参阅《工具参考指南》[`config`和《*工具参考指南》中的共享AWS SDKs 和`credentials`*文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。或者，您可以使用 [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 身份中心提供商的工作原理，请参阅*AWS SDKs 和工具参考指南*中的[了解 IAM 身份中心身份验证](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html)。

# 适用于 PHP 的 SDK 中的 `defaultProvider` 提供程序
<a name="defaultprovider-provider"></a>

 `Aws\Credentials\CredentialProvider::defaultProvider` 是默认凭证提供程序，也称为[默认凭证提供程序链](guide_credentials_default_chain.md)。如果您在创建客户端时省略 `credentials` 选项，则会使用此提供程序。例如，如果您创建一个 S3Client（如以下代码段所示），则 SDK 将使用默认提供程序：

```
$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
]);
```

# 适用于 PHP 的 SDK 中的 `ecsCredentials` 提供程序
<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
]);
```

# 适用于 PHP 的 SDK 中的 `env` 提供程序
<a name="env-provider"></a>

使用环境变量来包含您的凭据可以防止您意外共享您的 AWS 私有访问密钥。我们建议您不要在任何生产文件中将 AWS 访问密钥直接添加到客户端。

要对 Amazon Web Services 进行身份验证，SDK 首先检查环境变量中的凭证。开发工具包会使用 `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_ACCESS_KEY_ID``AWS_SECRET_KEY`、和`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()
]);
```

# 适用于 PHP 的 SDK 中的 `assumeRoleWithWebIdentityCredentialProvider` 提供程序
<a name="assume-role-with-web-identity-provider"></a>

 `Aws\Credentials\CredentialProvider::assumeRoleWithWebIdentityCredentialProvider` 尝试通过代入角色来加载凭证。如果存在环境变量 `AWS_ROLE_ARN` 和 `AWS_WEB_IDENTITY_TOKEN_FILE`，则提供商将尝试使用磁盘上的令牌（位于在 `AWS_WEB_IDENTITY_TOKEN_FILE` 中指定的完整路径上），代入在 `AWS_ROLE_ARN` 上指定的角色。如果使用环境变量，则提供商将尝试从 `AWS_ROLE_SESSION_NAME` 环境变量设置会话。

如果未设置环境变量，则提供商将使用默认配置文件或者设置为 `AWS_PROFILE` 的配置文件。默认情况下，提供商从 `~/.aws/credentials` 和 `~/.aws/config` 读取配置文件，并可读取 `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 可以提供完整版。凭证应按照提供的任何`false`方式进行设置 StsClient。

```
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
]);
```

# 适用于 PHP 的 SDK 中的 `ini` 提供程序
<a name="ini-provider"></a>

 `Aws\Credentials\CredentialProvider::ini` 尝试从共享的 `config` 和 `credentials` 文件中加载凭证。默认情况下，SDK 会尝试从位于的共享 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
]);
```

# 适用于 PHP 的 SDK 中的 `process` 提供程序
<a name="process-provider"></a>

 `Aws\Credentials\CredentialProvider::process`尝试通过执行[共享 AWS 配置文件中配置文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)中指定的`credential_process`值来加载凭证。

默认情况下，SDK 会先尝试从位于的共享 AWS `credentials`文件中加载 “默认” 配置文件`~/.aws/credentials`。如果在共享 `credentials` 文件中找不到“默认”配置文件，SDK 将在共享 `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
]);
```

# 适用于 PHP 的 SDK 中的 `instanceProfile` 提供程序
<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` 环境变量设置为 `true` 来禁用从 Amazon EC2 实例配置文件进行加载的尝试。

# 在适用于 PHP 的 SDK 中链接凭证提供程序
<a name="chaining-providers"></a>

可以使用 `Aws\Credentials\CredentialProvider::chain()` 函数将凭证提供程序链接起来。此函数接受可变数量的参数，每个参数都是凭证提供程序函数。然后，此函数会返回一个由提供的函数构成的新函数，这样便可以一个接一个地调用这些函数，直至其中一个提供程序返回已成功执行的 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 结合使用
<a name="creating-a-custom-provider"></a>

凭证提供程序只是在调用时返回承诺 (`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 中的凭证记忆
<a name="memoizing-credentials"></a>

有时，您可能需要创建能记住之前返回值的凭证提供程序。当加载凭证是一项代价高昂的操作时或在使用 `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());
```

当记住的凭证过期时，记忆包装器将调用可尝试刷新凭证的包装器提供程序。

# 使用 适用于 PHP 的 AWS SDK 版本 3 假设一个 IAM 角色
<a name="guide_credentials_assume_role"></a>

## 将 IAM 角色用于 Amazon EC2 实例可变凭证
<a name="instance-profile-credentials"></a>

如果您在 Amazon EC2 实例上运行应用程序，则提供用于调用的证书的首选方法 AWS 是使用 I [AM 角色](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'` 选项传递给客户端构造函数。这样，开发工具包便可改用缓存的实例配置文件凭证。有关详细信息，请参阅 [适用于 PHP 的 AWS SDK 版本 3 的配置](guide_configuration.md)。

有关使用开发 Amazon EC2 应用程序的更多信息 SDKs，请参阅*AWS SDKs 和工具参考指南*中的[为 Amazon EC2 实例使用 IAM 角色](https://docs.aws.amazon.com/sdkref/latest/guide/access-iam-roles-for-ec2.html)。

### 创建 IAM 角色并将其分配到 Amazon EC2 实例
<a name="create-and-assign-an-iam-role-to-an-ec2-instance"></a>

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 资源名称 (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 角色
<a name="ecs-credentials"></a>

亚马逊弹性容器服务 (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 账户
<a name="assuming-an-iam-role-in-another-aws-account"></a>

当您在 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']
    ]
]);
```

有关更多信息，请参阅[使用 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)或 适用于 PHP 的 AWS SDK API 参考[AssumeRole](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerole)中。

## 使用具备 Web 身份的 IAM 角色
<a name="using-an-iam-role-with-web-identity"></a>

Web 联合身份验证允许客户在访问 AWS 资源时使用第三方身份提供商进行身份验证。在您代入具备 Web 身份的角色之前，您必须先创建一个 IAM 角色并配置 Web 身份提供商 (IdP)。有关更多信息，请参阅 [创建用于 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 客户端对用户进行身份验证。 ProviderId 为你的身份提供 webIdentityToken 和，为用户提供权限的 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']
    ]
]);
```

有关更多信息，请参阅 “[通过基于 Web 的身份提供商进行AssumeRoleWithWebIdentity联](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)“ 适用于 PHP 的 AWS SDK API 参考”。

## 代入角色与配置文件
<a name="assume-role-with-profile"></a>

### 在 `~/.aws/credentials` 中定义配置文件
<a name="assume-role-profile-credentials-file"></a>

您可以通过在中定义配置文件 适用于 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` 中定义配置文件
<a name="assume-role-profile-config-file"></a>

`~/.aws/config` 文件还可以包含要代入的配置文件。如果设置了环境变量 `AWS_SDK_LOAD_NONDEFAULT_CONFIG`，则适用于 PHP 的 SDK 会从 `config` 文件中加载配置文件。设置 `AWS_SDK_LOAD_NONDEFAULT_CONFIG` 后，SDK 会同时从 `~/.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` 构造函数运行时（如以下代码段所示），将使用与 `default` 配置文件关联的凭证来代入 `project1` 配置文件中定义的角色。

```
$s3 = new Aws\S3\S3Client([
    'region' => 'us-east-1',
    'version' => '2006-03-01',
    'profile' => 'project1'
]);
```

# 使用适用于 PHP 的 SDK AWS STS 中的临时证书
<a name="guide_credentials_temporary"></a>

 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 联合身份](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)验证）。

## 获得临时凭证
<a name="getting-temporary-credentials"></a>

AWS STS 有几个返回临时证书的`GetSessionToken`操作，但演示起来最简单。以下代码段通过调用 PHP SDK 的 STS 客户端的 `getSessionToken` 方法来检索临时凭证。

```
$sdk = new Aws\Sdk([
    'region'   => 'us-east-1',
]);

$stsClient = $sdk->createSts();

$result = $stsClient->getSessionToken();
```

和其他 AWS STS 操作的`GetSessionToken`结果始终包含一个`'Credentials'`值。如果打印 `$result`（例如，通过使用 `print_r($result)`），则看起来如下所示。

```
Array
(
    ...
    [Credentials] => Array
    (
        [SessionToken] => '<base64 encoded session token value>'
        [SecretAccessKey] => '<temporary secret access key value>'
        [Expiration] => 2013-11-01T01:57:52Z
        [AccessKeyId] => '<temporary access key value>'
    )
    ...
)
```

## 向提供临时证书 适用于 PHP 的 AWS SDK
<a name="providing-temporary-credentials-to-the-sdk-php"></a>

您可以通过实例化 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()` 帮助程序方法。此方法从 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 中创建匿名客户端
<a name="guide_credentials_anonymous"></a>

在某些情况下，您可能想创建不与任何凭证关联的客户端。这样您便可以向服务发出匿名请求。

例如，您可以同时配置 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',
]);
```