跳至主要内容

使用 IDExpert Cloud 串接 Nextcloud SAML

本文件說明如何透過 SAML 2.0 協定，整合 IDExpert Cloud 與 Nextcloud 進行單一登入 (SSO)。

1. 前置準備

在開始設定前，請確認滿足以下條件：

1.1 系統需求

  • Nextcloud 版本：建議使用 Nextcloud 20 或更新版本
  • 帳號權限：
    • 需擁有 Nextcloud 管理員權限
    • 需擁有 IDExpert Cloud 系統管理員（Admin）或系統負責人（Root）權限
  • 插件需求：
    • Nextcloud 需安裝 SSO & SAML authentication 插件

建議作法：

  1. 先在 Nextcloud 中建立使用者帳號
  2. 在 IDExpert Cloud 中建立相同帳號名稱的使用者
  3. 或使用 LDAP/AD 統一管理雙方使用者帳號

2. Nextcloud 前置設定

2.1 安裝 SAML 插件

  1. 以管理員身分登入 Nextcloud

  2. 點擊右上角使用者圖示，選擇 應用程式

  3. 在應用程式頁面中：

    • 點擊搜尋圖示或按下快捷鍵 Ctrl + F
    • 搜尋 SSO & SAML authentication
    • 找到插件後點擊 啟用

  4. 等待插件安裝完成

如果無法找到此插件，請確認：

  • Nextcloud 版本是否支援此插件
  • 是否有網路連線可存取應用程式商店
  • 管理員帳號是否有安裝插件的權限

2.2 取得 Nextcloud SAML 資訊

安裝完成後，記錄以下資訊供 IDExpert Cloud 設定使用：

  • ACS URL：https://your-nextcloud-domain/apps/user_saml/acs
  • Entity ID：https://your-nextcloud-domain/apps/user_saml/saml/metadata

請將 your-nextcloud-domain 替換為您實際的 Nextcloud 網域名稱。

範例：

  • 如果 Nextcloud 網址是 https://cloud.example.com
  • ACS URL 為：https://cloud.example.com/apps/user_saml/acs
  • Entity ID 為：https://cloud.example.com/apps/user_saml/saml/metadata

3. IDExpert Cloud 設定

3.1 建立 SAML 應用程式

  1. 登入 IDExpert Cloud 管理控制台

  2. 前往 應用程式 > 建立應用程式

  3. 選擇 SAML 類型：

    • 可搜尋是否有 Nextcloud 範本
    • 若無範本，選擇 自定義 SAML 應用程式

  4. 填寫基本資訊：

    • 應用程式名稱：例如「Nextcloud」
    • 圖示：（可選）上傳 Nextcloud 圖示或使用預設圖示

  5. Service Provider 設定：

    欄位設定值說明
    ACS URLhttps://your-nextcloud-domain/apps/user_saml/acs替換為實際 Nextcloud 網址
    Entity IDhttps://your-nextcloud-domain/apps/user_saml/saml/metadata替換為實際 Nextcloud 網址
    Name ID 格式Unspecified 或 Email建議使用 Unspecified
    簽章項目只簽 Assertion必須選擇此選項
    簽章演算法SHA-1Nextcloud 預設支援 SHA-1

  6. 使用者屬性對應：

    • 屬性名稱：UID
    • 屬性值：user:uid（使用者的帳號名稱）

    UID 屬性必須正確設定，否則 Nextcloud 無法識別登入的使用者。

  7. SSO Portal 設定：

    • 若需要將此應用程式顯示在使用者 SSO 入口網站，請勾選此選項

  8. 點擊 建立 並進入 建立結果 頁面

3.2 取得 IdP 資訊

