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

# 憑證提供者
<a name="credential-providers"></a>

****  
**預設登入資料提供者鏈結解析 1.4.0 版所變更登入資料的順序。如需詳細資訊，請參閱以下備註。**

當您使用 將請求傳送至 Amazon Web Services 時 適用於 Kotlin 的 AWS SDK，必須使用 發行的憑證以密碼編譯方式簽署請求 AWS。Kotlin SDK 會自動為您簽署請求。若要取得登入資料，軟體開發套件可以使用位於多個位置的組態設定，例如 JVM 系統屬性、環境變數、共用 AWS `config`和`credentials`檔案，以及 Amazon EC2 執行個體中繼資料。

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 單一登入存取設定，則 SDK 會與 IAM Identity Center 搭配使用，以擷取用於提出請求的臨時憑證 AWS 服務。透過這種取得憑證的方法，開發套件會使用 IAM Identity Center 提供者 （也稱為 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. [Web 身分字符](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`)。根據字符資訊和角色，開發套件會取得臨時登入資料。

**4. [組態檔案中的設定檔](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)**  
在此步驟中，軟體開發套件會使用與設定檔相關聯的設定。根據預設，開發套件會使用共用 AWS `config`的 和 `credentials` 檔案，但如果已設定`AWS_CONFIG_FILE`環境變數，開發套件會使用該值。如果*未*設定`AWS_PROFILE`環境變數 （或 `aws.profile` JVM 系統屬性），軟體開發套件會尋找「預設」設定檔，否則會尋找符合`AWS_PROFILE’s`值的設定檔。  
開發套件會根據前一段所述的組態尋找設定檔，並使用其中定義的設定。如果 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`。如果 SDK 找到`credential_source`設定，它會根據`credential_source`設定的值，從 Amazon ECS 容器、Amazon EC2 執行個體或環境變數取得登入資料。然後，它會使用這些登入資料來取得角色的臨時登入資料。

   設定檔應包含 `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) - 如果 SDK 找到 ` sso_start_url`、`sso_account_id`、 `sso_region`和 `sso_role_name`設定，則 SDK 會從 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 `1.4.x+`的 SDK。在`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()
 }
```