SSO 與 SCIM
說明透過公司帳號（IdP）登入與自動同步使用者的設定順序。
將公司使用的 IdP（Okta、Microsoft Entra ID、Google Workspace 等）連接到 Keural 後，員工即可使用公司帳號登入，並在首次登入時自動加入組織。
IdP 管理人員與開發人員的規格請參考 SSO·SCIM 串接規格。
準備事項
| 項目 | 原因 |
|---|---|
| Keural 組織的擁有者帳號 | 只有擁有者可以變更 SSO 設定。 |
| IdP 管理員權限 | 需要在 IdP 中建立 Keural 應用程式。 |
| 公司網域的 DNS 管理權限 | 以 TXT 記錄驗證網域所有權。 |
支援的方式
| 方式 | 用途 |
|---|---|
| OpenID Connect（OIDC） | 以公司帳號登入 |
| SAML 2.0 | 以公司帳號登入。驗證請求採用 Redirect，回應以 HTTP-POST 接收。 |
| SCIM 2.0 | 在 IdP 中新增或停用使用者時，會自動同步到 Keural 帳號 |
OIDC 與 SAML 擇一即可。若 IdP 兩者都支援，建議選擇設定較簡單的 OIDC。
設定順序
所有設定都在 組織管理 → SSO 設定 中進行。
1. 驗證公司網域
請先驗證用於 SSO 的電子郵件網域的所有權。未驗證的網域在第 3 步無法儲存。
在 組織網域 中輸入公司網域（例如 acme.com），然後按下 新增網域。
在清單中該網域的列上，按下 驗證。驗證網域 視窗會顯示 TXT 記錄值（keural-verify=…）。複製該值。
在 DNS 管理畫面中，為該網域新增一筆 TXT 記錄，並貼上複製的值。主機（名稱）為網域本身（通常為 @）。
回到 Keural，按下 確認驗證。出現 已驗證 即完成。DNS 生效可能需要數十分鐘，失敗時請稍後再按一次。
若有多個公司網域，請分別新增並驗證。gmail.com 等公開電子郵件網域無法使用。
2. 在 IdP 中建立應用程式
在 SSO 設定 最上方的 通訊協定 中選擇 OpenID Connect (OIDC) 或 SAML 2.0，即會顯示需在 IdP 中登錄的 Keural 值。將這些值輸入 IdP 應用程式，並複製 IdP 發行的值備用。
| 方向 | 項目 | 內容 |
|---|---|---|
| Keural → IdP | 回呼 URI | 填入 IdP 應用程式的重新導向 URI。 |
| IdP → Keural | Issuer URL | IdP 的發行者位址。 |
| IdP → Keural | Client ID · Client Secret | 建立 IdP 應用程式後發行的值。 |
IdP 需傳送使用者的電子郵件，才能完成登入。
| IdP | 建立位置 | 填入回呼 URI 的位置 | Issuer URL |
|---|---|---|---|
| Okta | Applications → Create App Integration → OIDC · Web Application | Sign-in redirect URIs | https://<Okta 網域> |
| Microsoft Entra ID | App registrations → New registration | Redirect URI（Web） | https://login.microsoftonline.com/<租用戶 ID>/v2.0 |
| Google Workspace | Google Cloud 主控台 → API 和服務 → 憑證 → OAuth 用戶端 ID（網路應用程式） | 已授權的重新導向 URI | https://accounts.google.com |
- Microsoft Entra ID：Client Secret 是在 Certificates & secrets 中新建的密鑰值（Value）。在 Token configuration 中，為 ID 權杖新增
email選用宣告。 - Okta：在應用程式的 Assignments 中，指定可使用 Keural 的使用者或群組。
3. 在 Keural 中輸入值並儲存
- 輸入第 2 步從 IdP 取得的值。
- 在 電子郵件網域 中，以逗號分隔輸入第 1 步驗證過的網域。使用該網域的電子郵件登入時，會前往公司登入畫面。
- 設定 首次登入時自動建立使用者（JIT）。開啟後，尚無 Keural 帳號的員工在首次透過 SSO 登入時會自動建立帳號。關閉後，只有已有帳號的人可以登入。
- 按下 儲存。
使用 OIDC 且 IdP 未提供標準位址（discovery）時，請在 開啟進階設定 中直接輸入端點。大多數 IdP 留空即可。
4. 開啟 SSO 並測試登入
- 開啟 啟用 SSO，然後按下 儲存。
- 按下 測試登入。新視窗中會開啟公司登入畫面。
- 以公司帳號登入並回到 Keural，即表示連接完成。
測試登入只有在 SSO 開啟時才能運作。若有問題，請關閉 啟用 SSO 並儲存。在此期間，該網域的員工將以電子郵件連結登入。
員工登入
- 在 Keural 登入畫面輸入公司電子郵件，會前往公司登入畫面。登入後會回到 Keural。
- 在桌面 App 中，請以電子郵件連結登入，而非公司登入畫面。
- 首次透過 SSO 登入的員工，會以 成員 身分加入組織。管理員角色請在組織管理中另行指定。
在以下情況下，雖然可以登入，但不會自動加入組織。
- 組織購買的席次已全部用完。
- 該帳號已屬於其他組織。
5. 連接 SCIM（選用）
連接 SCIM 後，在 IdP 中新增或停用使用者時，會立即反映到 Keural 帳號。SSO 連接完成後再進行設定。
在 SCIM 佈建 中，開啟 啟用 SCIM 佈建。
按下 發行權杖，並複製權杖。權杖只會在此時顯示一次。
在 IdP 的佈建設定中，填入 SCIM Base URL（Tenant URL）與權杖。驗證方式為 Bearer 權杖。
| IdP | 輸入位置 |
|---|---|
| Okta | 應用程式 → Provisioning → SCIM connector base URL。Authentication Mode 選擇 HTTP Header |
| Microsoft Entra ID | Enterprise application → Provisioning → Automatic → Tenant URL · Secret Token |
IdP 中的操作會以下列方式反映到 Keural。
| 在 IdP 中 | 在 Keural 中 |
|---|---|
| 指派使用者 | 建立帳號並加入組織。使用者名稱為電子郵件。 |
| 停用使用者或取消指派 | 暫停帳號，阻擋登入。不會刪除資料。 |
| 重新啟用 | 解除暫停。 |
| 加入或移出 Keural Admins 群組 | 升為管理員或降為成員。擁有者不會改變。 |
若遺失權杖，請按下 重新發行權杖，並將新權杖輸入 IdP。原有權杖會立即失效。
疑難排解
| 症狀 | 處理方式 |
|---|---|
| 無法儲存電子郵件網域 | 確認已完成第 1 步的網域驗證，且該網域不是公開電子郵件網域。 |
| 網域驗證失敗 | 確認 TXT 值已從 keural-verify= 完整填入，等待 DNS 生效後再按一次。 |
| 按下測試登入後，公司登入畫面沒有開啟 | 確認已開啟 啟用 SSO 並已儲存。 |
| 公司登入後回到 Keural 登入畫面 | OIDC 請重新確認回呼 URI、Issuer URL、Client Secret 與電子郵件宣告；SAML 請重新確認 SP EntityID、ACS URL、憑證與電子郵件屬性。 |
| 提示沒有帳號而拒絕登入 | 首次登入時自動建立使用者（JIT）已關閉。請開啟，或先邀請該員工。 |
| 可以登入，但看不到組織工作區 | 確認是否仍有剩餘席次，以及該帳號是否已屬於其他組織。 |
| 從 IdP 入口網站點選應用程式後登入失敗（SAML） | 請從 Keural 登入畫面，以公司電子郵件開始登入。 |
| SCIM 連線測試失敗 | 重新填入 Base URL 與權杖。若已重新發行權杖，請改用新權杖。 |