建立完成後，請記錄以下資訊供 Nextcloud 設定使用：

  1. 身分提供者登入 URL（SSO URL）：

    • 格式：https://your-idexpert-domain/SAMLServlet/saml
    • 請複製完整的 URL

  2. 身分提供者登出 URL（SLO URL）：

    • 通常與登入 URL 相同
    • 格式：https://your-idexpert-domain/SAMLServlet/saml

  3. 發行者（Issuer）：

    • 此為 IDExpert Cloud 的唯一識別碼
    • 格式：https://your-idexpert-domain/SAMLServlet/saml

  4. X.509 憑證：

    • 點擊 下載憑證 按鈕下載憑證檔案
    • 或複製憑證內容（需包含完整的 BEGIN 和 END 標記）

3.3 設定存取政策

  1. 前往 政策 > 設定政策

  2. 建立或選擇一條存取政策

  3. 將需要存取 Nextcloud 的 使用者群組 加入政策中

  4. 設定適當的驗證方式（密碼、多因素驗證等）

  5. 儲存政策設定

4. Nextcloud SAML 設定

4.1 進入 SAML 設定頁面

  1. 以管理員身分登入 Nextcloud

  2. 點擊右上角使用者圖示，選擇 設定

  3. 在左側選單中找到並點擊 SSO & SAML authentication

  4. 選擇 Use built-in SAML authentication

    如果您的環境有其他身分驗證後端（如 LDAP），可以勾選 "Allow the use of multiple user back-ends" 以同時支援多種登入方式。

4.2 設定身分提供者資訊

在 Identity Provider 的自定義名稱 區域：

  1. 識別碼名稱：輸入 IDExpert 或其他易於識別的名稱

  2. 在 服務提供者 (Service Provider) 資料 區域：

    • 展開 "Show Service Provider settings..."
    • 確認 Nextcloud 自動產生的 Entity ID 和 ACS URL 正確

  3. 在 身分提供者 (IdP) 資料 區域設定以下資訊：

    Nextcloud 欄位設定值來源
    IDExpert SAML 識別名稱供應者端點https://your-idexpert-domain/SAMLServlet/saml從 IDExpert Cloud 複製的 SSO URL
    IDExpert SAML 識別名稱提供者實體 IDhttps://your-idexpert-domain/SAMLServlet/saml從 IDExpert Cloud 複製的 Issuer
    IDExpert SAML 登出端點 URLhttps://your-idexpert-domain/SAMLServlet/saml從 IDExpert Cloud 複製的 SLO URL（通常與 SSO URL 相同）
    IDExpert SAML 憑證貼上完整的 X.509 憑證內容從 IDExpert Cloud 下載的憑證
    • 必須包含 -----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE-----
    • 憑證內容需要完整且不能有格式錯誤
    • 可以使用文字編輯器開啟 .cer 或 .pem 檔案複製完整內容

4.3 設定屬性對應

在 Attribute mapping 區域：

系統預設的屬性對應通常已經足夠，但您可以根據需求調整：

  • UID：用於識別使用者的唯一屬性（通常保持預設即可）
  • Display Name：使用者顯示名稱（可選）
  • Email：電子郵件地址（可選）

IDExpert Cloud 在 SAML Response 中會傳送 UID 屬性，Nextcloud 將使用此屬性來識別使用者。

4.4 全域設定（選用）

在 Global settings 區域，根據需求勾選：

  • Allow the use of multiple user back-ends (e.g. LDAP)

    • 若需要同時支援 SAML 和其他登入方式（如密碼登入或 LDAP），請勾選此選項
    • 測試期間建議勾選，以便管理員可以使用密碼登入

  • Only allow authentication if an account exists on some other backend (e.g. LDAP)

    • 僅當使用者在其他後端（如 LDAP）已存在時才允許 SAML 登入

  • Use SAML auth for the Nextcloud desktop clients (requires user re-authentication)

    • 若需要桌面客戶端也使用 SAML 驗證，請勾選

在測試階段，建議勾選 "Allow the use of multiple user back-ends"，這樣即使 SAML 設定有誤，管理員仍可使用原生密碼登入修正設定。確認 SSO 正常運作後，可考慮取消勾選以強制使用 SAML 登入。

