擔任角色憑證提供者

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

若要設定您的 SDK或 工具以擔任角色，您必須先建立或識別要擔任的特定角色。IAM 角色由角色 Amazon Resource Name （） 唯一識別ARN。角色會與其他實體建立信任關係。使用 角色的受信任實體可能是 AWS 服務、另一個 AWS 帳戶、Web 身分提供者或 OIDC或SAML聯合。

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

如需開始使用這些設定的指引，請參閱本指南使用 AWS 憑證擔任角色中的 。

假設角色憑證提供者設定

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

credential_source - 共用 AWS config檔案設定

在 Amazon EC2執行個體或 Amazon Elastic Container Service 容器內使用，指定 SDK或 工具可以找到具有使用 role_arn 參數指定角色之許可的憑證。

預設值：無

有效值：

• 環境 – 指定 SDK或 工具是從環境變數 AWS_ACCESS_KEY_ID和 AWS_SECRET_ACCESS_KEY擷取來源憑證。

• Ec2InstanceMetadata – 指定 SDK或 工具使用IAM連接至EC2執行個體設定檔的角色來取得來源憑證。

• EcsContainer – 指定 SDK或 工具使用IAM連接到ECS容器的角色來取得來源憑證。

您無法在同一個描述檔中同時指定 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 使用者指南 中的檢視角色的工作階段持續時間上限設定。

在 config 檔案中設定的範例：

duration_seconds = 43200

external_id - 共用 AWS config檔案設定

指定一個唯一識別符，第三方用來在其客戶帳戶擔任角色。

此設定僅適用於設定檔指定擔任角色，且角色的信任政策需要 的值ExternalId。當設定檔指定角色時， 值會映射到傳遞至 AssumeRole 操作的 ExternalId 參數。

預設值：無。

有效值：請參閱 IAM 使用者指南 中的如何將 AWS 資源的存取權授予第三方時使用外部 ID。

在 config 檔案中設定的範例：

external_id = unique_value_assigned_by_3rd_party

mfa_serial - 共用 AWS config檔案設定

指定使用者擔任角色時必須使用的多重要素驗證 （MFA） 裝置的識別或序號。

擔任角色時為必要，其中該角色的信任政策包含需要MFA身分驗證的條件。

預設值：無。

有效值：該值可以是硬體裝置的序號 （例如 GAHT12345678），也可以是虛擬MFA裝置的 Amazon Resource Name （ARN）。如需 的詳細資訊MFA，請參閱 IAM 使用者指南 中的設定 MFA受保護API存取。

在 config 檔案中設定的範例：

mfa_serial = arn:aws:iam::123456789012:mfa/my-user-name

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 – 使用公有身分提供者或任何 OpenID Connect （OIDC） 相容身分提供者，供已在行動或 Web 應用程式中進行身分驗證的使用者使用。

role_session_name - 共用 AWS config檔案設定

AWS_ROLE_SESSION_NAME - 環境變數

aws.roleSessionName - JVM系統屬性：僅限 Java/Kotlin

指定要連接到角色工作階段的名稱。此名稱會出現在與工作階段相關聯的項目 AWS CloudTrail 日誌中，這在稽核時很有用。如需詳細資訊，請參閱 AWS CloudTrail 使用者指南 中的 CloudTrail userIdentity 元素。

預設值：選用參數。如果您不提供此值，則如果設定檔擔任角色，工作階段名稱會自動產生。

有效值：當 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 檔案。

如果您指定的設定檔也是擔任角色的設定檔，則每個角色都會依序擔任，以完全解析憑證。當 SDK遇到具有 憑證的設定檔時，此鏈會停止。角色鏈結會將您的 AWS CLI 或 AWS API角色工作階段限制為最多一小時，且無法增加。如需詳細資訊，請參閱 IAM 使用者指南 中的角色術語和概念。

預設值：無。

有效值：由 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 SDK。然後，您的程式碼會使用這些臨時憑證來存取 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

指定檔案的路徑，其中包含來自支援 2.0 OAuth 提供者或 OpenID Connect ID 身分提供者的存取權杖。

此設定透過使用 Web 身分聯合提供者進行身分驗證，例如 Google 、Facebook 和 Amazon 等。SDK 或 開發人員工具會載入此檔案的內容，並在代您呼叫AssumeRoleWithWebIdentity操作時將其傳遞為WebIdentityToken引數。

預設值：無。

有效值：此值必須是路徑和檔案名稱。檔案必須包含身分提供者提供給您的 OAuth 2.0 存取權杖或 OpenID Connect 權杖。相對路徑會被視為相對於程序的工作目錄。

與 的相容性 AWS SDKs

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

SDK	支援	備註或更多資訊
AWS CLI v2	是
SDK 適用於 C++	部分	credential_source 不支援。duration_seconds不支援。mfa_serial不支援。
SDK for Go V2 （1.x）	是
SDK for Go 1.x （V1）	是	若要使用共用config檔案設定，您必須開啟從組態檔案載入；請參閱工作階段 。
SDK 適用於 Java 2.x	部分	mfa_serial 不支援。
SDK 適用於 Java 1.x	部分	credential_source 不支援。mfa_serial不支援。JVM 不支援系統屬性。
SDK 適用於 JavaScript 3.x	是
SDK 適用於 JavaScript 2.x	部分	credential_source 不支援。
SDK 適用於 Kotlin	是
SDK 適用於 。NET 3.x	是
SDK 適用於 PHP 3.x	是
SDK for Python （Boto3）	是
SDK 適用於 Ruby 3.x	是
SDK for Rust	是
SDK 適用於 Swift	是
適用於 的工具 PowerShell	是