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

# 擔任角色登入資料提供者
<a name="feature-assume-role-credentials"></a>

**注意**  
如需了解設定頁面配置或解譯以下 **Support AWS SDKs和工具**資料表的說明，請參閱 [了解本指南的設定頁面](settings-reference.md#settingsPages)。

假設角色涉及使用一組臨時安全登入資料來存取 AWS 您可能無法存取的資源。這些臨時登入資料由存取金鑰 ID、私密存取金鑰和安全字符組成。

若要設定軟體開發套件或工具以擔任角色，您必須先建立或識別要擔任的特定*角色*。IAM 角色由角色 Amazon Resource Name ([ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html)) 唯一識別。角色會與其他實體建立信任關係。使用角色的信任實體可能是 AWS 服務、另一個 AWS 帳戶、Web 身分提供者或 OIDC 或 SAML 聯合。

識別 IAM 角色之後，如果您受該角色信任，您可以將 SDK 或工具設定為使用角色授予的許可。若要這樣做，請使用下列設定。

如需開始使用這些設定的指引，請參閱本指南[使用 AWS 登入資料來擔任角色以驗證 AWS SDKs和工具](access-assume-role.md)中的 。

## 擔任角色登入資料提供者設定
<a name="feature-assume-role-credentials-settings"></a>

使用下列項目設定此功能：

**`credential_source` - 共用 AWS `config`檔案設定**  
在 Amazon EC2 執行個體或 Amazon Elastic Container Service 容器內使用，以指定 SDK 或工具可以尋找登入資料的位置，這些登入資料具有使用 `role_arn` 參數擔任您指定之角色的許可。  
**預設值：**無  
**有效值**：  
+ **環境** – 指定 SDK 或工具是從環境變數 [`AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY`](feature-static-credentials.md)擷取來源憑證。
+ **Ec2InstanceMetadata** – 指定 SDK 或工具使用[連接到 EC2 執行個體描述檔的 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)來取得來源憑證。
+ **EcsContainer** – 指定 SDK 或工具使用[連接至 Amazon ECS 容器的 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html)或[連接至 Amazon EKS 容器的 IAM 角色](https://docs.aws.amazon.com/eks/latest/userguide/security-iam-service-with-iam.html)來取得來源憑證。
您無法在同一個描述檔中同時指定 `credential_source` 和 `source_profile`。  
在 `config` 檔案中設定此項目以表示登入資料應來自 Amazon EC2 的範例：  

```
credential_source = Ec2InstanceMetadata
role_arn = arn:aws:iam::123456789012:role/my-role-name
```

**`duration_seconds` - 共用 AWS `config`檔案設定**  
指定角色工作階段的最大持續時間 (以秒為單位)。  
此設定只有在設定檔指定 擔任角色時才適用。  
**預設值：**3600 秒 （一小時）  
**有效值：**值的範圍可以從 900 秒 (15 分鐘） 到為角色設定的工作階段持續時間上限 （最多可達 43200 秒或 12 小時）。如需詳細資訊，請參閱[《IAM 使用者指南》中的檢視角色的工作階段持續時間上限設定](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session)。 **  
在 `config` 檔案中設定的範例：  

```
duration_seconds = 43200
```

**`external_id` - 共用 AWS `config`檔案設定**  
指定一個唯一識別符，第三方用來在其客戶帳戶擔任角色。  
此設定僅適用於設定檔指定 擔任角色，且角色的信任政策需要 的值時`ExternalId`。當設定檔指定角色時， 值會映射至傳遞至 `AssumeRole`操作的 `ExternalId` 參數。  
**預設值：**無。  
**有效值：**請參閱《*IAM 使用者指南*》中的[如何在將 AWS 資源的存取權授予第三方時使用外部 ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)。  
在 `config` 檔案中設定的範例：  

```
external_id = unique_value_assigned_by_3rd_party
```

**`mfa_serial` - 共用 AWS `config`檔案設定**  
指定使用者擔任角色時必須使用的多重驗證 (MFA) 裝置的識別或序號。  
擔任角色時為必要，其中該角色的信任政策包含需要 MFA 身分驗證的條件。如需 MFA 的詳細資訊，請參閱《[AWS IAM 使用者指南》中的 IAM 中的多重要素驗證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html)。 **  
**預設值：**無。  
**有效值：**該值可以是硬體裝置的序號 （例如 `GAHT12345678`)，也可以是虛擬 MFA 裝置的 Amazon Resource Name (ARN)。ARN 的格式為： `arn:aws:iam::account-id:mfa/mfa-device-name`  
在 `config` 檔案中設定的範例：  
此範例假設已為帳戶`MyMFADevice`建立並為使用者啟用的虛擬 MFA 裝置，稱為 。  

```
mfa_serial = arn:aws:iam::123456789012:mfa/MyMFADevice
```

**`role_arn` - 共用 AWS `config`檔案設定`AWS_ROLE_ARN` - 環境變數`aws.roleArn` - JVM 系統屬性：僅限 Java/Kotlin**  
指定您要用來執行使用此設定檔請求之操作的 IAM 角色的 Amazon Resource Name (ARN)。  
**預設值：**無。  
**有效值：**該值必須是 IAM 角色的 ARN，格式如下： `arn:aws:iam::account-id:role/role-name`  
 此外，您還必須指定下列**其中一項**設定：  
+ `source_profile` – 識別另一個設定檔，用來尋找具有在此設定檔中擔任角色之許可的登入資料。
+ `credential_source` – 使用目前環境變數識別的登入資料，或連接至 Amazon EC2 執行個體描述檔的登入資料，或 Amazon ECS 容器執行個體。
+ `web_identity_token_file` – 針對已在行動或 Web 應用程式中驗證的使用者，使用公有身分提供者或任何 OpenID Connect (OIDC) 相容身分提供者。

**`role_session_name` - 共用 AWS `config`檔案設定`AWS_ROLE_SESSION_NAME` - 環境變數`aws.roleSessionName` - JVM 系統屬性：僅限 Java/Kotlin**  
指定要連接到角色工作階段的名稱。此名稱會出現在與此工作階段相關聯的項目 AWS CloudTrail 日誌中，這在稽核時非常有用。如需詳細資訊，請參閱*AWS CloudTrail 《 使用者指南*》中的 [CloudTrail userIdentity 元素](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)。  
**預設值：**選用參數。如果您未提供此值，則在設定檔擔任角色時，工作階段名稱會自動產生。  
**有效值：**當 AWS CLI 或 AWS API 代表您呼叫 `AssumeRole`操作 （或 操作等`AssumeRoleWithWebIdentity`操作） 時，提供給 `RoleSessionName` 參數。此值會成為您可以查詢的擔任角色使用者 Amazon Resource Name (ARN) 的一部分，並顯示為此設定檔所調用之操作的 CloudTrail 日誌項目的一部分。  
 `arn:aws:sts::123456789012:assumed-role/my-role-name/my-role_session_name`.  
在 `config` 檔案中設定的範例：  

```
role_session_name = my-role-session-name
```

**`source_profile` - 共用 AWS `config`檔案設定**  
指定另一個設定檔，其登入資料用於擔任原始設定檔中 `role_arn`設定所指定的角色。若要了解如何在共用 AWS `config` 和 `credentials` 檔案中使用設定檔，請參閱 [共用 `config`和 `credentials` 檔案](file-format.md)。  
如果您指定的設定檔也是擔任角色設定檔，則每個角色都會依序擔任，以完全解析登入資料。當 SDK 遇到具有登入資料的設定檔時，此鏈結會停止。角色鏈結會將您的 AWS CLI 或 AWS API 角色工作階段限制為最多一小時，且無法增加。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[角色術語和概念](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html)。  
**預設值：**無。  
**有效值：**文字字串，由 `config`和 `credentials`檔案中定義的設定檔名稱組成。您還必須在目前的設定檔`role_arn`中指定 的值。  
您無法在同一個描述檔中同時指定 `credential_source` 和 `source_profile`。  
在組態檔案中設定的範例：  

```
[profile A]
source_profile = B
role_arn =  arn:aws:iam::123456789012:role/RoleA
role_session_name = ProfileARoleSession
                
[profile B]
credential_process = ./aws_signing_helper credential-process --certificate /path/to/certificate --private-key /path/to/private-key --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID --role-arn arn:aws:iam::account:role/ROLE_ID
```
在先前的範例中，`A`設定檔會告知 SDK 或工具自動查詢連結`B`設定檔的登入資料。在此情況下， `B`設定檔會使用 提供的登入資料協助程式工具[使用 IAM Roles Anywhere 驗證 AWS SDKs和工具](access-rolesanywhere.md)來取得 SDK 的 AWS 登入資料。然後，您的程式碼會使用這些臨時登入資料來存取 AWS 資源。指定的角色必須已連接允許請求程式碼執行的 IAM 許可政策，例如 命令 AWS 服務或 API 方法。設定檔採取的每個動作`A`都會包含 CloudTrail 日誌中的角色工作階段名稱。  
對於角色鏈結的第二個範例，如果您在 Amazon Elastic Compute Cloud 執行個體上有應用程式，而且您想要讓該應用程式擔任另一個角色，則可以使用下列組態。  

```
[profile A]
source_profile = B
role_arn =  arn:aws:iam::123456789012:role/RoleA
role_session_name = ProfileARoleSession
                
[profile B]
credential_source=Ec2InstanceMetadata
```
設定檔`A`將使用來自 Amazon EC2 執行個體的登入資料擔任指定的角色，並自動續約登入資料。  


**`web_identity_token_file` - 共用 AWS `config`檔案設定`AWS_WEB_IDENTITY_TOKEN_FILE` - 環境變數`aws.webIdentityTokenFile` - JVM 系統屬性：僅限 Java/Kotlin**  
指定檔案的路徑，其中包含來自[支援 OAuth 2.0 提供者](https://wikipedia.org/wiki/List_of_OAuth_providers)或 [OpenID Connect ID 身分提供者](https://openid.net/developers/certified/)的存取權杖。  
此設定可透過使用 [Google](https://developers.google.com/identity/protocols/OAuth2)、[Facebook](https://developers.facebook.com/docs/facebook-login/overview) 和 [Amazon](https://login.amazon.com/) 等 Web 聯合身分提供者來啟用身分驗證。SDK 或開發人員工具會載入此檔案的內容，並在代您呼叫`AssumeRoleWithWebIdentity`操作時將其做為`WebIdentityToken`引數傳遞。  
**預設值：**無。  
**有效值：**此值必須是路徑和檔案名稱。檔案必須包含身分提供者提供給您的 OAuth 2.0 存取字符或 OpenID Connect 字符。相對路徑視為相對於程序的工作目錄。

## 支援 AWS SDKs和工具
<a name="assume-role-sdk-compat"></a>

下列 SDKs 支援本主題中所述的功能和設定。會記下任何部分例外狀況。 適用於 Java 的 AWS SDK 和 適用於 Kotlin 的 AWS SDK 僅支援任何 JVM 系統屬性設定。


| SDK | 支援 | 備註或更多資訊 | 
| --- | --- | --- | 
| [AWS CLI  ](https://docs.aws.amazon.com/cli/latest/userguide/) v2 | 是 |  | 
| [適用於 C\$1\$1 的 SDK](https://docs.aws.amazon.com/sdk-for-cpp/latest/developer-guide/) | 部分 | credential\$1source 不支援。duration\$1seconds不支援。mfa\$1serial不支援。 | 
| [適用於 Go 的 SDK V2 (1.x)](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/) | 是 |  | 
| [適用於 Go 的 SDK 1.x (V1)](https://docs.aws.amazon.com/sdk-for-go/latest/developer-guide/) | 是 | 若要使用共用config檔案設定，您必須開啟從組態檔案載入；請參閱[工作階段](https://docs.aws.amazon.com/sdk-for-go/api/aws/session/)。 | 
| [適用於 Java 的 SDK 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/) | 部分 | mfa\$1serial 不支援。duration\$1seconds不支援。 | 
| [適用於 Java 的 SDK 1.x](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/) | 部分 | credential\$1source 不支援。mfa\$1serial不支援。不支援 JVM 系統屬性。 | 
| [適用於 JavaScript 3.x 的 SDK](https://docs.aws.amazon.com/sdk-for-javascript/latest/developer-guide/) | 是 |  | 
| [適用於 JavaScript 2.x 的 SDK](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/) | 部分 | credential\$1source 不支援。 | 
| [適用於 Kotlin 的 SDK](https://docs.aws.amazon.com/sdk-for-kotlin/latest/developer-guide/) | 是 |  | 
| [適用於 .NET 4.x 的 SDK](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/) | 是 |  | 
| [適用於 .NET 3.x 的 SDK](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/) | 是 |  | 
| [適用於 PHP 的 SDK 3.x](https://docs.aws.amazon.com/sdk-for-php/latest/developer-guide/) | 是 |  | 
| [適用於 Python 的 SDK (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) | 是 |  | 
| [適用於 Ruby 的 SDK 3.x](https://docs.aws.amazon.com/sdk-for-ruby/latest/developer-guide/) | 是 |  | 
| [適用於 Rust 的 SDK](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/) | 是 |  | 
| [適用於 Swift 的 SDK](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/) | 是 |  | 
| [PowerShell V5 的工具](https://docs.aws.amazon.com/powershell/latest/userguide/) | 是 |  | 
| [PowerShell V4 的工具](https://docs.aws.amazon.com/powershell/v4/userguide/) | 是 |  |