Identity as a Service：基於 AgentRun 的 Agent 身份安全最佳實務

3.1 部署Function Compute

1. 登入Function Compute FC 控制台。

2. 在左側導覽列中選擇 函数管理 > 函數列表。

3. 選擇 Web 函数頁簽，單擊创建 Web 函數。

4. 運行環境選擇 自定义运行时 > Java > Java 17。

5. 代码上传方式選擇使用示例代码，其他配置保持預設。

6. 完成函數建立。

3.2 配置 JWT 認證

為函數的 HTTP 觸發器配置 JWT 認證，確保只有持有 IDaaS 簽發的 Access Token 才能訪問企業服務。

1. 進入 IDaaS 執行個體控制台，單擊Agent 身份安全配置指導中建立的企业服务節點。

2. 複製通用配置下的OIDC发现端点，在瀏覽器中開啟，複製驗簽公開金鑰端點（即jwks_uri欄位的值）。

3. 在瀏覽器中訪問驗簽公開金鑰端點，複製全部返回內容。

4. 進入Function Compute控制台，在函數列表中找到上一步中建立的函數，單擊操作列下的配置。

5. 在函数详情頁簽中單擊函数拓扑图中的触发器，认证方式選擇JWT 认证。

6. 將驗簽公開金鑰端點返回的內容填入 JWKS 配置項中。

7. 在 JWT Token 配置中將参数名称 設定為 Authorization。

8. 完成配置。

AgentRun 部署

1. 打包並壓縮 Agent 範例程式碼

   在終端執行以下命令：

   cd idaas-java-agent-id-demo
   mvn clean package
   cd ../
   zip -r idaas-java-agent-id-demo.zip idaas-java-agent-id-demo/

2. 建立執行角色

   1. 登入存取控制 RAM 控制台

   2. 單擊導覽列中的身份管理 > 角色。

   3. 單擊創建角色，信任主體類型選擇 雲服務，信任主體名稱選擇Function Compute/FC 。

   4. 角色名稱設定為 sample-fc-role。

3. 建立 Agent

   1. 登入Function Compute FC 控制台。

   2. 在左側導覽列中選擇 函数智能 > 智能體 AgentRun。

   3. 在角色授權檢查中單擊 一鍵授權（首次建立時需要）。

   4. 單擊建立 Agent，選擇通過代碼建立。

   5. 代碼來源選擇 上傳程式碼封裝，運行時選擇 Java 17。

   6. 上傳壓縮好的 idaas-java-agent-id-demo.zip 檔案。

   7. 啟動命令填入：

      java -Dcloud_idaas_config_path=classpath:cloud_idaas_config_for_agent_run.json -jar idaas-java-agent-id-demo/target/idaas-java-agent-id-demo-1.0.jar

   8. 啟動連接埠填入 9002。

   9. 配置環境變數。

      環境變數名	說明	擷取方式
      IDAAS_CLIENT_SECRET	Agent 的 Client Secret 憑證（使用 Client Secret 認證時必填）	Agent 身份安全配置指導中建立的 Agent 節點的通用配置中查看。
      ENV_PRIVATE_KEY	Agent 的私密金鑰（使用公私密金鑰認證時必填）	Agent 身份安全配置指導中，為 Agent 節點建立公私密金鑰憑證時所上傳公開金鑰對應的私密金鑰。
      JWKS_ENDPOINT	IDaaS 驗簽公開金鑰端點	格式為：https://xxx.aliyunidaas.com/api/v2/iauths_system/oauth2/jwks。 其中 xxx 取自步驟二：配置 IDaaS SDK的SDK 設定檔中 issuer 欄位的對應值。
      AGENT_AUDIENCE	Agent 的受眾標識	Agent 身份安全配置指導中建立的 Agent 節點的通用配置中查看。
      AGENT_SCOPE	Agent 的許可權標識	Agent 身份安全配置指導中建立的 Agent 節點的权限配置中查看。
      ACCESS_IDENTITY	Agent 身份模式：Machine（機器身份）或 Human（使用者身份）	本執行個體中使用 Machine（機器身份），適用於 Agent 以自身身份獨立操作的情境，下遊服務感知到的是 Agent 的機器身份
      LLM_API_KEY_IDENTIFIER	大模型 API Key 標識	Agent 身份安全配置指導中建立的大模型節點中查看。
      EXTERNAL_SERVER_API_KEY_IDENTIFIER	第三方服務 API Key 標識	Agent 身份安全配置指導中建立的三方服务節點中查看。
      ENTERPRISE_SERVICE_SCOPE	企業服務存取範圍（受眾標識 | 許可權標識）	格式為：受眾標識 | 許可權標識。 Agent 身份安全配置指導中建立的企业服务節點中的通用配置下查看受眾標識，权限配置下查看权限标识。
      EXTERNAL_SERVER_URL	三方服務的 Endpoint	高德 MCP Server HTTP Endpoint，從百鍊平台的高德地圖 MCP 中查看。
      ENTERPRISE_SERVICE_URL	企業服務 Endpoint	3.2 配置 JWT 認證中在函数详情頁簽中單擊函数拓扑图中的触发器，可查看公网访问地址。

   10. 執行角色選擇之前建立的 sample-fc-role。

   11. 單擊 開始部署。

   12. 部署完成後，在 Agent 卡片右下角單擊詳情，在左側導覽列中選擇版本與灰階，單擊建立 Endpoint。

