透過操作解決矩陣房間管理員權限錯誤
追蹤 M_FORBIDDEN 到房間功率等級、成員資格或 Synapse 伺服器管理員存取權限,然後僅恢復被封鎖操作所需的權限。
若要將 Keycloak 登入新增至 Element Web,請在 Synapse 中將 Keycloak 配置為 OpenID Connect (OIDC) 提供程序,然後確保 Element Web 使用的是該 Synapse 主伺服器。 Synapse 會處理驗證重新導向和回呼;Element Web 不需要 Keycloak 用戶端金鑰。
範例場景(假設):一個小型組織在 `<hostname>` 上執行 Element Web chat.example.org,在 `<hostname>` 上執行 Synapse matrix.example.org,在 `<hostname>` 上執行 Keycloak login.example.org。同樣的順序也適用於其他主機名,但每個 URL 必須與您的實際公共配置相符。此範例僅供參考,並非實際部署情況的報表。
請使用公用 HTTPS URL 存取 Keycloak 和 Synapse。 Synapse 的 OIDC 文件要求身分提供者使用安全性來源,且其回呼必須可透過公用 Synapse URL 存取。請確認 Keycloak、Synapsepublic_baseurl和 Element Web 使用的 homeserver URL 中的 realm 名稱。如果任一服務前端使用了反向代理,則反向代理必須將請求轉送到正確的後端,並保留外部 HTTPS 主機和協定。
Synapse 目前配置使用oidc_providers清單形式。舊的單提供者oidc_config形式已被棄用。測試期間,請保留一個可用的管理員登入帳號和一份目前配置的副本。在驗證 SSO 流程並確定帳號設定方式之前,請勿停用密碼登入或註冊。
在您組織使用者所在的 Keycloak 網域中,為 Synapse 建立一個 OpenID Connect 用戶端。 Synapse 官方 Keycloak 範例使用了一個客戶端 ID 為 `client_id` 的機密客戶端synapse。將有效的重定向 URI 設定為此回調,並將 `client_id` 替換為您的 Synapse 主機名稱:
https://matrix.example.org/_synapse/client/oidc/callback
對於假設的設置,請將客戶端存取類型設為「機密」並啟用客戶端。在「憑證」標籤上,將產生的用戶端金鑰複製到您的金鑰管理系統中;請勿將其放在 Element Web 的公共目錄中config.json或發佈到任何儲存庫中。
重定向 URI 是常見的故障來源。它必須使用 Synapse 的公共 URL、確切/_synapse/client/oidc/callback路徑,以及 Synapse 從瀏覽器看到的相同協定和主機名稱。如果精確的 URI 可以正常運作,請避免使用寬泛的通配符回呼。如果您之後啟用了背景登出,也請在 Keycloak 中新增 Synapse 文件中記錄的後台登出端點;這是可選的,並且與基本登入功能無關。
編輯活動配置homeserver.yaml。將下面的 realm 和 secret 替換為您自己的值,並從 realm 的 OpenID 發現文件中確認頒發者 URL。標準的 Keycloak realm 發行者 URL 格式如下:
https://login.example.org/realms/your-realm
對於使用 Synapse Keycloak 範例中所示的標準發現端點和聲明的部署,提供者條目為:
oidc_providers:
- idp_id: keycloak
idp_name: "Company Login"
issuer: "https://login.example.org/realms/your-realm"
client_id: "synapse"
client_secret: "REPLACE_WITH_THE_KEYCLOAK_SECRET"
scopes: ["openid", "profile"]
user_mapping_provider:
config:
localpart_template: "{{ user.preferred_username }}"
display_name_template: "{{ user.name }}"
頒發者必須與 Keycloak 的網域頒發者匹配,而不僅僅是 Keycloak 伺服器根目錄。發現機制允許 Synapse 從該頒發者取得授權、令牌和使用者資訊端點。對應使用 Keycloak 的聲明preferred_username來建立 Matrix 本地部分並name作為顯示名稱;請確保這些聲明對您的使用者而言存在且穩定。 Matrix 本地部分是帳戶標識符,因此稍後更改對應可能會導致帳戶匹配混亂或產生不同的 Matrix ID。
如果已配置其他身分提供程序,請保留現有oidc_providers清單;新增此條目,而不是取代不相關的提供者。將客戶端金鑰作為金鑰保護,並根據您的部署設定檔案權限。驗證 YAML 縮進,然後使用適用於您安裝的服務或容器程序重新啟動 Synapse。打包安裝可能已包含 OIDC 相依性;對於 virtualenv 安裝,請參閱 Synapse 文件中的安裝說明matrix-synapse[oidc]。對於其他安裝方法,請遵循軟體包維護者的指導。
Element Webconfig.json應該將 Synapse 伺服器標識為其 homeserver,例如透過 `< default_server_config.mHomeserver.base_urlhomeserver URL>`。請使用實際的 homeserver URL,而不是 Keycloak 發行者的 URL。 Element Web 是一個靜態用戶端:變更 homeserver URL 後,請使用您的託管方式重新部署或重新載入其設定。請勿將 Keycloak 的客戶端金鑰放在此文件中,因為瀏覽器可以讀取它。
假設 Element Web 託管於 [此處應填入伺服器位址https://chat.example.org] 並連接到 [此處應填入https://matrix.example.org伺服器位址]。當使用者在 Element 的登入介面選擇 SSO 選項時,瀏覽器應透過 Synapse 的登入流程跳到 Keycloak 網域,然後傳回 Synapse 的回呼函數。具體的按鈕文字和登入介面佈局可能因 Element Web 版本和伺服器配置而異;請測試實際行為,而不是只依賴某個標籤。
在隱私瀏覽視窗中開啟 Element Web,並選擇 SSO 登入選項。使用測試 Keycloak 使用者登錄,如果出現提示,請批准要求的存取權限,並確認瀏覽器返回目標伺服器並開啟預期的 Matrix 帳戶。檢查產生的 Matrix ID 是否包含預期的本機部分。如果瀏覽器回傳錯誤,請查看 Synapse 和 Keycloak 日誌。
如果重定向失敗,請將 Keycloak 中的回呼 URL 與 Synapse 的公共回呼 URL 逐字比較。 「頒發者不符」表示網域頒發者或反向代理主機名稱錯誤。缺少使用者名稱或映射錯誤表示配置的聲明缺失或不適用;請檢查測試使用者的聲明並手動調整映射。如果瀏覽器存取了 Keycloak 但未傳回,請檢查 Synapse 回呼的 TLS 憑證和代理程式路由。
可選註銷: Synapse 支援 OIDC 反向通道註銷。若要使用此功能,請backchannel_logout_enabled: true在此提供者下進行設置,並將 Keycloak 的反向通道登出 URL 配置為https://matrix.example.org/_synapse/client/oidc/backchannel_logout。 Synapse 也提供了在 Keycloak 中啟用會話必要選項的文件。此選項用於處理供應商發起的登出通知;它並非實現初始 SSO 登入的必要條件。
部署前:確定 SSO 是建立新的 Matrix 用戶,還是僅驗證您單獨配置的帳戶,然後查看 Synapse 針對您已安裝版本的 OIDC 選項。配置標籤和 Keycloak 管理介面在不同版本之間可能會有所變化。此處的步驟遵循 Synapse 於 2026 年 10 月 10 日發布的 OIDC 文檔,並假設使用標準的 Keycloak 域和採用文檔中提供的提供程序格式的 Synapse 部署。在套用特定於版本的設定之前,請參閱Synapse OpenID Connect 和 Keycloak 指南、Synapse 設定參考以及Keycloak 官方文件。測試帳戶成功登入並設定恢復路徑後,請記錄最終的回呼、頒發者和聲明映射,以供管理員參考。
追蹤 M_FORBIDDEN 到房間功率等級、成員資格或 Synapse 伺服器管理員存取權限,然後僅恢復被封鎖操作所需的權限。
設定 Synapse 發現、HTTPS 和代理路由,以便其他 Matrix 主伺服器可以找到並聯絡您的伺服器。
配置 Keycloak OIDC 用戶端和 Synapse 提供程序,以便 Element Web 使用者可以透過您的身分伺服器登錄,而無需暴露客戶端金鑰。
儲存恢復金鑰,驗證您的 Element 會話,並檢查加密訊息金鑰是否可以恢復,而不會將備份與您的帳戶密碼混淆。
診斷 Synapse 在同步過程中記憶體不足的故障,安全地調整緩存,識別請求積壓,並驗證穩定的記憶體使用量。
追蹤矩陣聯合憑證故障到正確的伺服器,修復 TLS 鍊或 CA 信任,並在不停用安全檢查的情況下驗證修復。
Route Matrix 用戶端和透過 Cloudflare 在 HTTPS 443 上進行聯合,可以保留 Synapse 探索功能,避免快取 API 流量或中斷媒體上傳。
使用 pg_dump 備份 Synapse,保護其簽章金鑰和介質,並將其還原到乾淨的 PostgreSQL 資料庫中,而無需重複使用過時的一次性金鑰。
使用專用 Matrix 帳戶、加密管理室、Docker Compose、政策清單和權限檢查來設定 Mjölnir。
跳過已停用的代理,配置 Synapse 內建的滑動同步功能。檢查客戶端發現情況,然後在相容的手機上測量房間清單載入和重新連接行為。