Element WebでKeycloakを使用してシングルサインオン（SSO）を設定する方法

Element Web は Keycloak に対して直接認証を行いません。Element は、サポートされているログイン方法を Matrix ホームサーバーに問い合わせます。ホームサーバーは Keycloak との OpenID Connect (OIDC) を完了し、ユーザーを Element に返します。組み込みの OIDC サポートを使用する Synapse デプロイメントの場合は、Keycloak で機密 OIDC クライアントを設定し、そのプロバイダーを Synapse に追加し、必要に応じて Element Web の設定を調整してconfig.jsonSSO を表示または自動的に開始します。

このガイドでは、一般的な導入方法である Synapse の組み込み OIDC プロバイダを使用します。ホームサーバーが認証を Matrix Authentication Service (MAS) に委任している場合は、代わりに以下で説明する MAS コールバックとプロバイダ構成を使用してください。2 つのコールバック URL は異なります。手順は、2026 年 10 月 6 日に Element Web 構成ドキュメント、Synapse v1.144 OIDC ガイド、最新の MAS アップストリーム SSO ガイド、および Keycloak 26.8.0 管理ガイドに基づいて確認済みです。導入パッケージと UI ラベルはバージョンによって異なる場合があります。

まず、どの認証パスを使用しているかを確認してください。

クライアントを作成する前に、Synapseの設定およびデプロイメントに関するドキュメントを確認してください。コールバックはKeycloakと通信するコンポーネントに属するものでなければなりません。ElementのWebサイトURLをコールバックとして登録しないでください。

必要なもの