5.1 前端 UI 配置

修改 Agent 範例程式碼中的 frontend/config.js 檔案：

window.APP_CONFIG = {
  API_URL: 'http://localhost:9002/openai/v1/chat/completions',
  IDAAS_AUTHORIZE_ENDPOINT: 'https://xxx.aliyunidaas.com/login/app/common/oauth2/authorize',
  IDAAS_LOGOUT_ENDPOINT: 'https://xxx.aliyunidaas.com/login/app/common/oauth2/logout',
  CLIENT_ID: '{client_id}',
  SCOPE: 'https://agentserver.example.com|agent.access',
};

5.2 啟動前端 UI

在終端執行以下命令（需安裝 Nodejs）：

cd frontend
npx http-server -p 9001

5.3 配置用戶端應用

1. 進入 IDaaS EIAM 控制台。

2. 在左側導覽列中單擊应用管理> M2M应用管理。

3. 定位Agent 身份安全配置指導中建立的客户端節點，單擊操作列下的管理。

4. 單擊登录访问頁簽，在授权模式下勾選隐式模式。

5. 隐式模式参数的返回类型 Response Types選擇 Token。

6. 登录 Redirect URI填入前端 UI 啟動地址：http://127.0.0.1:9001/。

7. 單擊顯示進階配置，登出回調地址填入前端 UI 啟動地址：http://127.0.0.1:9001/。

8. 完成配置。

修改 IDaaS SDK 配置

修改 src/main/resources/cloud_idaas_config_for_agent_run.json，在原有配置基礎上新增 openApiEndpoint，並修改 authnConfiguration，其餘欄位保持不變：

{
    "idaasInstanceId": "idaas_xxx",      
    "clientId": "app_xxx",               
    "issuer":"https://xxx/api/v2/iauths_system/oauth2",               
    "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
    "scope": "api.example.com|read:file",
    "openApiEndpoint":"eiam.[region_id].aliyuncs.com",
    "developerApiEndpoint":"eiam-developerapi.[region_id].aliyuncs.com",
    "authnConfiguration": {
      "identityType": "CLIENT",
      "authnMethod": "PLUGIN",
      "pluginName": "alibabacloudPluginCredentialProvider"
  }
}

詳細的配置說明，可參見環境準備。

執行角色配置

AgentRun 執行角色需具備調用 IDaaS GenerateOauthToken OpenAPI 的許可權，樣本權限原則如下：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "eiam:GenerateOauthToken",
      "Resource": [
        "acs:eiam:{regionId}:{accountId}:instance/{InstanceId}/application/{ApplicationId}"
      ]
    }
  ]
}

將 {regionId}、{accountId}、{InstanceId}、{ApplicationId} 替換為實際的地區 ID、阿里雲主帳號 ID、IDaaS 執行個體 ID 和 Agent ID。

建立權限原則與授權執行角色，詳細配置可參見阿里雲 OpenAPI 認證。

AgentRun 部署服務時，需按上述說明修改 SDK 配置並將配置執行角色，其餘流程均保持一致。