【2026 最新】Agentic Identity Broker 教學：兩個 Agent 的 OAuth 委派怎麼撤權？

你請一個 Agent 整理文件，再請另一個 Agent 處理待辦。兩個都用你的帳號做事；當你只想停掉其中一個，究竟該刪哪一份授權？這篇 Agentic Identity Broker 教學，從兩份假委託單出發，帶你分清「撤掉 Agent」與「斷開外部服務」的差別。

前半寫給第一次接觸 OAuth 的讀者，用跑腿者、委託單與鑰匙解釋；後半給願意開終端機、或和開發者一起驗收的人，走官方 Mock 入門，再設計雙 Agent 撤權對照。你會知道應該觀察哪一層，而不只看畫面有沒有顯示成功。

以下依 2026 年 11 月 7 日查閱的官方文件與程式整理，程式快照為 f289728ce439。本文環境未提供 Docker，未執行完整容器流程；步驟與預期行為來自官方文件、實作及測試案例，雙 Agent 的傳播時間保留給你的環境量測。

先說結論：委託單管交換，鑰匙有自己的有效期

一次可用的工具呼叫＝有效委派＋可用服務連線＋Gateway 放行＋下游接受 token。 Grant 是「誰准許哪個 Agent 做什麼」；provider session 是「Broker 保管的服務連線」；token 則是外部服務認得的鑰匙。三者有關係，卻各有生命週期。

• 撤銷 grant，重點是阻擋該 Agent 後續向 Broker 換取憑證。
• 終止 provider session，影響的是使用這份服務連線的多個 Agent。
• Gateway 若仍有可用快取，下一次工具呼叫的結果需要另外驗收。
• 已發出的 provider token，還受到服務端有效期與撤銷機制約束。

一、Agentic Identity Broker 教學：先認識五個角色

把它想成公司櫃檯：你是委託人，Agent 是跑腿同事，Broker 管委託單與鑰匙櫃，Gateway 是出入口，外部服務是辦事窗口。OAuth（讓程式取得限定存取權的授權框架）提供協定；Broker 把許多服務的授權與每個 Agent 的同意關係接起來。

• ①「本人」Principal：已通過登入系統驗證的人。正式部署由可信反向代理把身分交給 Broker。
• ②「跑腿者」Agent：在 Broker 註冊的軟體身分，以 UUID 識別；顯示名稱供人閱讀。
• ③「委託單」Grant：某個人授予某個 Agent 的 permission sets，可附到期時間。
• ④「鑰匙櫃」Provider session：同一個人與同一項服務之間的 OAuth 連線，保存加密的 access／refresh token。
• ⑤「出入口」Gateway：驗證 Agent 帶來的 token，透過 Broker 取得適合下游的憑證，再轉送工具請求。

Permission set 是管理者替一組服務 scopes 取的白話名稱，例如「讀取儲存庫」。依官方委派模型，同一人與同一 Agent 最多一份有效 grant；同一人與同一服務共用一份 session。換句話說，兩張委託單可以借用同一個鑰匙櫃。

二、既有 OAuth 已能委派，為什麼還要 Broker？

先講答案：OAuth 本來就能授權，Token Exchange 也已有標準。 RFC 8693定義了用 token 換取另一種 token 的請求與回應。這個專案的價值，是把多服務憑證保管、每個 Agent 的同意、交換與稽核放進共同的執行路徑。

例如，研究助理 A 讀文件，排程助理 B 看行程。你希望收回 A 的讀取權，仍讓 B 繼續工作。若兩者直接持有同一份外部服務憑證，管理者很難只靠那把鑰匙分辨委託關係。Broker 讓每次交換帶有使用者、Agent 與目標資源，據此檢查授權。

它也需要現有登入系統。官方對 IdP 的分工說明把人員登入、單一登入與多因素驗證留給身分提供者；Broker 處理代理委派。若你只是做一個簡單應用，先把現有 OAuth 流程接好；多個 Agent、多種服務、集中撤權與稽核需求出現時，再評估這層基礎設施。

若「模型」與「替模型執行工作的一圈程式」還混在一起，先讀Agent Harness 白話教學。身分、工具、停止條件都屬於系統接線，不能只靠提示詞表達。

三、Agentic Identity Broker 教學上手：先跑官方 Mock

第一步「先備好練習場」：已有 Docker Compose v2、Git、curl、OpenSSL 與 jq 的讀者，可在新的練習目錄依官方 Get started啟動。示範使用假 OAuth 供應商，這一輪不連真實 Google 或 GitHub 帳號。先用 docker compose version 確認工具存在，再記錄版本。