• Synapse の公開 HTTPS URL (例: https://matrix.example.com) と、到達可能な Keycloak レルム発行者 (例: https://sso.example.com/realms/company)。
• KeycloakレルムおよびSynapseの設定とサービスへの管理者アクセス権。
• 現在の設定のバックアップと、サインインに失敗した場合にSynapseログまたはサーバーコンソールを使用する方法。
• アカウントプロビジョニングに関する決定事項：どのKeycloakユーザーがサインインできるか、どのクレームでユーザーを識別するか、既存のMatrixアカウントを保持する必要があるかどうか。

Synapse OIDC 用に Keycloak を設定する

1. 機密性の高いOIDCクライアントを作成する

Matrix アカウントに使用されるレルムで、OpenID Connect プロトコルを使用して Synapse のクライアントを作成します。認証コードまたは標準フローとクライアント認証を有効にして、Synapse がトークンエンドポイントでクライアントシークレットを使用できるようにします。クライアント ID を Synapse でも使用する値に設定します (例: ) synapse。

有効なリダイレクトURIを、正確なSynapseコールバックに設定してください。

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

例のホスト名を、Synapse用に実際に設定されている公開ベースURLに置き換えてください。本番環境では、*`/etc/hostname

クライアントを保存し、生成されたシークレットをコピーして、サーバー側のシークレットとして保存してください。Element Web の公開情報config.json、ソース管理、スクリーンショット、クライアント側の JavaScript には含めないでください。Keycloak 管理コンソールでは、リリースによってクライアント認証や資格情報の表示が異なる場合があります。生成されたクライアントが機密情報であり、標準の認証コードフローを使用できることを確認してください。

2. 発行者と請求内容を確認する

発行者は、Keycloak サーバーのルートではなく、レルムを識別します。この例では、 を使用しますhttps://sso.example.com/realms/company。レルムの OpenID 設定が でアクセス可能であり<issuer>/.well-known/openid-configuration、その公開されている発行者が Synapse に指定する値と完全に一致することを確認してください。

Synapse は、Keycloak アカウントを Matrix ユーザーと関連付けるために、安定した ID クレームを必要とします。通常、その OIDC プロバイダは、OIDC サブジェクト クレームを使用して外部のサブジェクトを識別します。以下のユーザー名マッピングでは、preferred_usernameMatrix のローカルパートとしてこれを使用します。Keycloak が実際にそのクレームを返すこと、およびアカウント ポリシーの下でユーザー名が一意かつ安定していることを確認してください。組織でユーザー名の変更が許可されている場合は、本番環境で使用する前にマッピング戦略を選択してテストしてください。予期しないマッピングの変更は、ユーザーがアクセスする Matrix アカウントに影響を与える可能性があります。

Synapseの設定

3. OIDCプロバイダーを追加する

Synapse のメイン設定にプロバイダーエントリを追加します。通常は ですhomeserver.yaml。他の設定を置き換えるのではなく、既存の YAML とマージします。レルム発行者と実際のクライアントシークレットを置き換えてください。

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 プロセスのみが読み取り可能な状態にしてください。コンテナまたはチャートを使用して Synapse を管理している場合は、上書きされる生成ファイルを編集するのではなく、サポートされている設定ソースにプロバイダ設定を配置してください。

4. バックチャネルログアウトをオプションで設定する

デフォルトでは、あるサービスからログアウトしても、他のすべてのサービスのブラウザセッションが必ずしも終了するとは限りません。Keycloakのログアウト通知でSynapseセッションを終了するには、backchannel_logout_enabled: trueSynapseのKeycloakプロバイダで有効にし、KeycloakのバックチャネルログアウトURLを次のように設定してください。

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

これはオプションであり、ログアウトポリシーとクライアントの設定によって異なります。SynapseからのログアウトとKeycloakからのログアウトの両方向をテストしてください。ElementからのログアウトだけでKeycloakセッションが終了するとは限らないことに注意してください。

5. Synapseを再起動してテストする

デプロイメントの構成チェックを使用して YAML を検証し、パッケージまたはコンテナの設定でサポートされている方法を使用して Synapse を再起動またはリロードします。Synapse のログを確認し、OIDC 検出、クライアント認証、コールバック、またはクレームマッピングのエラーがないか確認してください。最初にテストアカウントを使用して、その Matrix ID と表示名が期待される値であることを確認してください。

要素ウェブの設定

6. SSOをオプションにするか、自動的にリダイレクトする

SynapseがOIDCログインを通知すると、Element WebはSSOログインオプションを表示できるようになります。Elementのsso_redirect_options設定はブラウザのエクスペリエンスを制御するものであり、Keycloakの設定やクライアントシークレットの保存は行いません。config.json認証されていない訪問者がウェルカムページまたはログインページにアクセスした際に、利用可能なSSOフローに誘導したい場合は、 Element Webのservedに次のような設定を追加してください。

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

SSOのみによるサインインが真に必要とされるデプロイメントでは、"immediate": true認証されていないすべてのユーザーに対してSSOを開始するように設定します。これにより、パスワードやその他のログイン方法へのアクセスが難しくなる可能性があるため、適用する前に復旧機能と管理者アクセスをテストしてください。ユーザーがSSOと他の方法を選択する必要がある場合は、自動リダイレクトを無効にしたまま、ログインフローにSSOオプションが表示されることをテストしてください。

SynapseがMatrix認証サービスを使用する場合

MAS は独立した認証サービスであり、Keycloak の OIDC クライアントとして機能します。このアーキテクチャでは、Keycloak のリダイレクト URI を として構成します。https://auth.example.com/upstream/callback/<provider-id>ここで、プロバイダー ID は MAS 構成と一致します。プロバイダーを MAS の の下に構成しますupstream_oauth2.providers。その後、要素はホームサーバーの MAS ベースの認証フローを使用します。このアップストリーム接続には Synapse の を使用しないでください/_synapse/client/oidc/callback。MAS には、認可コード フローをサポートする OIDC プロバイダーが必要です。その構成形式、必要なプロバイダー ID、および移行手順は、Synapse の組み込み とは異なりますoidc_providers。

よくある誤解とその解決策

• 「Elementの設定を変更するだけでいいんです。」 Elementはブラウザのフローを制御し、SynapseまたはMASはOIDCを処理します。まず、適切なホームサーバー側のプロバイダを設定してください。
• 「Keycloakへのログインが成功すれば、アカウントマッピングが正しいことが証明されます。」誤ったlocalpartまたはprofileクレームが選択されていても、認証は成功する可能性があります。非本番環境のユーザーでテストを行い、結果として得られるMatrix IDを確認してください。
• 「SSOはパスワードと登録を自動的に無効にします。」これらのポリシーはホームサーバーとデプロイメントによって制御されます。Synapseのログインと登録の設定を個別に確認し、承認されたポリシーを確認してください。
• 「Elementからログアウトすると、他のすべての場所からもログアウトされてしまう。」ブラウザセッションはKeycloakでアクティブなままになることがあります。集中管理によるセッション終了が必要な場合は、バックチャネルログアウトを設定してテストしてください。

検証チェックリスト

• Keycloakクライアントは、認可コードフロー、クライアント認証、およびSynapseまたはMASの正確なコールバックを使用します。
• 発行者URLはレルムの検出メタデータと一致し、クライアントシークレットはサーバー側に保存されます。
• SynapseまたはMASは、OIDC構成エラーなしで起動し、意図したログイン方法を公開します。
• テストユーザーは、新規のブラウザセッションからサインインし、想定どおりのMatrixアカウントにアクセスして、通常のElementセッションを完了することができます。
• ログアウト動作、既存アカウント、登録制限、および代替管理者アクセスは、お客様のポリシーに準拠している必要があります。

公式資料

• Synapse v1.144 OpenID Connect ガイド（Keycloak クライアントおよびコールバック設定を含む）
• 要素Web設定：SSOリダイレクトオプション
• Matrix Authentication Service: アップストリームSSOプロバイダーの設定
• Keycloak 26.8.0 サーバー管理者ガイド