如何在 ownCloud Infinite Scale 中設定雙重認證

若要為 ownCloud Infinite Scale 登入啟用雙重認證 (2FA)，請在用於驗證使用者的 OpenID Connect 身分提供者 (IDP) 中進行設定。對於許多部署而言，這意味著在 Keycloak 中啟用基於時間的一次性密碼 (TOTP)，然後要求使用者在完成登入之前進行註冊。 Infinite Scale 本身不提供通用的 TOTP 註冊介面。其內建的 IDP 功能有限；ownCloud 建議使用外部 OpenID Connect 提供者來滿足更廣泛的身份驗證需求，並且其文件指出 2FA 應使用 Keycloak。

假設範例： Northstar Design 是一家虛構的 40 人公司，其 ownCloud Infinite Scale 已連接到名為 `<realm_name>` 的 Keycloak 網域files。員工目前使用密碼登入。管理員希望他們註冊一個身份驗證器應用，並在下次身份驗證時使用驗證碼。此範例僅供參考，並非實際安裝或測試報告。以下步驟假設 Keycloak 已是 Infinite Scale 使用的身分識別提供者 (IDP)；如果不是，請先依照官方部署指南連線這兩個服務。

本指南中的介面圖片僅為概念範例，並非實際 Northstar 或 ownCloud 系統的螢幕截圖。不同 Keycloak 版本的選單措詞和佈局可能有所不同。本指南已於 2026 年 10 月 6 日對照 ownCloud Infinite Scale 8.2 文件和 Keycloak 伺服器管理指南 26.8 進行核對。

範例配置螢幕，包含 ownCloud OIDC 頒發者和用戶端 ID，隨後從雲端站點重定向到 Keycloak 進行登入。 — 對於這個虛構的設置，Infinite Scale 會將使用者傳送到已配置的 Keycloak 發行者；特定的 OIDC 設定取決於現有的部署。

在無限擴展部署中，雙重認證 (2FA) 會帶來哪些變化

OpenID Connect (OIDC) 是一種登入協議，它允許 Infinite Scale 依賴身分提供者 (IDP) 而不是自行驗證每個密碼。 Keycloak 會請求主憑證，並在其身分驗證流程需要時請求第二因素，例如 TOTP。 Infinite Scale 隨後會接收 OIDC 驗證結果。 TOTP 是一個由共用金鑰和目前時間產生的短有效代碼；身份驗證器應用程式會在使用者掃描註冊二維碼時儲存該金鑰。

這種區分至關重要。在 Keycloak 中設定 OTP 策略會改變 Keycloak 對使用者進行身份驗證的方式。設定 ownCloud MFA 選項不會註冊手機或建立 TOTP 憑證。具體來說，ownCloud 選項OCIS_MFA_ENABLED用於在特定受保護路由上進行增強身份驗證，前提是身份提供者 (IDP) 支援 OpenID Connect 身份驗證上下文類別引用 (ACR) 聲明。它並非一個會在每次登入時都會加入通用 TOTP 提示的開關。

在改變領域之前

確認生產環境中的 Infinite Scale 用戶端實際使用的身分提供者 (IDP) 和網域。請將 OIDC 頒發者和用戶端 ID 與部署配置進行比較，而不是僅憑瀏覽器網址列中的資訊進行猜測。
為正確的 Keycloak 領域設定管理員帳戶，為每個使用者設定受支援的身份驗證器應用程序，並為遺失裝置的使用者制定恢復流程。
檢查 Keycloak 登入頁面和 Infinite Scale 是否可透過 HTTPS 訪問，並具有有效的憑證。在進行身份驗證變更時，請保持現有管理員會話處於開啟狀態，並先使用非管理員帳戶進行測試。
清點所有登入路徑。瀏覽器流程控制基於瀏覽器的 OIDC 驗證；API 憑證、服務帳戶、應用程式密碼或其他驗證流程可能單獨管理。

1. 確認無限尺度使用了鑰石隱形

在 Northstar 範例中，管理員確認 Web 用戶端已重新導向至指定files網域。 ownCloud 部署範例在其 Keycloak 設定中https://login.example.test/realms/files使用了諸如OCIS_OIDC_ISSUER`<domain>`、 `<domain>` 和 `<domain>` 之類的設定。這些是部署配置值，而不是普通使用者在 Infinite Scale Web 介面中可以變更的欄位。WEB_OIDC_CLIENT_IDPROXY_OIDC_REWRITE_WELLKNOWN

如果您的執行個體仍使用嵌入式身分識別提供者 (IDP)，請在強制執行一次性密碼 (OTP) 之前單獨規劃 Keycloak 整合。連接外部 IDP 不僅僅是輸入頒發者 URL：它還涉及客戶端註冊、重定向和 Web 來源配置、令牌聲明、HTTPS，並且所使用的桌面或行動用戶端都需要達成協議。您可以參考 ownCloud 維護的 Keycloak 部署範例，並根據您的特定版本和拓撲結構進行配置。

