Synapse OIDCを介してElement WebをKeycloakに接続します。

Element WebにKeycloakサインイン機能を追加するには、SynapseでKeycloakをOpenID Connect(OIDC)プロバイダーとして設定し、Element WebがそのSynapseホームサーバーを使用していることを確認してください。認証リダイレクトとコールバックはSynapseが処理するため、Element WebはKeycloakクライアントシークレットを必要としません。

シナリオ例(架空):小規模な組織が、Element Webをchat.example.org、Synapseをmatrix.example.org、Keycloakをで運用していますlogin.example.org。他のホスト名にも同じ手順が適用されますが、すべてのURLは実際の公開設定と一致している必要があります。この例は説明のためのものであり、実際の運用環境のレポートではありません。

設定を変更する前に必要なもの

KeycloakとSynapseには公開HTTPS URLを使用してください。SynapseのOIDCドキュメントでは、IDプロバイダにセキュアなオリジンが必要とされており、コールバックは公開Synapse URL経由でアクセス可能でなければなりません。Keycloak、Synapse public_baseurl、およびElement Webに提供されるホームサーバーのURLでレルム名を確認してください。いずれかのサービスの前にリバースプロキシがある場合は、リクエストを正しいバックエンドに渡し、外部HTTPSホストとスキームを維持する必要があります。

Synapseの現在の設定ではoidc_providersリスト形式が使用されています。以前の単一プロバイダーoidc_config形式は非推奨です。テスト中は、正常に動作する管理者ログインと現在の設定のコピーを保持してください。SSOフローを確認し、アカウントのプロビジョニング方法を決定するまでは、パスワードログインや登録を無効にしないでください。

1. KeycloakにSynapseをクライアントとして登録する

組織のユーザーが利用する Keycloak レルムで、Synapse 用の OpenID Connect クライアントを作成します。Synapse の公式 Keycloak の例では、クライアント ID を持つ機密クライアントを使用していますsynapse。有効なリダイレクト URI を、Synapse ホスト名に置き換えて、このコールバックに正確に設定します。

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

想定される設定では、クライアントアクセスタイプを「機密」に設定し、クライアントを有効にします。「認証情報」タブで、生成されたクライアントシークレットをシークレット管理システムにコピーします。Element Webのパブリックフォルダに置いconfig.jsonたり、リポジトリに公開したりしないでください。

リダイレクトURIは、頻繁にエラーの原因となります。Synapseの公開URL、正確な/_synapse/client/oidc/callbackパス、そしてブラウザからSynapseが認識するスキームとホスト名と同じものを使用する必要があります。正確なURIで済む場合は、広範囲のワイルドカードコールバックは避けてください。後でバックチャネルログアウトを有効にする場合は、KeycloakにもSynapseのドキュメントに記載されているバックチャネルエンドポイントを追加してください。これはオプションであり、基本的なサインインとは別個の機能です。

2. KeycloakプロバイダーをSynapseに追加する

アクティブな を編集しますhomeserver.yaml。以下のレルムとシークレットを実際の値に置き換え、レルムの OpenID ディスカバリ ドキュメントから発行者 URL を確認してください。標準の Keycloak レルム発行者は次の形式です。

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_usernameMatrix ローカルパートを作成し、name表示名として使用します。これらのクレームがユーザーに対して存在し、安定していることを確認してください。Matrix ローカルパートはアカウント識別子であるため、後でマッピングを変更すると、アカウントのマッチングが混乱したり、異なる Matrix ID が生成されたりする可能性があります。

他のIDプロバイダーが設定されている場合は、既存のoidc_providersリストを保持し、無関係なプロバイダーを置き換えるのではなく、このエントリを追加します。クライアントシークレットをシークレットとして保護し、デプロイメントに応じてファイル権限を設定します。YAMLのインデントを検証してから、インストール用のサービスまたはコンテナの手順に従ってSynapseを再起動します。パッケージ化されたインストールには、すでにOIDCの依存関係が含まれている場合があります。virtualenvのインストールについては、Synapseのインストールに関するドキュメントmatrix-synapse[oidc]を参照してください。その他のインストール方法については、パッケージメンテナーのガイダンスに従ってください。

3. 同じホームサーバー上のWeb要素を特定する

Element Web はconfig.json、例えば を介して Synapse サーバーをホームサーバーとして識別する必要がありますdefault_server_config.mHomeserver.base_url。Keycloak 発行者ではなく、実際のホームサーバーの URL を使用してください。Element Web は静的クライアントです。ホームサーバーの URL を変更した後は、ホスティング方法を使用して設定を再デプロイまたは再読み込みしてください。ブラウザが読み取れるため、Keycloak のクライアント シークレットをこのファイルに記述しないでください。

