如何在 Element Web 中設定 Keycloak 單一登入 (SSO)

Element Web 不會直接向 Keycloak 進行驗證。 Element 會向其 Matrix 伺服器請求支援的登入方式；伺服器會與 Keycloak 完成 OpenID Connect (OIDC) 連接，並將使用者傳回給 Element。對於使用 Synapse 內建 OIDC 支援的部署，需要在 Keycloak 中設定保密的 OIDC 用戶端，將該提供者新增至 Synapse，並可選擇調整 Element Web 的設定config.json以顯示或自動啟動 SSO。

本指南使用 Synapse 內建的 OIDC 提供程序，這是一種常見的部署方式。如果您的 homeserver 將驗證委託給 Matrix Authentication Service (MAS)，請改用下文所述的 MAS 回呼和提供者設定。這兩個回呼 URL 不同。本指南的說明已於 2026 年 10 月 6 日根據 Element Web 設定文件、Synapse v1.144 OIDC 指南、目前 MAS 上游 SSO 指南和 Keycloak 26.8.0 管理指南進行核對；部署套件和 UI 標籤可能因版本而異。

首先，確定您使用的身份驗證路徑。

部署	Keycloak 的配置位置	Keycloak回呼URL
Synapse 內建 OIDC	突觸`oidc_providers`	`https://matrix.example.com/_synapse/client/oidc/callback`
Synapse 將授權委託給 MAS	MAS`upstream_oauth2.providers`	`https://auth.example.com/upstream/callback/<provider-id>`

在建立客戶端之前，請先查看 Synapse 設定和部署文件。回呼函數必須屬於與 Keycloak 通訊的元件；請勿將 Element 的網站 URL 註冊為回呼函數。

你需要什麼

Synapse 的公共 HTTPS URL，例如https://matrix.example.com，以及可存取的 Keycloak 領域頒發者，例如https://sso.example.com/realms/company。
對 Keycloak 領域以及 Synapse 配置和服務的管理存取權。
備份目前配置，並在登入失敗時可以使用 Synapse 日誌或伺服器控制台。
關於帳戶配置的決定：哪些 Keycloak 使用者可以登錄，哪些聲明可以識別他們，以及是否必須保留現有的 Matrix 帳戶。

配置 Keycloak 以支援 Synapse OIDC

1. 創造一個保密的 OIDC 客戶

在用於 Matrix 帳戶的網域中，使用 OpenID Connect 協定為 Synapse 建立用戶端。啟用授權碼或標準流程以及用戶端身份驗證，以便 Synapse 可以在令牌端點使用用戶端金鑰。將客戶端 ID 設定為您將在 Synapse 中使用的值，例如synapse。

將有效的重定向 URI 設定為 Synapse 回呼函數的正確位址：

https://matrix.example.com/_synapse/client/oidc/callback

請將範例主機名稱替換為 Synapse 實際配置的公共基本 URL。請勿使用*生產環境中常用的寬泛通配符。 Keycloak 會驗證重定向 URI，因此主機、協定、路徑或尾部斜線不符都可能導致「不允許重定向 URI」錯誤。

保存客戶端，複製其產生的密鑰，並將其作為伺服器端密鑰儲存。請勿將其公開至 Element Web 的config.json原始碼控制系統、螢幕截圖或客戶端 JavaScript 中。 Keycloak 管理控制台在不同版本中對用戶端驗證或憑證的標記可能有所不同；請驗證產生的用戶端是否保密，並且能夠使用標準的授權碼流程。

2. 確認發卡機構和索賠訊息

頒發者標識的是領域，而不是 Keycloak 伺服器根目錄。在本例中，請使用 `<realm_root>` https://sso.example.com/realms/company。確認該領域的 OpenID 配置可透過 `<realm_root>` 訪問，<issuer>/.well-known/openid-configuration並且其通告的頒發者與您提供給 Synapse 的值完全匹配。

Synapse 需要一個穩定的身份聲明才能將 Keycloak 帳戶與 Matrix 使用者關聯起來。其 OIDC 提供者通常使用 OIDC 主體聲明來識別外部主體；下面的使用者名稱映射使用preferred_usernameMatrix 本地部分。請確保 Keycloak 實際傳回該聲明，並且使用者名稱在您的帳戶策略下是唯一且穩定的。如果您的組織允許更改使用者名，請在生產環境之前選擇並測試對應策略；意外的對應變更可能會影響使用者造訪的 Matrix 帳戶。

配置 Synapse

3. 新增 OIDC 提供商

