Anthropic 在 Claude Code 2.1.312 發行紀錄中，新增 Claude apps gateway 的 oidc.user_id_claim，讓閘道可用 ID token（身分識別權杖）裡 sub 以外的欄位辨識使用者，並以 Microsoft Entra ID 的 oid 為例。這是閘道身分對接的調整，不代表登入成功後角色與權限就會自動同步。
組織升級時要先確認一件事：既有存取政策拿哪個欄位對應員工，而身分提供者目前送來的 token 又包含什麼 claim（聲明欄位）？若兩邊使用不同識別值，登入仍可能成功，使用者映射、稽核紀錄或政策判斷卻接不上。這次變更與一般版本升級檢查不同，涉及帳號識別與權限流程；可參考Claude Code 升級時檢查權限規則的方法，把登入、辨識與授權分開驗收。
一、Claude Code 2.1.312 改了哪一段閘道身分流程？
新增的 oidc.user_id_claim 讓 Claude apps gateway 可選用 ID token 中 sub 以外的 claim 作為使用者識別依據；發行紀錄舉出的例子是 Microsoft Entra ID 的 oid。
這項更新的真實案例，是 Anthropic 在 2.1.312 發行紀錄列出新欄位的用途：當現有閘道使用的 sub 不符合組織既有的帳號對應方式時，可指定另一個 token 欄位供閘道辨識登入者。這回答的是「用哪個值找出使用者」，還沒有回答「使用者可以做什麼」。後一題仍由組織既有的角色、群組、政策與整合設定決定。
目前可確認的公開資訊止於欄位名稱、用途與 oid 範例。發行紀錄沒有列出設定檔位置、格式、預設值、支援版本條件或部署限制，因此不應照著猜測寫出設定片段。實際操作前需查閱所用 gateway 版本的正式設定文件；若文件未涵蓋這個欄位，先在測試環境確認，不要把範例名稱當成已驗證的設定語法。
二、先確認既有存取控管依賴哪個使用者識別
登入驗證確認帳號通過身分提供者檢查；閘道識別決定這個登入者對應哪筆使用者資料；授權才依角色或政策決定可存取的功能。三者串接失敗時，不能只看登入頁是否成功。
實務上常見的第一個卡點，是閘道讀到的值與政策資料庫使用的鍵不一致。例如既有系統以目錄物件 ID 綁定員工，token 卻只提供另一種識別值；如果映射層沒有轉換規則，系統就無法穩定找到對應帳號。可能的結果包括找不到使用者、稽核紀錄分散在不同帳號，或錯把新舊帳號當成同一人。這些是整合檢查情境，發行紀錄本身沒有宣稱這次更新曾造成上述故障。
Microsoft 的文件提供了第二個具體案例：同一位使用者以兩個不同應用程式登入時，兩個應用程式取得的 sub 可以不同，oid 則相同。這使 oid 適合某些需要跨應用程式對應同一租戶使用者的情境；選用前仍要確認 token 是否包含它，以及組織的帳號目錄是否以相同範圍管理身分。若現有政策已能使用 sub 正確映射，沒有必要只為了改用 oid 而更動設定。
盤點時可從實際流程找答案：閘道收到哪個 issuer（發行者）的 token、目前用哪個 claim 建立使用者記錄、授權系統用哪個鍵查角色、日誌又以何值串起登入事件。若原本就依版本或擴充模組調整權限，先核對Claude Code 版本更新前後的檢查方式，再把本次新增欄位納入既有升級紀錄。
三、沿用 sub 或改用其他 claim，差異在哪裡？
先依身分提供者的保證、帳號映射範圍與政策需求選擇。sub 在 OIDC 中與 iss（發行者）合用，是規格保證穩定且唯一的識別組合；Microsoft Entra ID 的 oid 可在同一租戶的不同應用程式間識別同一使用者，email 則可能變更或重複，不宜當授權依據。
OIDC Core 規格說明，sub 在單一發行者範圍內對特定使用者維持唯一且不重新分配；要識別使用者，可靠的組合是 iss 加 sub。規格也允許成對識別碼（pairwise subject）：同一使用者在不同應用程式可得到不同 sub，以降低服務之間互相追蹤的可能。這是第三個案例：兩個應用程式看到不同識別值，可能是身分提供者依隱私設計產生的預期結果，未必代表帳號錯亂。
Microsoft Entra ID 的案例呈現另一種取捨。其文件指出，oid 在不同應用程式登入同一租戶使用者時一致，但同一個人若存在於多個租戶，各租戶會有不同的物件 ID。跨租戶系統因此還得核對 tid（租戶識別碼）與組織定義的帳號範圍，不能把不同租戶中的相同自然人逕自合併。這項設計也有安全意義：租戶間帳號與權限應各自管理，訪客身分不應無條件沿用原租戶權限。
email、preferred_username 或顯示名稱方便人閱讀，卻可能變更，也可能在帳號生命週期中被重複使用。Microsoft 明確提醒，不要將這些可讀欄位當作授權決策或唯一使用者鍵。選擇識別值前，先寫清楚系統需要的是「同一個應用程式內穩定識別」、「跨應用程式關聯」，還是「不同租戶之間隔離」；再以實際 token 和身分提供者文件確認欄位能否滿足需求。
| 欄位 | 適合用來回答的問題 | 設計時要留意 |
|---|---|---|
iss + sub | 此發行者發出的 token 對應哪位使用者？ | sub 可能採應用程式專屬的成對識別；跨應用程式映射需先確認策略 |
oid | 同一 Entra 租戶內，不同應用程式的登入是否屬於同一目錄物件？ | 多租戶仍須納入 tid 與租戶政策 |
email、名稱或帳號 | 使用者如何被人辨認或聯絡？ | 值可能變更或重複，不宜當作唯一授權鍵 |
「唯一能保證識別特定使用者的組合，是發行者 iss 與主體 sub。」（譯）（OpenID Connect Core 1.0，§5.7）
四、部署前如何設定並驗收使用者識別？
先確認所用版本的正式設定格式，再用測試帳號核對 ID token 是否含有指定 claim、其值能否映射到既有使用者，最後測試允許與拒絕兩種存取結果及稽核紀錄。
目前發行紀錄未提供可直接照抄的設定位置或完整語法。管理者需從 Claude apps gateway 對應版本的文件確認設定層級、欄位格式、重新載入方式與相容條件；若找不到正式說明，先向供應商文件或支援管道確認。不可只因欄位名稱看起來像設定鍵，就推定它應放在哪個檔案或環境變數。
- 確認版本與文件：記錄 Claude Code 與 gateway 的實際版本，找到該版本支援
oidc.user_id_claim的正式說明，確認設定位置、格式及套用方式。 - 檢查測試 token：使用測試帳號取得實際 ID token，在安全環境確認
iss、sub、欲指定的 claim 與tid是否存在。避免把完整 token 貼進工單或一般聊天紀錄。 - 核對使用者映射：將指定 claim 的值與目錄及政策系統中的既有使用者鍵比對，檢查新進、離職、訪客、改名及跨租戶帳號的處理方式。
- 驗證正反結果：分別測試應獲准與應被拒絕的帳號，確認功能存取符合政策；檢查日誌能否以預期識別值追溯事件，並確認拒絕原因可供管理者判讀。
- 記錄回復條件：保留原設定、變更內容、測試結果與回復步驟；若 claim 缺漏或映射錯誤，先回復已驗證設定，再查 token 發行與映射流程。
這份驗收能檢查欄位是否接通，但不代替安全審查。ID token 仍須由整合元件依規格驗證簽章、發行者、受眾與有效期限；選對使用者欄位也不會自動建立角色、群組或授權政策。若群組資料另由 token 提供，還要依身分提供者文件確認超量或未發出時的處理方式。
Microsoft Entra ID 文件提醒，email 與顯示名稱可能變動；跨服務共用同一租戶使用者識別時，應依需求一併考量 oid 與 tid。（Microsoft Learn，ID token claims reference）
oidc.user_id_claim指定的是閘道用哪個 token 欄位辨識使用者，不會自動替組織完成授權。- 是否改用
oid，取決於既有映射、應用程式範圍與租戶邊界；不要以 email 或顯示名稱當唯一權限鍵。 - 設定格式與位置以對應版本的正式文件為準；部署前用實際 token 驗證映射、允許／拒絕結果及日誌。
五、常見問題：升級後是否必須更改 OIDC 設定？
不一定。若既有 sub 已能穩定對應帳號與政策，先確認升級相容性即可；只有在閘道需要使用其他 claim、且正式文件確認設定方式後，才評估調整。
常見問題
Q1: oidc.user_id_claim 會同步角色或群組嗎？
發行紀錄只說明此欄位用來以 ID token claim 識別使用者。角色、群組與存取決策仍須檢查組織既有的政策整合。
Q2: Microsoft Entra ID 一定要改用 oid 嗎？
不一定。若 sub 與現有使用者資料已能正確映射，無須只為採用範例而更動。需要跨應用程式對應時，再依租戶、oid、tid 與組織政策評估。
Q3: 可以用 email 當 user_id_claim 嗎？
即使技術上可指定，也不宜只憑欄位可讀就當成唯一識別或授權鍵。Microsoft 文件指出 email 可能變更或不正確；應使用身分提供者保證穩定的欄位，並驗證帳號生命週期的映射。
Q4: 欄位不存在或登入後找不到帳號，先查什麼？
先在安全環境確認實際 ID token 是否含有指定 claim，再核對閘道設定格式、租戶與 issuer，以及該值是否對應既有使用者記錄。接著分別檢查授權政策與稽核日誌，避免把映射失敗誤判為登入失敗。