4.5 安全性設定（選用）

在 Security settings 區域，可以根據安全需求勾選：

  • Indicates that the nameID of the [samlp:logoutRequest] sent by this SP will be encrypted
  • Indicates whether the [samlp:AuthnRequest] messages sent by this SP will be signed
  • Indicates whether the [samlp:logoutRequest] messages sent by this SP will be signed
  • Indicates whether the [samlp:logoutResponse] messages sent by this SP will be signed
  • Whether the metadata should be signed

這些安全選項可以增強 SAML 通訊的安全性，但需要 IDExpert Cloud 支援相應的功能。一般情況下使用預設設定即可。

4.6 儲存設定

完成所有設定後，滾動到頁面底部確認設定無誤，系統會自動儲存變更。

5. 測試驗證

5.1 從 Nextcloud 登入頁面測試

  1. 登出當前帳號（如已登入）

  2. 前往 Nextcloud 登入頁面

  3. 在登入頁面應該會看到新的登入選項：

    • 原生的帳號密碼登入欄位（若啟用多重後端）
    • IDExpert 按鈕（或您設定的識別碼名稱）

  4. 點擊 IDExpert 按鈕

  5. 系統會自動導向 IDExpert Cloud 登入頁面

  6. 輸入 IDExpert Cloud 使用者帳號和密碼

  7. 完成 IDExpert Cloud 的多因素驗證（如有設定）

  8. 驗證成功後，應自動導回 Nextcloud 並完成登入

如果登入後顯示錯誤或無法識別使用者：

  • 確認 IDExpert Cloud 和 Nextcloud 的使用者帳號名稱完全一致
  • 檢查 UID 屬性對應設定是否正確
  • 查看 Nextcloud 日誌檔案了解詳細錯誤訊息

5.2 從 IDExpert Cloud SSO 入口測試

若您在 IDExpert Cloud 中啟用了 SSO Portal：

  1. 登入 IDExpert Cloud 使用者入口網站

  2. 在應用程式清單中找到 Nextcloud 圖示並點擊

  3. 系統應自動完成身分驗證並導向 Nextcloud

  4. 確認能成功登入並存取檔案

6. 疑難排解

常見問題

Q1: 點擊 IDExpert 按鈕後顯示 404 錯誤

原因：IDExpert Cloud 的 SSO URL 設定錯誤

解決方式：

  • 確認 IDExpert Cloud 應用程式中的 ACS URL 正確
  • 檢查 Nextcloud 中設定的 IDExpert SAML 端點 URL 是否正確
  • 確認網址中沒有多餘的空格或特殊字元

Q2: 驗證成功但顯示「無法找到使用者」

原因：使用者帳號不匹配或 UID 屬性設定錯誤

解決方式：

  • 確認 Nextcloud 中是否存在該使用者帳號
  • 檢查 IDExpert Cloud 和 Nextcloud 的帳號名稱是否完全一致（區分大小寫）
  • 確認 IDExpert Cloud 應用程式中的 UID 屬性對應設定為 user:uid
  • 在 Nextcloud 使用者管理中預先建立對應的使用者帳號

Q3: 憑證驗證失敗

原因：憑證格式錯誤或憑證內容不完整

解決方式：

  • 確認憑證包含完整的 BEGIN 和 END 標記
  • 檢查憑證內容沒有被截斷或包含額外字元
  • 重新從 IDExpert Cloud 下載憑證並完整複製
  • 確認使用的是正確的憑證（不是私鑰）

Q4: 無法顯示 IDExpert 登入按鈕

原因：SAML 插件未正確安裝或設定未生效

解決方式：

  • 確認 SSO & SAML authentication 插件已啟用
  • 檢查是否選擇了 "Use built-in SAML authentication"
  • 確認身分提供者資訊已完整填寫並儲存
  • 嘗試清除瀏覽器快取或使用無痕模式測試