在 Synapse 的主配置中新增一個提供者條目，通常情況下homeserver.yaml，將其與現有的 YAML 檔案合併，而不是取代其他設定。請將 `<realm issuer>` 和 `<client secret>` 替換為您的 realm issuer 和真實的客戶端金鑰：

oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://sso.example.com/realms/company"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_CLIENT_SECRET"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

請求的作用域控制 Keycloak 可以傳回哪些使用者資訊；但它們不保證每個聲明都會被填入。如果您不需要匯入電子郵件或顯示名稱，請相應地減少作用域和對應。根據您的部署情況，請確保設定檔僅對服務管理員和 Synapse 進程可讀。如果您透過容器或 Chart 管理 Synapse，請將提供者設定放在受支援的設定來源中，而不是編輯會被覆寫的產生檔案。

4. （選用）配置後台通道註銷

預設情況下，從一項服務中註銷並不一定會結束其他所有服務的瀏覽器會話。如果您希望 Keycloak 登出通知結束 Synapse 會話，請backchannel_logout_enabled: true在 Synapse 的 Keycloak 提供者中啟用此功能，並將 Keycloak 的 Backchannel 登出 URL 設定為：

https://matrix.example.com/_synapse/client/oidc/backchannel_logout

這是可選步驟，取決於您的登出策略和用戶端設定。請測試兩種註銷方式：Synapse 註銷和 Keycloak 註銷。不要以為僅從 Element 登出就會終止 Keycloak 會話。

5. 重新啟動並測試 Synapse

使用部署配置檢查驗證 YAML 文件，然後使用軟體包或容器設定支援的方法重新啟動或重新載入 Synapse。檢查 Synapse 日誌，尋找 OIDC 發現、用戶端驗證、回呼或宣告對應錯誤。首先使用測試帳戶，並確認其矩陣 ID 和顯示名稱是否為預期值。

配置元素 Web

6. 保持 SSO 可選或自動重定向

Synapse 發布 OIDC 登入後，Element Web 即可顯示其 SSO 登入選項。 Element 的sso_redirect_options設定控制瀏覽器體驗；它不會配置 Keycloak 或儲存客戶端金鑰。config.json如果您希望未經驗證的訪客在造訪歡迎頁面或登入頁面時被引導至可用的 SSO 流程，請將類似如下的設定新增至 Element Web 的 serve 中：

{
  "sso_redirect_options": {
    "immediate": false,
    "on_welcome_page": true,
    "on_login_page": true
  }
}

對於確實需要僅使用 SSO 登入的部署，請設定"immediate": true為對所有未經身份驗證的使用者啟用 SSO。這可能會使使用者更難找到密碼或其他登入選項，因此在強制執行之前，請測試復原功能和管理員存取權限。如果使用者需要在 SSO 和其他登入方式之間進行選擇，請停用自動重新導向，並測試 SSO 選項是否出現在登入流程中。

如果 Synapse 使用矩陣驗證服務

MAS 是一個獨立的身份驗證服務，可以作為 Keycloak 的 OIDC 用戶端。在該架構中，將 Keycloak 的重定向 URI 配置為 `< https://auth.example.com/upstream/callback/<provider-id>Provider ID>`，其中提供者 ID 與 MAS 配置相符。在 MAS 的 `<Provider ID>` 下設定提供者upstream_oauth2.providers；然後 Element 將使用主伺服器基於 MAS 的驗證流程。請勿使用 Synapse 的 `< /_synapse/client/oidc/callbackProvider ID>` 進行此上游連線。 MAS 需要一個支援授權碼流程的 OIDC 提供者。其配置格式、所需的提供者 ID 和遷移步驟與 Synapse 內建的 `<Provider ID>` 不同oidc_providers。

常見誤解及解決方法

我只需要修改 Element 的配置。 Element控制瀏覽器流程，而 Synapse 或 MAS 處理 OIDC。請先設定正確的 homeserver 端提供者。
「Keycloak 登入成功證明帳戶映射正確。」即使選擇了錯誤的本機部分或設定檔聲明，身份驗證也可能成功。請使用非生產用戶進行測試，並驗證產生的矩陣 ID。
「SSO 會自動停用密碼和註冊。」這些政策由主伺服器和部署環境控制。請分別檢查 Synapse 的登入和註冊設置，並確認已核准的策略。
「從 Element 登出後，我會在所有平台上都無法登入。」瀏覽器工作階段在 Keycloak 上可以保持活動狀態。如果需要集中式會話終止，請設定並測試背景登出功能。