OIDC接入需求規範書模板

YourBizUnit 平臺用戶登入時，必須透過鴻海集團統一的單點登入（SSO）系統 —— 中央授權中心（域名為 sso.foxconn.com，以下簡稱「授權中心」）完成身份驗證，並遵循以下規範：

1. 使用專屬 OIDC 客戶端：必須使用授權中心註冊之 YourBizUnit 平臺專屬 OIDC 客戶端進行整合。
2. 開發前閱讀技術文件：整合開發前，須詳細閱讀《中央授權中心 OIDC 支援說明》，網址為：https://sso.foxconn.com/Developer/Document/OIDC。
3. 授權類型選擇：應使用「授權碼模式（authorization code）」（[點擊查看流程圖]）或「客戶端模式」（僅限於集團內部 API 資源調用場景）。
4. 身份識別建議方式：建議採用 Access Token 搭配 UserInfo 端點查詢用戶資訊的方式進行身份識別，不建議僅依賴 ID Token。
5. 跨系統 API 調用規範：YourBizUnit 平臺與集團其他平臺／系統之間進行 Web API 調用時，應以 Access Token 控制存取權限，並應設定合理的 API Scope 以限制存取範圍。API Scope命名為服務提供方的Client ID開頭，例如：
   Client ID: YourBizUnit

   API Resource: YourBizUnit.Manage
   API Scope: YourBizUnit.Manage.View、YourBizUnit.Manage.New、YourBizUnit.Manage.Update
   
   Client ID: civet

   API Resource: civet.api
   API Scope: civet.api.msg、civet.api.broadcast、civet.api.subscribe
   
6. Access Token 有效期與刷新機制：帶有用戶資訊的 Access Token 不提供 Refresh Token 功能，若需再次取得，須重新發起授權流程。
7. Access Token 保管安全：Access Token 屬於敏感憑證，嚴禁在前端（例如：JavaScript、localStorage、URL 參數等）中暴露或傳輸，應僅於後端安全保存與使用，以防止憑證遭攔截或濫用。
8. Redirect URI 管控：所有授權流程的 Redirect URI 必須事先於授權中心註冊，且強烈建議使用 HTTPS，防止中間人攻擊。禁止使用 localhost、IP 位址或萬用字元作為正式環境的回調地址。
9. 狀態參數（state）的使用建議：為防範 CSRF 攻擊，建議在授權請求中使用 state 參數，並於回傳階段驗證其一致性。建議對 state 值進行加密或簽章處理，避免被竄改或重放。
10. 錯誤處理與日誌：整合時應妥善處理授權失敗情況（如 code 無效、scope 錯誤、token 過期等），並將關鍵錯誤記錄於後端日誌，便於問題追蹤與稽核。
11. Session 與 Access Token 關係：Access Token 僅用於 API 訪問權杖，請避免將其用作 Web Session 憑證。建議於後端根據 token 對應的使用者資訊建立獨立 session 管理。
12. 二次驗證建議：為強化安全性，建議 YourBizUnit 平臺於適當情境下啟用用戶的二次驗證功能，並可依需求設計為選擇性（即：請求授權端點時添加參數 login_type=2fa）或強制性執行（即：設定客戶端強行開啟雙因子驗證）。