架空の例として、Element Web は でホストされhttps://chat.example.org、 に接続しますhttps://matrix.example.org。ユーザーが Element のサインイン画面で SSO オプションを選択すると、ブラウザは Synapse のログイン フローを経て Keycloak レルムに移動し、Synapse のコールバックに戻ります。ボタンの正確な文言やログイン画面のレイアウトは、Element Web のリリースやサーバー構成によって異なる場合があります。特定のラベルに頼るのではなく、動作をテストしてください。

4. SSOを強制適用する前に、1つのアカウントでテストする

プライベートブラウザウィンドウでElement Webを開き、SSOログインオプションを選択します。テスト用のKeycloakユーザーでサインインし、プロンプトが表示されたらアクセス要求を承認し、ブラウザが目的のホームサーバーに戻り、期待どおりのMatrixアカウントが開くことを確認します。生成されたMatrix IDに目的のlocalpartが含まれていることを確認します。ブラウザがエラーを返す場合は、SynapseとKeycloakのログを確認してください。

リダイレクトが失敗した場合は、Keycloak のコールバック URL と Synapse の公開コールバック URL を文字ごとに比較してください。「発行者の不一致」は、レルム発行者またはリバースプロキシのホスト名が間違っていることを示しています。ユーザー名が見つからない、またはマッピングエラーは、設定されたクレームが存在しないか、または不適切であることを意味します。テストユーザーのクレームを調べて、マッピングを意図的に調整してください。ブラウザが Keycloak に到達しても応答がない場合は、TLS 証明書と Synapse コールバックのプロキシルーティングを確認してください。

オプションのログアウト: 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 の管理 UI はリリース間で変更される場合があります。ここでの手順は、2026 年 10 月 10 日時点で利用可能な Synapse の OIDC ドキュメントに準拠しており、標準の Keycloak レルムと、ドキュメントに記載されているプロバイダー形式を使用した Synapse デプロイメントを前提としています。バージョン固有の設定を適用する前に、 Synapse OpenID Connect および Keycloak ガイド、Synapse 構成リファレンス、および公式の Keycloak ドキュメントを参照してください。テスト アカウントが正しくサインインし、復旧ルートが確立されたら、管理者向けに最終的なコールバック、発行者、およびクレーム マッピングを文書化してください。

コメントを残す

Synapse OIDCを介してElement WebをKeycloakに接続します。

Keycloak OIDCクライアントとSynapseプロバイダーを設定することで、Element Webユーザーがクライアントシークレットを公開することなく、IDサーバー経由でサインインできるようになります。

要素キーのバックアップとクロス署名を安全に設定する

要素キーのバックアップとクロス署名を安全に設定する

復旧キーを保存し、Elementセッションを確認し、暗号化されたメッセージキーがアカウントパスワードと混同することなく復元できることを確認してください。

クライアント同期中に発生するMatrix Synapseのメモリクラッシュを停止する

Synapseの同期中に発生するメモリ不足エラーを診断し、キャッシュを安全に調整し、リクエストのバックログを特定し、安定したメモリ使用状況を確認します。

Synapse Federation TLS証明書のエラーを解決する

トレースマトリックスのフェデレーション証明書の障害を正しいサーバーに追跡し、TLSチェーンまたはCA信頼を修復し、セキュリティチェックを無効にすることなく修正を検証します。

Synapse MatrixサーバーをCloudflareの背後に安全に配置する

Synapse MatrixサーバーをCloudflareの背後に安全に配置する

Route MatrixクライアントとCloudflareをHTTPS 443経由でフェデレーションすることで、Synapseの検出機能を維持し、APIトラフィックのキャッシュやメディアアップロードの中断を回避します。

PostgreSQLダンプを使用してMatrix Synapseを安全に復元する

pg_dumpを使用してSynapseをバックアップし、署名キーとメディアを保護し、古いワンタイムキーを再利用せずにクリーンなPostgreSQLデータベースに復元します。

MjölnirをDockerでMatrixルームモデレーションボットとして実行する

MjölnirをDockerでMatrixルームモデレーションボットとして実行する

Mjölnirを、専用のMatrixアカウント、暗号化された管理ルーム、Docker Compose、ポリシーリスト、および権限チェックとともにセットアップします。

モバイル読み込み速度を向上させるために、ネイティブマトリックススライディング同期を有効にする

モバイル読み込み速度を向上させるために、ネイティブマトリックススライディング同期を有効にする

廃止されたプロキシはスキップし、Synapseに組み込まれているスライディング同期を設定してください。クライアント検出機能をチェックした後、互換性のあるスマートフォンでルームリストの読み込みと再接続の動作を測定します。

カスタムホームサーバーを使用してNginx上でWebサイトをホストする

Element Webを静的サイトとしてデプロイし、Matrixホームサーバーに接続し、HTTPSを追加し、Nginxを設定して古いファイルなしで更新を配信します。

Raspberry Pi 4で軽量なMatrix Homeserverを実行する

64ビット版Raspberry Pi 4に、永続データ、HTTPSフェデレーション、保護された登録、および動作中のホームサーバーのチェック機能を備えたConduitをセットアップします。