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

# 适用于 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 实例配置文件进行加载的尝试。