使用 OIDC 將 ownCloud Infinite Scale 連接到 Keycloak

使用者常常會遇到這樣的情況：登入 Keycloak 頁面並完成身份驗證後，卻又跳到 ownCloud Infinite Scale 的登入介面，或是看到「未知使用者」錯誤。常見原因包括：網域頒發者不符、Web 用戶端是從其他範例版本複製而來，或身分聲明與 oCIS 帳戶不符。請將 Keycloak 設定為 oCIS 的外部 OpenID Connect 提供者 (OIDC)，確保這三個值一致，並驗證瀏覽器和用戶端是否可以透過 HTTPS 存取該提供者。

本演練使用虛擬主機：cloud.example.com分別用於 oCIS 和sso.example.comKeycloak。設定參考 ownCloud Infinite Scale 8.2 文件；在應用程式設定前，請將名稱與您已安裝版本的文件進行核對。本演練適用於 Infinite Scale (oCIS)，而非 ownCloud Server 10。

1. 檢查領域和發現端點

身分提供者 (IdP) 為其他服務驗證使用者身分。 OpenID Connect 是登入協議，它使 oCIS 能夠信任 Keycloak 的登入和身分資訊。網域是 Keycloak 的獨立使用者、客戶端和設定集合。選擇將為 oCIS 提供服務的網域，然後確定其頒發者 URL：例如，對於範例網域ocis，它是https://sso.example.com/realms/ocis。

在編輯 oCIS 之前，請先https://sso.example.com/realms/ocis/.well-known/openid-configuration在瀏覽器中開啟此 OpenID Connect 發現文件。該文件描述了提供者的端點。請確認其issuer值與領域 URL 完全匹配，包括協定、主機、大小寫和路徑。頒發者不能是管理頁面或較長的發現 URL。提供者的 TLS 憑證必須同時受到使用者瀏覽器和 oCIS 伺服器/容器的信任。

如果發現 URL 無法加載，請先解決 DNS、反向代理路由、防火牆或憑證問題。僅憑瀏覽器回應成功並不能證明 oCIS 容器可以存取 Keycloak；還需要檢查伺服器部署網路的網路存取情況。 OpenID Connect 發現規則要求傳回的頒發者識別相同的提供者。請參閱OpenID Connect 發現規格。

2. 將 Keycloak 用戶端與 oCIS Web 應用程式配對

請使用維護良好的ownCloud Keycloak 部署範例作為起點，並將其 realm 檔案與您的 oCIS 版本相符。請勿混用不同版本：目前的 compose 範例使用 web 用戶端 ID web，而較舊的設定說明則ocis-web使用 。 Keycloak 和 oCIS 必須使用相同的客戶端 ID。

在 Keycloak 中，開啟選定的網域和 Web 用戶端。將登入流程和用戶端 ID 與 ownCloud 範例進行比對。使用公共 HTTPS 主機，將有效的重定向 URI 設定為該網域所需的精確回呼位址。僅根據範本要求設定 Web 來源。以下通配符僅供參考，並非生產環境建議：寬泛的重定向模式可能會導致意外的目標。標籤會因 Keycloak 版本而異。

保持 Keycloak 的公共主機名稱穩定。如果 TLS 連線終止於反向代理，請設定其公用主機名稱和受信任的代理程式標頭，否則重定向可能會使用錯誤的協定或主機；請遵循Keycloak 反向代理指南。在公開 Keycloak 之前，請先取代演示管理員憑證。

3. 將 oCIS 指向同一發卡機構和客戶

將這些變數新增至部署配置中的 oCIS 服務，同時保留其其他設定和金鑰。範例使用虛構的 URL 和當前範例客戶端 ID：

OCIS_URL=https://cloud.example.com
OCIS_OIDC_ISSUER=https://sso.example.com/realms/ocis
WEB_OIDC_CLIENT_ID=web
PROXY_OIDC_REWRITE_WELLKNOWN=true
OCIS_EXCLUDE_RUN_SERVICES=idp

OCIS_URL是公共 oCIS 位址；頒發者和客戶端 ID 必須與 Keycloak 完全匹配。此重寫啟用桌面、Android 和 iOS 用戶端使用的發現路徑。排除此配置idp會停止外部身分提供者 (IdP) 部署中的內建提供者；如果您的設定有意使用該服務，請省略此配置。

使用部署的正常重新啟動流程套用變更。使用 Docker Compose 時，請docker compose up -d從 compose 目錄執行指令以重新建立已變更的服務，然後查看 oCIS 日誌。在生產環境中使用受信任的 TLS 憑證。 ownCloud 範例將其標記INSECURE=true為本機自簽名憑證選項；在面向網際網路的伺服器上，請將其移除或設定為 false。 ownCloud 也建議不要在生產環境中使用PROXY_OIDC_INSECURE。

4. 決定 oCIS 應如何辨識用戶

宣告是 OIDC 身分字段，例如sub` <username> preferred_username`、`<mail>` 或 ` email<user ID>`。 oCIS 使用它來尋找帳戶。對於現有用戶，將其對應到他們已使用的屬性—使用者名稱、郵箱或使用者 ID。如果匹配不匹配，Keycloak 在接受登入後可能會出現「找不到用戶」的錯誤。

若要在首次登入時建立帳戶，請PROXY_AUTOPROVISION_ACCOUNTS=true僅在需要時設定，並且必須在 oCIS Graph 使用者後端啟用寫入權限後進行設定。標識符必須唯一、穩定且不可重新分配。 ownCloud 識別碼被認為sub是合適的；僅當電子郵件地址或首選使用者名稱無法變更時才使用。請確保創建聲明和查找聲明保持一致：

PROXY_AUTOPROVISION_ACCOUNTS=true
PROXY_AUTOPROVISION_CLAIM_USERNAME=sub
PROXY_USER_OIDC_CLAIM=sub
PROXY_USER_CS3_CLAIM=username

確認 Keycloak 是否在令牌或使用者資訊回應中傳回了所選聲明。如果自動設定功能關閉，登入時不會建立新使用者；如果 Graph 後端為唯讀模式，則設定可能會失敗。僅在登入成功後才會新增群組或角色對應。在啟用寫入權限或變更身分映射之前，請參閱 ownCloud 8.2 代理程式和自動設定文件。

驗證完整的登入流程

在隱私瀏覽視窗中開啟 oCIS 並登入。您應該能夠連接到 Keycloak 網域，通過身份驗證，並返回與預期帳戶相同的 oCIS 主機。首先測試一個現有帳戶。如果啟用了設定功能，請測試已核准的新用戶，並確認該用戶已使用預期的用戶名建立。登出並重新登入。

對於桌面或行動裝置發現，請開啟https://cloud.example.com/.well-known/openid-configuration；重寫操作應公開 Keycloak 的提供者資訊。登入循環表示重定向主機或方案不符。成功登入後用戶被拒絕表示缺少聲明或與PROXY_USER_OIDC_CLAIM不符PROXY_USER_CS3_CLAIM。