如何將 Keycloak 配置為 ownCloud Infinite Scale 的身份提供者 (IDP)。

本指南使用基於 OAuth 2.0 的身份層 OpenID Connect (OIDC) 將 ownCloud Infinite Scale (oCIS) 連接到 Keycloak。 Keycloak 對使用者進行身份驗證；oCIS 信任 Keycloak 頒發的已簽名身分和存取資訊。基於瀏覽器的登入使用 HTTPS 重定向，同時 oCIS 也需要存取 Keycloak 的發現和簽署金鑰端點。

截至 2026 年 10 月 6 日，ownCloud 的最新管理文件在 Infinite Scale 9.0 版本中描述了這些設定。官方的 Keycloak 部署範例是一個有用的起點，但其 Compose 檔案和 realm 匯出可能會改變。請務必使用相容的鏡像版本，並仔細檢查您部署的文件，而不是盲目複製未版本化的範例。

基於瀏覽器的 ownCloud 登入和身分提供者透過 HTTPS 交換流量。 — 瀏覽器從 ownCloud 啟動，按照安全登入流程連線到身分提供者，並在身份驗證後返回。

配置 OIDC 前需要準備什麼

請準備 oCIS 的公共 HTTPS 位址（例如 `<oCIS_public_HTTPS_address>`）https://cloud.example.com和 Keycloak 的公共 HTTPS 位址（例如 `<Keycloak_public_HTTPS_address>` https://sso.example.com）。這兩個位址必須能夠被使用者的瀏覽器正確解析。 oCIS 伺服器還必須能夠存取 Keycloak 的 OIDC 元資料和公鑰簽章。如果反向代理伺服器為任一服務提供服務，請確保其公用主機名稱和轉送標頭配置一致。

一個可正常運作的 ownCloud Infinite Scale 部署，以及管理員對其環境或 Compose 配置的存取權限。
一個可用的 Keycloak 網域和管理員存取權限。網域是 Keycloak 的一個命名空間，用於管理使用者、客戶端、角色和身分設定。
瀏覽器和伺服器都信任的 TLS 證書，用於驗證 Keycloak 的 TLS 憑證。生產環境中不應停用證書驗證。
關於帳戶匹配的決定：將現有 oCIS 使用者連接到穩定的身份聲明，或啟用首次登入帳戶配置，並具有所需的寫入權限的用戶後端。

Keycloak 領域頒發者 URL 與其 OpenID Connect 發現文件 URL 配對。 — 領域頒發者是基本 URL；附加 /.well-known/openid-configuration 以檢查發現元資料。

1. 找到確切的 Keycloak 發行者

在 Keycloak 中，OIDC 頒發者通常是 realm URL，而不是 admin-console URL 或 discovery-document URL。例如，對於名為 `<realm_name>` 的 realm ，其值team可能類似於 ` https://sso.example.com/realms/team<realm_name>/ ...https://sso.example.com/realms/team/.well-known/openid-configurationissuer

從能夠存取 Keycloak 的伺服器，您可以使用以下命令檢查文件：

curl -fsS https://sso.example.com/realms/team/.well-known/openid-configuration

請檢查傳回的頒發者是否使用與您在 oCIS 中配置的方案、主機、路徑和領域名稱相同的名稱。 OpenID Connect 會精確驗證頒發者的身分；反向代理主機名稱不符或多出的斜線都可能導致登入失敗。

向 Keycloak 領域發現端點發出的終端請求以及 JSON 頒發者回應。 — 從可以存取 Keycloak 的主機執行發現請求，並將傳回的頒發者與 OCIS_OIDC_ISSUER 進行精確比較。

2. 為 ownCloud Web 註冊 OIDC 用戶端

客戶端是 Keycloak 用於決定哪些服務可以請求登入的應用程式註冊資訊。在 oCIS 使用的網域中建立或適配一個 OpenID Connect 用戶端。使用客戶端 ID，例如 `<client_id>` web，或自訂值，並確保它WEB_OIDC_CLIENT_ID與 oCIS 中的值相符。官方 ownCloud 範例使用 ` web<client_id>` 作為其預設值。

對於基於瀏覽器的用戶端，請使用標準授權碼流程，並使用與官方範例網域一致的公共用戶端配置。輸入部署所需的確切 HTTPS 重定向和登出後重定向模式。使用更精確的主機名稱模式（例如 `http://example.com/`）https://cloud.example.com/*比使用覆蓋所有主機的通配符模式更容易審核。僅新增部署所需的 Web 來源。不要為公共瀏覽器用戶端建立客戶端金鑰並將其嵌入前端配置中。

一個包含公共客戶端、授權碼流程和 HTTPS 重定向 URI 的 Keycloak OpenID Connect 用戶端範例。 — 對於 ownCloud Web，請將公共用戶端 ID 和允許的重定向 URI 與您的 ownCloud 主機名稱對齊。

3. 檢查聲明和範圍

OIDC 聲明是指令牌中攜帶或由使用者資訊端點傳回的身分屬性。至少，請謹慎選擇用戶名聲明。 ownCloud 代理程式預設使用 `<username>`preferred_username解析用戶，而 Keycloak 範例則使用標準設定檔和電子郵件範圍來設定 Web 用戶端。請驗證您自己的網域是否實際傳回您使用的聲明；聲明的可用性取決於客戶端範圍和協定映射器。

對於現有帳戶，配置的聲明必須對應到對應的穩定 ownCloud 使用者屬性。如果使用已變更的使用者名稱或電子郵件地址作為永久標識符，則可能會導致帳戶匹配問題。聲明sub保證在每個身分提供者都是唯一且穩定的，但可能與已存在的使用者名稱不符。在向所有使用者開放存取權限之前，請使用非管理員帳戶測試帳戶對應。

