View a markdown version of this page

取得工作負載存取字符 - Amazon Bedrock AgentCore
什麼是工作負載存取字符？執行期和閘道如何自動取得權杖如何手動擷取工作負載存取字符GetWorkloadAccessTokenForUserId API 的安全控制

取得工作負載存取字符

了解工作負載存取字符是什麼、如何取得它們，以及使用這些字符的安全層面對於建置安全代理程式應用程式至關重要。本節涵蓋您需要了解的重要概念和實作模式。

什麼是工作負載存取字符？

工作負載存取字符是 AWS簽署的不透明存取字符，可讓客服人員存取第一方 AgentCore 服務，例如傳出憑證提供者。執行期會自動將工作負載存取權杖做為承載標頭交付給代理程式執行執行個體，在大多數情況下不需要手動權杖管理。

重要特性

  • 僅限第一方服務 – 工作負載存取字符僅用於存取 AWS 第一方 AgentCore 服務，不能用於外部服務

  • 自動交付 – 執行期和閘道會在執行期間自動將這些字符提供給客服人員

  • 設計安全性 – 執行期受管代理程式身分無法直接擷取工作負載存取字符，防止字符擷取和濫用

  • 使用者和代理程式身分繫結 – 權杖同時包含使用者身分和代理程式身分資訊，以安全存取登入資料

執行期和閘道如何自動取得權杖

透過 AgentCore 執行期或閘道使用傳入身分驗證叫用代理程式時，服務會自動處理工作負載存取字符產生：

  1. 執行時間會驗證傳入身分提供者 OAuth 權杖 （發行者、簽章）

  2. 執行時間會從代表使用者身分的 OAuth 權杖中擷取發行者和子宣告

  3. 執行時間會擷取代理程式的相關聯工作負載身分

  4. GetWorkloadAccessTokenForJWT 同時具有使用者身分和代理程式工作負載身分的執行期調用

  5. 執行期會將工作負載存取權杖傳遞給代理程式程式碼，做為調用承載標頭的一部分

此自動程序可確保客服人員在不手動介入的情況下接收適當範圍的權杖。

如何手動擷取工作負載存取字符

有兩種模式可用來擷取工作負載存取權杖，具體取決於您如何識別代理程式的最終使用者：

模式 1：JWT 型識別 （建議用於生產）

如果客服人員的發起人有身分提供者為最終使用者發行的 JWT，請使用 請求工作負載存取字符GetWorkloadAccessTokenForJWT。當您提供 JWT 時，AgentCore Identity 會驗證權杖，以確保權杖正確簽署且未過期，並使用其「iss」和「sub」宣告來唯一識別使用者。代理程式代表使用者存放的登入資料與此密碼編譯驗證身分相關聯，未來的擷取需要具有相同身分的有效工作負載存取權杖。

