管理員指南
自訂 OAuth 提供者
新增任何符合 OIDC 標準的自訂登入方式
除了內建的 OAuth 提供者外，Root 可以新增任何符合 OIDC 標準的自訂登入方式。使用 Root 帳號登入後，進入系統設定頁面（`/console/setting`），找到「自訂 OAuth」區域。Web 控制台與參考設計一致，正在串接中；目前示範資料與登入頁透過 localStorage 連動。
新增自訂 OAuth 提供者
自訂 OAuth 提供者
設定自訂 OAuth 提供者，支援 GitHub Enterprise、GitLab、Gitea、NextCloud、Keycloak、Casdoor 等相容 OAuth 2.0 / OpenID Connect 協定的身分提供者。 回呼 URL 格式：{網站位址}/oauth/{slug}
| 圖標 | 名稱 | Slug | 狀態 | Client ID | 操作 |
|---|---|---|---|---|---|
| 尚無自訂 OAuth 提供者 | |||||
系統設定底部「自訂 OAuth」區域示意：說明橫幅、新增按鈕與空列表
進入設定區域
Root 登入後進入 /console/setting ，捲動至頁面底部「自訂 OAuth 提供者」卡片。與 系統設定 其他 Tab 同屬 option / custom_oauth_provider 設定範疇。
新增提供者
點擊「+ 新增 OAuth 提供者」開啟表單，填寫名稱、Slug、Client ID/Secret 與 OAuth 端點。Slug 建立後不建議修改，否則需在 IdP 端同步更新回呼 URL。
回呼 URL 格式
在 IdP 應用程式設定中將 Redirect URI 設為：
{網站位址}/oauth/{slug}其中「網站位址」為系統設定中的 ServerAddress（如 https://ai.example.com），{slug} 與表單中 Slug 欄位一致。
提供者列表
| 欄 | 欄位 | 說明 |
|---|---|---|
| 圖標 | icon | 提供者 Logo URL 或圖標標識 |
| 名稱 | name | 登入按鈕顯示名稱，如「企業 GitLab」 |
| Slug | slug | 唯一標識，用於回呼路徑 `/oauth/{slug}` |
| 狀態 | enabled | 啟用後出現在登入/註冊頁第三方區域 |
| Client ID | client_id | 在 IdP 註冊應用程式後取得的用戶端 ID（列表中可遮蔽顯示） |
| 操作 | — | 編輯、啟用/停用、刪除 |
設定 Client ID / Secret
- 在 IdP（GitLab、Keycloak 等）建立 OAuth / OIDC 應用程式，記錄 Client ID 與 Client Secret。
- 將回呼 URL 設定為 `{ServerAddress}/oauth/{slug}`，slug 與 EasyAPI 中填寫的 Slug 完全一致。
- 在 EasyAPI 系統設定 → 自訂 OAuth →「新增 OAuth 提供者」填寫端點與 scopes；若提供 well_known 可簡化端點設定。
- 儲存後啟用（enabled=1）；僅 enabled 的提供者會出現在 `/login` 與 `/register` 底部第三方區域。
表單欄位說明
| 設定項 | 欄位 | 說明 |
|---|---|---|
| 名稱 | name | 必填；顯示在登入按鈕上 |
| Slug | slug | 必填；小寫英文，全域唯一，決定回呼 URL 路徑 |
| 圖標 | icon | 選填；圖標 URL |
| Client ID | client_id | OAuth 應用程式 Client ID |
| Client Secret | client_secret | OAuth 應用程式密鑰，儲存後不在列表中明文顯示 |
| 授權端點 | authorization_endpoint | OAuth authorize URL |
| Token 端點 | token_endpoint | OAuth token URL |
| 使用者資訊端點 | user_info_endpoint | 取得使用者 profile 的 API |
| Scopes | scopes | 預設 openid profile email，依 IdP 要求調整 |
| Well-Known | well_known | 選填；OIDC `.well-known/openid-configuration` 位址，可自動探索端點 |
| 使用者 ID 欄位 | user_id_field | 從 userinfo JSON 讀取唯一 ID 的鍵，預設 sub |
| 使用者名稱欄位 | username_field | 對應為系統 username，預設 preferred_username |
| 顯示名稱欄位 | display_name_field | 對應為 nickname，預設 name |
| 電子郵件欄位 | email_field | 對應為 email，預設 email |
| 授權樣式 | auth_style | 0=以參數傳遞 client_secret；1=以 Header 傳遞（部分 IdP 要求） |
| 存取策略 | access_policy | 選填 JSON；限制允許登入的使用者範圍 |
| 拒絕提示 | access_denied_message | 策略拒絕時向使用者顯示的文案 |
資料表 custom_oauth_provider 欄位與上述表單一一對應；slug 欄有唯一索引。
端點與 scopes
- 標準 OIDC：填寫
well_known後可自動解析 authorization / token / userinfo 端點 - 純 OAuth 2.0：需手動填寫 authorization_endpoint、token_endpoint、user_info_endpoint
- Scopes 範例：
openid profile email（OIDC）或read:user user:email（GitHub） - 內建 OAuth 路由：
GET /api/oauth/github、wechat等與自訂/oauth/{slug}並存，互不影響
測試 OAuth 回呼
- 登出目前帳號，開啟 `/login`，確認底部出現剛新增的 OAuth 按鈕。
- 點擊按鈕應跳轉至 IdP 授權頁；授權成功後回跳 `{網站位址}/oauth/{slug}` 並完成登入或註冊綁定。
- 在「個人設定 → 帳戶綁定」驗證第三方帳號是否已關聯。
- 若失敗，檢查 Client Secret、回呼 URL、scopes 及 userinfo 欄位對應是否與 IdP 回傳的 JSON 一致。
使用者端 OAuth 登入說明見 註冊與登入 文件中的「第三方 OAuth 登入」章節。