擷取Workload Access Token - 智能體身分（Agent Identity）

本文為您詳細介紹什麼是工作負載存取權杖（Workload Access Token）以及擷取Workload Access Token的方式。

什麼是Workload Access Token

工作負載存取權杖（Workload Access Token）是一種不透明令牌（Opaque Token）。Agent Identity 服務在完成對調用者（通常為 Agent）的入站身份認證後，為工作負載身份（Workload Identity）簽發Workload Access Token。Agent 可使用 Workload Access Token 訪問 Agent Identity 服務，例如請求 OAuth 憑證供應商的存取權杖以訪問外部資源。

Workload Access Token有以下特點：

僅可用於訪問 Agent Identity 服務的相關介面。
令牌同時包含工作負載身份和終端使用者身份（調用者）的資訊。
該令牌由智能體運行時（如百鍊、AI Studio、LangStudio）在收到終端使用者請求後，通過調用 Agent Identity 服務自動擷取，並注入到智能體執行環境中。

Workload Access Token擷取方式

Agent Identity 提供三種介面用於擷取Workload Access Token，以適應不同的業務情境：

對比維度	`GetWorkloadAccessToken`	`GetWorkloadAccessTokenForJWT`	`GetWorkloadAccessTokenForUserId`
核心情境	無使用者參與，程式自動化	有使用者參與且使用者可以通過IdP完成登入	有使用者參與
使用者身份	無使用者身份	通過標準的 JWT (JSON Web Token) 驗證	通過自訂的使用者識別碼字串聲明
安全性	高。令牌僅代表 Agent 自身，安全可控。	最高。Agent Identity 服務會驗證 JWT 的簽名、頒發者（`iss`）和有效期間，確保使用者身份的真實性和時效性，是生產環境中的最佳實務。	中等。Agent Identity 服務完全信任調用方提供的 `userId` 字串，不做額外驗證。安全性依賴於調用方自身的身分識別驗證和會話管理。
使用情境	Agent 在後台運行，執行資料同步、報表產生等不涉及特定使用者資料的自動化任務。	使用者通過 OIDC 相容的身份供應商（如阿里雲、DingTalk、企業自建 IdP）登入應用後，應用後端使用使用者 IdP 簽發的 JWT 為 Agent 換取令牌，執行需強身分識別驗證的操作。	應用使用自建的使用者系統，無法簽發標準 JWT，但能為每個登入使用者產生穩定且唯一的 ID。適用於快速整合各種自訂身份系統或在開發測試階段類比使用者。
潛在風險/缺點	無法用於擷取與使用者個人賬戶綁定的憑證。	對調用方的要求最高，應用必須能夠擷取到使用者的 JWT。	調用方必須自行承擔確保 `userId` 唯一性、正確性和安全性的責任。如果 `userId` 被猜測或盜用，可能導致許可權升級風險。

若 Agent 部署在智能體運行時（如百鍊、AI Studio、LangStudio）中，則無需手動調用介面擷取 Workload Access Token。智能體運行時會根據傳入的使用者上下文資訊，自動選擇擷取令牌的方式：

使用者上下文資訊中包含使用者令牌時，調用 GetWorkloadAccessTokenForJWT 介面。
使用者上下文資訊中不含使用者令牌但包含使用者識別碼時，調用 GetWorkloadAccessTokenForUserId 介面。
使用者上下文資訊中既不含使用者令牌也不含使用者識別碼時，調用 GetWorkloadAccessToken 介面。

說明

調用 GetWorkloadAccessToken* 系列介面時，必須傳入已配置的 Workload Identity 名稱，且調用者必須完成入站身份認證。具體請參見入站認證方式。
調用以上介面前，必須在 RAM 中為調用者授予相應的權限原則。要求的權限如下：
- GetWorkloadAccessTokenForJWT介面：agentidentitydata:GetWorkloadAccessTokenForJWT
- GetWorkloadAccessTokenForUserId介面：agentidentitydata:GetWorkloadAccessTokenForUserId
- GetWorkloadAccessToken介面：agentidentitydata:GetWorkloadAccessToken

手動擷取Workload Access Token

可通過 Agent Identity SDK 擷取 Workload Access Token。範例程式碼（Python）如下：

from agent_identity_python_sdk import IdentityClient

identity_client = IdentityClient(region_id="cn-beijing")

# Get Workload Access Token by using user token
workload_access_token = identity_client.get_workload_access_token(
  workload_name="your-worload-identity-name",
  user_token="your-user-token"
)

# Get Workload Access Token by using user id
workload_access_token = identity_client.get_workload_access_token(
  workload_name="your-worload-identity-name",
  user_id="your-user-id"
)

# Get Workload Access Token without user id or user token
workload_access_token = identity_client.get_workload_access_token(workload_name="your-worload-identity-name")