在下列情況下使用此模式：

  • 您的應用程式會與身分提供者 (Cognito、Auth0、Okta 等） 整合

  • 您需要最終使用者身分的密碼編譯證明

  • 您正在部署到生產環境

模式 2：以 UserId 為基礎的識別

如果客服人員的發起人沒有識別最終使用者的 JWT，請使用 請求工作負載存取字符，GetWorkloadAccessTokenForUserId並具有識別使用者的唯一字串。

在下列情況下使用此模式：

  • 您的應用程式會管理自己的使用者識別符，而且您需要將客戶管理的 userId 字串傳遞給 AgentCore Identity

  • 您處於尚未提供 IdP 字符的開發或快速入門案例

  • 您的企業架構可在上游解析使用者身分，並將信任的識別符傳遞給客服人員工作負載

權衡：平台會將 userId 視為不透明字串，且無法針對已驗證的最終使用者身分進行驗證。安全繫結倚賴傳遞正確 userId 的呼叫工作負載，以及適當範圍的 IAM 政策。如需建議的控制項GetWorkloadAccessTokenForUserId API 的安全控制，請參閱 。

程式碼範例

以下範例說明使用 AgentCore 開發套件，以這兩種方法擷取工作負載存取字符：

from bedrock_agentcore.services.identity import IdentityClient

identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user.
# AgentCore Identity validates the JWT signature, issuer, and expiry.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user.
# Use this when a JWT is not available. The platform does not verify this string.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)

GetWorkloadAccessTokenForUserId API 的安全控制

GetWorkloadAccessTokenForUserId API 接受發起人提供的使用者識別符字串，並發出範圍限定於該使用者代理程式對的工作負載存取字符。此 API 旨在支援需要傳遞客戶受管 userId 字串的企業客戶，以及在開發期間沒有可用身分提供者 (IdP) 字符的建置器。

重要

當您使用 時GetWorkloadAccessTokenForUserId，平台會將該userId值視為不透明字串，而不會針對已驗證的最終使用者身分進行驗證。安全繫結完全依賴通過正確 userId 的呼叫工作負載，以及您的 IAM 政策的適當範圍。如果您的應用程式可以存取識別最終使用者的 JWT，請GetWorkloadAccessTokenForJWT改用 ，在發出工作負載存取字符之前驗證字符的發行者、簽章和過期。

GetWorkloadAccessTokenForUserId API 實作數個安全控制，以防止未經授權的存取：

  • 工作負載身分驗證 – API 會驗證請求的身分是否具有代表指定工作負載身分的許可

  • 服務受管身分限制 – 執行期受管和閘道受管工作負載身分無法直接擷取字符。這可防止客服人員擷取字符以供濫用

  • IAM 許可要求 – 來電者必須擁有適當的 IAM 許可，包括 GetWorkloadAccessToken 、 GetWorkloadAccessTokenForUserId 和 GetWorkloadAccessTokenForJWT

  • 權杖範圍 – 權杖的範圍限定於特定的使用者代理程式對，確保存放在某個使用者下的登入資料無法由另一個使用者存取

  • 多個身分提供者的使用者 ID 分割 – 使用多個身分提供者時，請使用 模式分割您的使用者 IDsprovider_id+user_id，以防止不同提供者之間的使用者衝突。例如，使用 cognito+user123和 auth0+user123 來區分不同身分提供者之間具有相同識別符的使用者

建議的安全控制

由於平台無法驗證 userId 字串，因此您必須負責確保傳遞給此 API 的值完整性。套用下列控制項：

  • 偏好在 JWT 可用GetWorkloadAccessTokenForJWT時 – JWT 型路徑會驗證字符的發行者和簽章，提供使用者身分的密碼編譯證明。GetWorkloadAccessTokenForUserId 僅在 JWT 無法使用時使用。

  • 從信任的來源衍生 userId – userId 值應衍生自已驗證主體的內容 （例如，IAM 呼叫者身分、工作階段屬性或上游身分解析層），而不是接受任意用戶端提供的值。這可防止已驗證的發起人模擬另一個使用者。

  • 限制 IAM 許可 – 只有信任的委託人才能擁有 bedrock-agentcore:GetWorkloadAccessTokenForUserId許可。將此許可範圍限定為特定工作負載身分資源。請勿透過受管政策或萬用字元資源陳述式廣泛授予。

  • 拒絕不需要GetWorkloadAccessTokenForUserId的地方 – 對於始終有 JWT 可用的工作負載，明確拒絕 IAM 政策中的 動作，以防止使用 userId 路徑：

    {
   "Statement": [
      {
         "Sid": "DenyForUserIdAccess",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default"
      }
   ]
}

  • 實作稽核記錄 – 記錄已驗證的 IAM 主體與要傳遞的 userId 值之間的關係。Use AWS CloudTrail 可監控GetWorkloadAccessTokenForUserId呼叫並偵測非預期的 userId 值。

如果您遇到錯誤「WorkloadIdentity 已連結至服務，且無法由發起人擷取存取字符」，這表示工作負載身分是由執行期或閘道管理，且無法直接擷取字符。此限制有助於維持安全界限，並防止未經授權的字符存取。

如需其他安全控制，您可以實作精細的存取政策，以限制哪些工作負載身分可以存取特定的登入資料提供者。如需詳細資訊，請參閱依工作負載身分縮小對憑證提供者的存取範圍。