Q5: 登入後權限不正確

原因：Nextcloud 使用者權限與 SAML 使用者權限不一致

解決方式：

  • 在 Nextcloud 使用者管理中檢查該使用者的群組和權限設定
  • SAML 驗證只負責身分認證，權限需在 Nextcloud 中單獨設定
  • 確認使用者被分配到正確的 Nextcloud 群組

Q6: 測試時管理員帳號被鎖定

原因：未啟用多重後端，且 SAML 設定錯誤

解決方式：

  • 使用 Nextcloud 的 occ 命令列工具重設管理員密碼
  • 修改 Nextcloud 設定檔暫時停用 SAML
  • 預防措施：測試期間務必勾選 "Allow the use of multiple user back-ends"

日誌檢查

如果遇到問題，可以查看以下日誌：

Nextcloud 日誌

  1. 以管理員身分登入 Nextcloud
  2. 前往 設定 > 管理 > 日誌
  3. 查找與 SAML 相關的錯誤訊息

IDExpert Cloud 日誌

  1. 登入 IDExpert Cloud 管理控制台
  2. 前往 日誌 > 驗證記錄 或 操作記錄
  3. 查找對應時間的驗證嘗試記錄

7. 進階設定

7.1 自動佈建使用者（Auto-provisioning）

Nextcloud 的 SAML 插件支援自動建立使用者帳號。若要啟用：

  1. 在 Nextcloud SAML 設定中確認屬性對應正確
  2. 首次透過 SAML 登入時，系統會自動建立使用者帳號
  3. 使用者資訊將根據 SAML Response 中的屬性自動填入

自動佈建的使用者會使用預設權限。建議管理員定期檢查並調整新使用者的群組和權限。

7.2 群組對應

如果需要根據 IDExpert Cloud 的群組自動分配 Nextcloud 群組：

  1. 在 IDExpert Cloud 應用程式設定中新增群組屬性：

    • 屬性名稱：groups
    • 屬性值：user:groups

  2. 在 Nextcloud SAML 設定的 Attribute mapping 中設定：

    • Group 欄位設為對應的屬性名稱

  3. 設定群組對應規則（需參考 Nextcloud 文件）

7.3 強制使用 SAML 登入

確認 SAML SSO 完全正常運作後，可以強制所有使用者使用 SAML 登入：

  1. 在 Nextcloud SAML 設定的 Global settings 區域
  2. 取消勾選 "Allow the use of multiple user back-ends"
  3. 這將隱藏原生的帳號密碼登入選項

執行此步驟前，請確保：

  • SAML SSO 已完整測試且運作正常
  • 至少保留一個管理員帳號可以透過其他方式登入（如直接資料庫修改）
  • 已備份 Nextcloud 設定檔案

8. 參考資源

Nextcloud 官方文件

IDExpert Cloud 相關文件

SAML 技術規範

9. 附錄

9.1 快速參考表

URL 格式參考

項目格式範例
Nextcloud ACS URLhttps://{domain}/apps/user_saml/acshttps://cloud.example.com/apps/user_saml/acs
Nextcloud Entity IDhttps://{domain}/apps/user_saml/saml/metadatahttps://cloud.example.com/apps/user_saml/saml/metadata
IDExpert SSO URLhttps://{domain}/SAMLServlet/samlhttps://idp.example.com/SAMLServlet/saml
IDExpert Issuerhttps://{domain}/SAMLServlet/samlhttps://idp.example.com/SAMLServlet/saml

SAML 參數對照表

IDExpert CloudNextcloud設定值
ACS URLService Provider ACS URLNextcloud 的 /apps/user_saml/acs 端點
Entity IDService Provider Entity IDNextcloud 的 metadata 端點
Name ID 格式-Unspecified 或 Email
簽章項目-只簽 Assertion
簽章演算法-SHA-1
屬性：UIDAttribute mapping: UIDuser:uid