git clone https://github.com/zalando-incubator/agentic-identity-broker.git
cd agentic-identity-broker
git checkout f289728ce439aea9b0a67e153614732fa79b1ce3
test -f .env.compose || cp .env.compose.example .env.compose
IDENTITY_BROKER_JWE_SIGNING_KEY="$(./scripts/generate-jwe-key.sh)" \
IDENTITY_BROKER_ENCRYPTION_MEMORY_RAW_KEY="$(./scripts/generate-jwe-key.sh)" \
  docker compose --env-file .env.compose -f docker-compose.yml up -d --build --wait --wait-timeout 600

這段會建立多個映像並下載建置相依套件，耗時與磁碟用量取決於電腦與快取。請在隔離的本機開發環境執行，先確認容器發布的連接埠不對其他機器開放。 開發代理會注入 X-Remote-User: dev@example.com，它是模擬身分，不是正式登入保護；Compose 的 port mapping 與主機防火牆必須一起檢查。

第二步「等資料備好」：執行下面的唯讀查詢，等結果出現 Local Research Agent。只有 health 成功，還不足以判定示範資料已建立。若失敗，先查同一份 Compose 設定的 logs，不要跳過初始化。

curl --fail-with-body http://localhost:14000/api/agents

第三步「分開兩次同意」：開啟 http://localhost:9002/，選 Login as Local Client。跳到同意介面後，勾選選用的 Identity Access，連接 Mock OAuth2 Service (Dev)，完成假供應商授權，再提交同意。這裡既建立服務連線，也建立 Agent 的委派；兩者要分開記。

第四步「看見換過的鑰匙」：回到 sample client，選 Call MCP Tool: whoami (allowed)。對照 Access Token Claims 與工具回傳的 JWT Claims：前者是 Agent 送出的身分資料，後者是 Mock MCP 收到的 provider claims。官方範例中，aud 由 token-exchange-broker 變為 mcp-server。

Claims 是 token 內的欄位；JWT 是可承載這些欄位的格式。讀得出欄位，與驗證簽章是兩個動作。 官方 Mock 的 decoder 用來觀察，Gateway 才負責這條示範路徑的 JWT 驗證。外部服務收到的 azp 也可能是 provider client，而非原 Agent UUID；要追責，還得保留交換側的使用者、Agent、resource 與關聯紀錄。

四、兩個假 Agent：先寫委託單，再做撤權對照

先在紙上設定 A「研究助理」與 B「排程助理」：兩者屬於同一個假使用者，接同一個 Mock 服務，grant ID 與 Agent UUID 各自不同。A 與 B 的 permission sets 可以不同；但第一輪應先選一個兩者都被允許的唯讀動作，讓撤權前有成功對照。這是接下來的驗收規格，並非已跑出的結果。

官方單 Agent 入門跑通後，開發者可依管理 Agent 與服務指南註冊第二個測試 Agent，設定其 permission sets、redirect URI 與 client 驗證方式，再用對應 client 完成同意。第二個瀏覽器分頁本身不會建立第二個 Agent；請從 admin API 核對 UUID，並分開保存兩個 client 的 token 狀態。

下面可查第一個 Agent 的 grant。AGENT_ID 是當前執行環境的實際 UUID，不是文章預先編好的固定值。這個請求走 3000 的開發代理；14000 列的是 Agent 設定，與使用者 grant 是兩個介面。

AGENT_ID=$(curl --fail --silent http://localhost:14000/api/agents \
  | jq -er '.[] | select(.display_name == "Local Research Agent") | .id')
curl --fail-with-body "http://localhost:3000/api/consent/agents/$AGENT_ID/grants"

記錄回應中的 grant ID、principal、agent_id、granted_permission_sets 與到期設定；在本文程式快照中，data 是一筆 grant 物件或 null，先核對結構再解析。接著給 B 做相同紀錄。保存識別資訊與結果即可，查核檔不要收錄可重用 token 原文。

• ① 撤權前：A、B 各送同一個允許的唯讀請求；確認兩者都真有到達 Mock。
• ② 只撤 A：在 A 的同意管理介面選 Revoke All Access，核對對話框中的 Agent 名稱；保留 B 的 grant 與共用服務連線。
• ③ 冷交換：讓 A 的請求確實重新抵達 Broker token endpoint，記錄拒絕；再讓 B 做同樣交換，檢查它仍有可用 grant 與 session。
• ④ 暖快取：保留撤權前的 Gateway 狀態再呼叫 A，記錄是否仍轉送；把它與冷交換結果分欄。

官方撤權測試案例包含「先成功交換、撤銷 grant、立即再交換收到拒絕」的斷言。這支持 Broker 端的驗收預期；它沒有替你的 Gateway 快取、多副本部署或外部服務量出端到端秒數。B 的完整對照仍應自行記錄，不能由 A 的測試通過代填。

五、最容易誤讀的撤權邊界：Broker、快取與 provider token