Keycloak OIDC 作用域和 preferred_username 宣告會對應在概念配置檢視中。 — 確認 ID 令牌或使用者資訊回應包含 ownCloud 配置為解析的穩定使用者名稱聲明。

4. 將無限縮放點到鑰匙斗篷

為 oCIS 部署設定以下環境變數值。範例假設使用 HTTPS 和 Keycloak 網域/realms/team。請使用您自己的 URL。此 YAML 樣式程式碼區塊僅供參考；Docker Compose、Kubernetes、systemd 和其他部署方法表達環境變數的方式有所不同。

OCIS_URL: https://cloud.example.com
OCIS_OIDC_ISSUER: https://sso.example.com/realms/team
PROXY_OIDC_REWRITE_WELLKNOWN: "true"
WEB_OIDC_CLIENT_ID: web
PROXY_USER_OIDC_CLAIM: preferred_username
OCIS_EXCLUDE_RUN_SERVICES: idp

OCIS_OIDC_ISSUER選擇外部身分提供者。PROXY_OIDC_REWRITE_WELLKNOWN=true使代理程式將 OpenID Connect 發現端點重寫為配置的頒發者；ownCloud 文件指出，這對於其桌面和行動用戶端發現提供者是必要的。WEB_OIDC_CLIENT_ID必須與 Keycloak 客戶端相符。排除項idp遵循 ownCloud 的 Keycloak 範例，因此嵌入式提供者不會作為活動登入提供者啟動。

設定 OIDC 頒發者、Web 用戶端 ID 和發現重寫選項的環境配置範例。 — 請在部署設定中保留頒發者 ID 和用戶端 ID。範例客戶端 ID 必須與 Keycloak 中註冊的 ID 一致。

如果您希望 oCIS 在首次成功登入時建立帳戶，請設定PROXY_AUTOPROVISION_ACCOUNTS=true並設定具有寫入權限的使用者後端 Graph 服務。將 `username`PROXY_USER_OIDC_CLAIM和`id` 設定PROXY_AUTOPROVISION_CLAIM_USERNAME為相同聲明；對於使用者名稱屬性，請參閱 ownCloud 文件PROXY_USER_CS3_CLAIM=username以了解此流程。自動配置是可選的，應與身份驗證分開測試。除非傳入的聲明是唯一的且映射符合預期，否則請勿啟用此功能。

5. 在內容安全策略中允許身分提供程序

Infinite Scale 使用內容安全性原則 (CSP) 來控制其 Web 用戶端可以連接哪些外部來源。 ownCloud 的文檔指出，像 Keycloak 這樣的外部身分提供者需要適當的 CSP 定義。如果登入按鈕出現但瀏覽器封鎖了請求，請檢查瀏覽器控制台是否有 CSP 錯誤。透過配置策略PROXY_CSP_CONFIG_FILE_LOCATION，並僅允許部署所需的 Keycloak 來源和指令。更改檔案後，請重新啟動代理程式或部署。不要透過允許所有來源來解決連線問題。

6. 重新啟動並驗證整個流程

應用環境變更並使用您已用於管理 oCIS 部署的方法重新啟動 oCIS 部署。沒有通用的重啟指令：Compose 專案、Kubernetes 工作負載和 systemd 服務都有不同的控制方式。然後檢查鏈條中的每個環節：

開啟 Keycloak 發現 URL 並確認它會傳回包含issuer, authorization_endpoint, token_endpoint, 和的JSON jwks_uri。
在隱私瀏覽視窗中開啟 ownCloud Web URL。確認瀏覽器已重定向到預期的 Keycloak 域。
使用測試帳戶登錄，並確認瀏覽器返回相同的 ownCloud 主機名，而不會出現重定向循環。
檢查預期使用者（而不是新建立的重複使用者）是否出現在 Infinite Scale 中，並且只能存取預期的資源。
測試註銷功能，然後使用第二個帳戶重複此操作。如果桌面或行動用戶端也在測試範圍內，請分別測試它們的發現和登入功能。

OpenID Connect 發現文件的瀏覽器視圖，包含頒發者、授權、令牌和 JWKS 端點。 — 發現文件公佈了 ownCloud 完成 OIDC 身份驗證所需的頒發者和端點。

使用者、ownCloud Infinite Scale 和 Keycloak 之間的瀏覽器驗證流程範例。 — Keycloak 對使用者進行身份驗證後，瀏覽器會回到 ownCloud，ownCloud 會驗證 OIDC 回應，然後再開啟檔案。

常見故障及其通常意義

症狀	首先檢查
發行方不符或代幣無效	`OCIS_OIDC_ISSUER`與發現文件中的值逐字比較`issuer`。
Keycloak 重定向 URI 錯誤	檢查用戶端的有效重新導向和登出後 URL 與真正的公共 ownCloud URL 是否一致，包括 HTTPS 和路徑。
登入功能在瀏覽器中可用，但在桌面或行動用戶端中不可用。	確認`PROXY_OIDC_REWRITE_WELLKNOWN=true`並檢查 ownCloud URL 提供的發現回應。
瀏覽器控制台報告請求被阻止	檢查 CSP 並使用必要的指令允許 Keycloak 來源。
用戶登入後發現帳號錯誤或重複帳號。	檢查使用者名稱聲明、其在令牌或使用者資訊回應中的值以及與現有帳戶的對應關係。
伺服器發送的 TLS 或發現請求失敗	驗證 DNS、反向代理路由、憑證鏈信任，以及 oCIS 主機是否可以存取 Keycloak。