2. 在 Keycloak 中選擇基於時間的 OTP 策略

在 Keycloak 管理控制台中開啟檔案網域，依序選擇「驗證」、「策略」和「OTP 策略」。為身份驗證器應用程式選擇基於時間的策略 (TOTP)。 Keycloak 也支援基於計數器的 HOTP，但 TOTP 通常更適合手機身份驗證器應用，因為驗證碼會隨時間變化。

部署前請仔細檢視策略。 Keycloak 會公開一些設置，例如雜湊演算法、程式碼長度、時鐘漂移視窗、令牌有效期以及程式碼是否可以重複使用。首先，請使用使用者目前使用的身份驗證器所支援的值。較大的時鐘視窗有助於減少時鐘漂移，但也會延長程式碼的有效期限。請確保伺服器時鐘保持同步，切勿透過擴大時鐘視窗來取代解決時間同步問題。

Keycloak 驗證頁面，已選擇「策略」選項卡，顯示 OTP 策略，並將 OTP 類型設定為「基於時間」。 — 選擇基於時間的 OTP 策略，以便使用者可以註冊相容的身份驗證器應用程式。

3. 要求新用戶註冊一次性密碼 (OTP)

在「驗證」 > 「必要操作」中，請確保已啟用「設定 OTP」並將其標記為預設操作。 Keycloak 文件指出，預設的必要操作會在新使用者首次登入時生效。這會建立一個註冊要求；使用者仍需完成設定才能獲得 TOTP 憑證。

同時檢查瀏覽器身份驗證流程。在標準的 Keycloak 瀏覽器流程中，條件雙重認證 (2FA) 子流程會在使用者設定了 OTP 憑證時提示輸入 OTP。如果使用者無需設定 OTP，則可以繼續操作而無需第二因素提示。保留正常的密碼或第一因素驗證步驟，並在綁定自訂流程之前仔細測試流程。身份驗證流程的變更會影響整個網域，如果配置錯誤，可能會導致管理員被鎖定。

Keycloak 必要操作表，其中「配置 OTP」已啟用，且其預設操作複選框已為新使用者選取。 — 將「設定 OTP」標記為預設必填操作，以便新建立的帳戶在首次登入時被要求註冊。

4. 對現有用戶增加註冊要求

預設操作不會追溯適用於已存在的帳戶。對於 Northstar 的現有員工，管理員需要在 Keycloak 網域中開啟每個用戶，並在該用戶的「必要操作」下新增「配置 OTP」，然後儲存變更。 Keycloak 文件還提供了使用者「憑證」標籤下的選項，用於傳送憑證重設電子郵件，引導使用者設定 OTP。選擇適合您帳戶管理流程的方法，並驗證使用者是否可以收到電子郵件（如果您使用此方法）。

對於大型目錄，請使用受支援的 Keycloak 管理介面或自動化工具規劃受控的批次處理流程。不要想當然地認為啟用預設操作會自動將所有人加入策略。在全面應用策略之前，請建立一個測試使用者並檢查預期的首次登入行為。

Keycloak 使用者詳細信息，用於代表帳戶，其中「配置 OTP」列在「必需使用者操作」中，並包含一個「儲存」按鈕。 — 對於現有帳戶，將「設定 OTP」指定為必要的使用者操作，並儲存帳戶變更。

5. 要求每個使用者註冊一個身份驗證器

當虛構的 Northstar 員工 Alex 下次登入 ownCloud 並被重新導向到 Keycloak 時，Keycloak 會要求 Alex 設定一次性密碼 (OTP)。 Alex 開啟一個驗證器應用，掃描 Keycloak 顯示的二維碼，然後輸入應用程式中顯示的驗證碼以確認註冊。此二維碼包含一次性密碼金鑰 (TOTP)，因此使用者應將其視為憑證：切勿透過電子郵件傳送給管理員、將其保存在共用工單中或在不受信任的裝置上掃描。

如果套用無法掃描二維碼，Keycloak 的設定頁面可能會提供手動輸入底層金鑰的選項。使用者應僅將該金鑰儲存在身份驗證器中。在關閉設定頁面之前，使用者應完成驗證步驟。驗證失敗的二維碼可能是過期的、輸入錯誤的，或是由裝置時鐘不正確的應用產生的。

Keycloak 設定 OTP 頁面範例，包含通用二維碼註冊圖形、程式碼欄位和「繼續」按鈕。 — Keycloak 註冊頁面會顯示一個二維碼，並要求使用者輸入來自身份驗證器的程式碼；該圖像是一個概念性的使用者介面範例。

