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

# 凭证提供程序
<a name="credential-providers"></a>

****  
**默认凭证提供程序链解析在 1.4.0 版本中更改的凭据的顺序有关详细信息，请参阅以下注释。**

当您使用向 Amazon Web Services 发送请求时 适用于 Kotlin 的 AWS SDK，必须使用颁发的凭证对请求进行 AWS加密签名。Kotlin 软件开发工具包会自动为您签署请求。要获取证书，软件开发工具包可以使用位于多个位置的配置设置，例如 JVM 系统属性、环境变量、共享 AWS `config`和`credentials`文件以及 Amazon EC2 实例元数据。

SDK 使用*凭证提供程序*抽象来简化从各种来源检索凭证的过程。SDK 包含[多个凭据提供程序实现](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/aws-config/aws.sdk.kotlin.runtime.auth.credentials/index.html)。

例如，如果检索到的配置包括共享`config`文件中的 IAM Identity Center 单点登录访问权限设置，则软件开发工具包将与 IAM Identity Center 合作检索用于向其发出请求的临时证书。 AWS 服务通过这种获取证书的方法，软件开发工具包使用 IAM 身份中心提供商（也称为 SSO 凭证提供商）。本指南的[设置部分](setup-basic-onetime-setup.md#setup-sso-access)描述了此配置。

要使用特定的凭据提供程序，可以在创建服务客户端时指定一个。或者，您可以使用默认凭证提供程序链自动搜索配置设置。

## 默认凭证提供者链
<a name="default-credential-provider-chain"></a>

如果在客户端构造时没有明确指定，Kotlin 的 SDK 会使用凭证提供程序，该提供程序会按顺序检查每个可以提供凭据的地方。此默认凭证提供程序是作为证书提供者链实现的。

要使用默认链在应用程序中提供凭证，请在不显式提供`credentialsProvider`属性的情况下创建服务客户端。

```
val ddb = DynamoDbClient {
    region = "us-east-2"
}
```

有关创建服务客户端的更多信息，请参阅[构造和配置客户端](creating-clients.md)。

### 了解默认凭证提供商链
<a name="default-credentials-retrieval-order"></a>

默认凭证提供程序链使用以下预定义顺序搜索凭证配置。当配置的设置提供有效的凭据时，链就会停止。

**1。 [AWS 访问密钥（JVM 系统属性）](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html)**  
SDK 会查找`aws.accessKeyId``aws.secretAccessKey`、和 `aws.sessionToken` JVM 系统属性。

**2。 [AWS 访问密钥（环境变量）](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html)**  
SDK 尝试从 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 以及 `AWS_SESSION_TOKEN` 环境变量加载凭证。

**3. [网络身份令牌](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role-web.html)**  
SDK 会查找环境变量`AWS_WEB_IDENTITY_TOKEN_FILE`和`AWS_ROLE_ARN`（或 JVM 系统属性`aws.webIdentityTokenFile`和`aws.roleArn`）。根据令牌信息和角色，SDK 获取临时证书。

**4. [配置文件中的配置文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)**  
在此步骤中，SDK 使用与配置文件关联的设置。默认情况下，SDK 使用共享 AWS `config`和`credentials`文件，但如果设置了`AWS_CONFIG_FILE`环境变量，SDK 将使用该值。如果*未*设置`AWS_PROFILE`环境变量（或 `aws.profile` JVM 系统属性），SDK 将查找 “默认” 配置文件，否则会查找与`AWS_PROFILE’s`值匹配的配置文件。  
SDK 根据上一段所述的配置查找配置文件，并使用此处定义的设置。如果 SDK 找到的设置包含适用于不同凭证提供者方法的混合设置，则 SDK 将按以下顺序排列：  

1. [AWS 访问密钥（配置文件）](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html)-SDK 使用`aws_access_key_id``aws_access_key_id`、和的设置`aws_session_token`。

1. [假设角色配置](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html)-如果 SDK 找到`role_arn`和 `source_profile` /或`credential_source`设置，则会尝试代入角色。如果 SDK 找到了该`source_profile`设置，它会从另一个配置文件获取凭证，以接收指定角色的临时证书`role_arn`。如果软件开发工具包找到了该`credential_source`设置，则它会根据设置的值从 Amazon ECS 容器、Amazon EC2 实例或环境变量中`credential_source`获取证书。然后，它使用这些证书为该角色获取临时证书。

   配置文件应包含`source_profile`设置或`credential_source`设置，但不能同时包含两者。

1. [Web 身份令牌配置](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role-web.html)-如果 SDK 找到`role_arn`并进行了`web_identity_token_file`设置，则它会根据`role_arn`和令牌获取访问 AWS 资源的临时证书。

1. [SSO 令牌配置](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html)-如果软件开发工具包找到`sso_session`、`sso_account_id`、`sso_role_name`设置（以及配置文件中的配套`sso-session`部分），则软件开发工具包将从 IAM Identity Center 服务中检索临时证书。

1. [旧版 SSO 配置](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-legacy)-如果软件开发工具包找到` sso_start_url`、`sso_region``sso_account_id`、和`sso_role_name`设置，则软件开发工具包会从 IAM Identity Center 服务中检索临时证书。

1. [登录配置](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-legacy)-如果 SDK 找到`login_session`设置，它将使用登录会话中的临时证书，或者如果这些证书在 5 分钟内过期，则尝试刷新它们。要了解如何启动登录会话，请参阅 [AWS CLI 用户指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)。

1. [流程配置](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html)-如果 SDK 找到`credential_process`设置，它将使用路径值来调用流程并获取临时证书。

**5. [容器凭证](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html)**  
SDK 会查找环境变量`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`或`AWS_CONTAINER_CREDENTIALS_FULL_URI`和`AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`或`AWS_CONTAINER_AUTHORIZATION_TOKEN`。它使用这些值通过 GET 请求从指定的 HTTP 端点加载证书。

**6. [IMDS 凭证](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html)**  
SDK 尝试使用默认或配置的 HTTP 端点从[实例元数据服务](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)获取凭证。SDK 仅支持[IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)。

如果此时仍未解析凭证，则客户端创建会失败，但会出现异常。

**注意：更改凭据解析顺序**  
上面描述的凭证解析顺序适用于适用于 Kotlin 的 SDK 的`1.4.x+`发布。在`1.4.0`发布之前，3号和4号的物品被切换，当前的4a物品紧随当前的4g物品。

## 指定凭证提供商
<a name="explicit-credential-provider"></a>

您可以指定凭证提供商，而不是使用默认的提供者链。通过这种方法，您可以直接控制 SDK 使用哪些凭据。

例如，要使用代入的 IAM 角色的证书，请在创建客户端`StsAssumeRoleCredentialsProvider`时指定：

```
val ddb = DynamoDbClient {
    region = "us-east-1"
    credentialsProvider = StsAssumeRoleCredentialsProvider()
}
```

您也可以创建一个自定义链 (`CredentialsProviderChain`)，该链按您的首选顺序组合多个提供商。

### 使用独立提供商缓存凭证
<a name="credentials-caching"></a>

**重要**  
默认链会自动缓存凭证。独立提供商不缓存凭证。为避免在每次 API 调用时获取凭证，请将您的提供程序包起来。`CachedCredentialsProvider`仅当当前凭证过期时，缓存的提供者才会获取新凭证。

要使用独立提供程序缓存凭证，请使用以下`CachedCredentialsProvider`类：

```
val ddb = DynamoDbClient {
     region = "us-east-1"
     credentialsProvider = CachedCredentialsProvider(StsAssumeRoleCredentialsProvider())
 }
```

 或者，使用`cached()`扩展函数获取更简洁的代码：

```
val ddb = DynamoDbClient {
      region = "us-east-1"
      credentialsProvider = StsAssumeRoleCredentialsProvider().cached()
 }
```