第一層是 Broker 的新交換。官方模型要求有效 grant；撤權後的新交換應被擋。若看到工具仍回資料，先查請求是否真的走到 Broker，而非立刻判定 grant 沒刪掉。

第二層是 ExtProc 的既有快取。官方快取設計以 subject token 與 resource 組合識別快取，各 sidecar 實例各自持有記憶體狀態。它降低交換負擔，也讓已交換憑證可能繼續被使用；撤掉 grant 與清掉所有實例的快取，是不同事件。

查閱快照的Compose sidecar 設定列出 cache.default_ttl: "5m" 與 cache.max_ttl: "1h"。這不等於撤權必定五分鐘或一小時生效。 官方 Gateway 指南說明，default TTL 用於交換回應缺少有效期時；實際還受回傳 lifetime、快取上限與暫時故障回退邏輯影響。測試時要保存實際設定與每次命中情況。

第三層是 外部服務已發出的 token。Zalando 的架構文章明確指出，grant 撤銷擋後續交換，無法因此撤銷已發出的 provider token。因此不要把這個按鈕當作外部服務端所有憑證的緊急失效機制；需要另核對該服務的撤銷能力、token 有效期，以及是否存在繞過 Gateway 的路徑。

驗收紀錄至少分五欄：撤權時間、Agent UUID、Broker 是否收到新交換、Gateway 是否命中快取、Mock 是否收到請求。要測冷交換，可在隔離測試中重啟 sidecar 清掉其記憶體快取，再用原 Agent token 重試；這會改變測試條件，務必另列一輪，不要和暖快取的自然傳播時間混算。

六、三個常見坑：同意範圍、工具動作與轉委派

坑一：把 permission set 當成下游一定縮小過的 token。 Broker 檢查 grant 後，回傳的是儲存的 provider credential。若那份服務 session 擁有更廣的 scopes，還要在工具執行路徑驗證實際可做的動作。官方 token exchange 模型另列 Broker CEL 與 ExtProc OPA 兩道政策門；不要因為交換成功，就把任意工具都算成允許。

坑二：想停 A，卻終止共用 session。 Grant 是每個使用者與 Agent 的關係，session 是每個使用者與服務的關係。終止後者會影響依賴它的 Agent；操作前先看受影響名單，並保留 B 的對照。這與Alter 多使用者授權教學的軸線不同：那篇比較不同使用者，這裡固定同一人、拆開不同 Agent。

坑三：從 token exchange 推論任意轉委派都已完成。 A 呼叫 B，再由 B 呼叫工具，需要另外定義 B 是替誰、依哪份同意、是否超出 A 原本權限，以及撤 A 會如何影響鏈條。RFC 能表達 actor 與 delegation，專案也有 impersonation 功能；對你的應用，仍要逐段檢查，而非將兩個 Agent 串起來就算驗收。

常見問題：八個先講答案的判斷

1. 這是在取代 OAuth 嗎？

不是。它使用 OAuth 與 Token Exchange，集中管理 Agent 委派、外部服務連線與交換路徑。

2. 需要真實 Google 或 GitHub 帳號嗎？

官方 Mock 入門不需要。先完成假身分、假供應商與 whoami 對照，再規劃真實服務整合。

3. 撤掉 A，B 一定繼續正常嗎？

要看 B 自己的 grant、session 與政策是否有效。設計上可分開撤 grant；請用 B 的成功對照證明你沒有誤斷共用連線。

4. JWT 的 exp 還沒到，grant 撤銷有用嗎？

有。Token 的格式與時間檢查通過，後續抵達 Broker 的交換仍須通過有效 grant 檢查；快取路徑則另測。

5. Revoke All Access 等於登出外部服務嗎？

不是。官方對話框與委派模型將 Agent grant 和服務 session 分開；要終止服務連線，請選對應的 session 操作。

6. whoami 回傳姓名，就是完整安全證明嗎？

不是。它幫你看見收到的 claims；簽章、audience、工具政策、旁路與快取仍各有驗收問題。

7. 這份教學能承諾幾秒完成撤權嗎？

不能。本文未量得端到端時間。你要固定版本、token lifetime、Gateway 設定與副本數，分開測新交換與暖快取。

8. 完成練習後如何收尾？

執行下面的 Compose down。官方開發環境使用記憶體儲存，Broker 停止後會失去示範 grant 與 provider sessions；下次需重新授權。

docker compose --env-file .env.compose -f docker-compose.yml down

給新手的三個重點

• 身分、委託單、鑰匙分開看：同一人可以授權多個 Agent，不代表每個 Agent 都要持有外部服務 token。
• 先有成功對照，再撤一份 grant：同時記錄 A 與 B，才能看出撤權是否隔離。
• 把「已撤銷」接到真正的執行結果：Broker 拒絕新交換、Gateway 停止轉送、服務拒絕舊 token，各自需要證據。