範例驗證器應用程式螢幕，顯示了「檔案」帳戶條目、一個旋轉的六位數範例程式碼和一個倒數計時器。 — 身份驗證器應用程式會為帳戶產生一個不斷變化的程式碼；顯示的數字只是一個範例，不是可用的憑證。

6. 在執行政策之前，先做好補救準備。

使用者需要一種方法來恢復遺失、更換或資料被清除的手機的存取權限。 Keycloak 26.8 將復原驗證碼作為一項附加憑證，可在瀏覽器流程中啟用並新增為備選方案。如果您的 Keycloak 版本和網域支援此功能，請啟用並進行測試。使用者應將恢復碼儲存在經批准的密碼管理器或其他受保護的離線位置，並將每個恢復碼視為敏感資訊。請勿將其儲存在儲存 TOTP 金鑰的相同手機應用程式中。

如果您的網域中未啟用復原代碼，請記錄管理員主導的復原流程。在重置或移除 OTP 憑證之前，必須進行身份驗證。維護一個緊急管理員帳戶，並採用單獨的、嚴格控制的流程，以防止用戶註冊問題演變為全域鎖定。

Keycloak 恢復身份驗證碼範例頁面，包含帶有遮罩的佔位符代碼和確認複選框 — 如果為網域啟用了復原代碼，則應在使用者完成註冊之前將其儲存在受保護的位置。

7. 測試完整的 ownCloud 登入路徑

註冊完成後，請登出測試帳戶，然後使用正常的 Infinite Scale 地址重新登入。確認瀏覽器能夠存取預期的 Keycloak 網域，接受帳戶密碼，要求基於時間的驗證碼，並在身份驗證成功後將使用者返回 ownCloud。然後測試支援的桌面和行動用戶端、共用連結以及任何依賴相同身分提供者的操作工具。

瀏覽器測試成功並不能證明所有客戶端或協定都使用相同的流程。 Keycloak 的瀏覽器流程可能不包含單獨的直接授權流程，且現有的 Keycloak 單一登入 (SSO) 會話可以在不再次顯示 OTP 提示的情況下滿足後續的 ownCloud 登入。這是預期的會話重用，並非驗證因素失效的證據。如果策略要求更頻繁地使用新的驗證因素，請在製定會話策略時審查 Keycloak 的 SSO 和身份驗證等級設定。

上方是 ownCloud Infinite Scale 所有檔案頁面上的 Keycloak 一次性程式碼挑戰範例 — 預期的瀏覽器路徑會向身分提供者請求一次性程式碼，然後返回雲端文件介面；這是一個範例流程，而不是測試結果。

可選：僅對受保護的路由要求啟用升級版 MFA

某些部署方案僅要求使用者在存取敏感資源時啟用第二因素身份驗證。 Infinite Scale 支援透過 OIDC ACR 聲明進行路由級升級驗證。在 8.2 版本文件中，OCIS_MFA_ENABLED啟用強制執行並OCIS_MFA_AUTH_LEVEL_NAMES指定了表示多因素身份驗證 (MFA) 的 ACR 等級。身分提供者 (IDP) 必須支援升級身分驗證，並在令牌中頒發相符的 ACR 值。 Keycloak 提供了針對此模式的驗證等級和 ACR 配置，但其流程、請求等級和令牌對應必須與 Infinite Scale 中配置的值相符。

OCIS_MFA_ENABLED=true
OCIS_MFA_AUTH_LEVEL_NAMES=advanced

此範例僅為起點：advanced僅當 Keycloak 實際配置為在所需因素之後傳回該 ACR 值時才使用。如果請求的受保護路由缺少必要的級別，Infinite Scale 可能會拒絕存取並傳回帶有X-OCIS-MFA-Required標頭的 403 回應。路由等級的升級與每次新的 Keycloak 瀏覽器驗證期間都需要 TOTP 不同。

常見問題及解決方法

症狀	需要檢查什麼
沒有出現一次性密碼提示	確認帳戶已完成 OTP 註冊，瀏覽器流程已為已設定使用者呼叫 OTP 步驟，且預先存在的 SSO 會話未重複使用驗證。
新用戶無需註冊	確認「配置一次性密碼」功能已啟用，並在正確的網域中標記為預設操作。預設操作適用於新使用者；現有帳戶需要指派必需的操作。
代碼被拒絕	確認使用者選擇的是 TOTP 而非 HOTP，並檢查裝置和伺服器時鐘。請使用者等待下一個驗證碼間隔，然後輸入新的驗證碼。
桌面端、行動端或自動化登入失敗	檢查客戶端使用的 OIDC 或其他身份驗證流程。測試每個受支援的用戶端，並確保變更沒有將非瀏覽器登入依賴於僅限瀏覽器的流程。
流程變更後，使用者將被鎖定。	請使用已記錄的管理員恢復流程和受保護的緊急帳戶。在再次變更預設流程之前，請先查看網域的最後一次流程變更。