Matrix Synapseの「SSL証明書の検証に失敗しました」というフェデレーションエラーを修正する

Matrix Synapseでよくある障害は、一見単純に見えます。ローカルクライアントはログインでき、リバースプロキシもオンライン、Synapse自体も正常に見えるにもかかわらず、リモートのホームサーバーがフェデレーションできないという状況です。片側のログにはcertificate verify failed、、、などのフレーズや、TLS検証によって発生した一般的なフェデレーション要求の失敗などhostname mismatchが含まれている場合があります。unable to get local issuer certificate

この問題を解決する最も簡単な方法は、Matrix フェデレーション検出が解決するホスト名とポートを正確にテストし、間違っている証明書、証明書チェーン、または検出パスを修復することです。証明書のチェックを無効にすることから始めないでください。Matrix サーバー間のトラフィックは HTTPS であり、Matrix 仕様では、宛先が信頼できる認証局によって署名された証明書を提示する必要があります。Synapse は、デフォルトで送信フェデレーション証明書の検証を有効にしています。Matrixサーバー間 API 仕様と最新の Synapse 構成ドキュメントを参照してください。

1. フェデレーションが実際に検証しているホスト名を特定します

Nginx、Caddy、Synapse、またはDNSを変更する前に、Matrixが想定する証明書名を確認してください。答えは、あなたの環境server_nameとサーバー検出によって異なります。

Matrix サーバー名が でexample.com、フェデレーションを委任しない場合、他のホームサーバーは通常、その名前に関連付けられたフェデレーション サービス (一般的には TCP 8448) を試みます。 を提供する場合https://example.com/.well-known/matrix/server、 のm.server値は、 などの別のホスト名にフェデレーションを委任できますmatrix.example.com:443。この場合、委任されたホスト名は TLS 検証パスの一部になります。 Matrix は SRV ベースの検出もサポートしていますが、Synapse のドキュメントでは、.well-known理解しやすく正しく構成しやすいため、一般的な展開では委任を推奨しています。権威的な動作については、Matrix 仕様のサーバー検出とSynapse フェデレーション委任のドキュメントに記載されています。

curl -fsS https://example.com/.well-known/matrix/server

委任された応答は次のようになります。

{
  "m.server": "matrix.example.com:443"
}

ファイルが存在しない、または無効な場合でも、それがTLSのバグであると決めつけないでください。Matrixにはフォールバック検出ルールがあります。重要なのは、リモートサーバーが最終的にどのホスト名とポートに接続するかを把握することです。

2. OpenSSLを使用して証明書検証の失敗を再現する

想定されるフェデレーションエンドポイントがわかったら、SNIとホスト名の検証を使って直接テストしてください。これにより、TLS IDの問題とSynapseアプリケーションの問題を切り分けることができます。

openssl s_client   -connect example.com:8448   -servername example.com   -verify_hostname example.com   -showcerts </dev/null

443番ポートで委任されたホストの場合、接続先と想定されるホスト名の両方を変更します。

openssl s_client   -connect matrix.example.com:443   -servername matrix.example.com   -verify_hostname matrix.example.com   -showcerts </dev/null

最終的な検証結果と証明書のサブジェクト代替名に注目してください。TCPおよびTLSプロトコルレベルでは接続が成功しても、ID検証に失敗する可能性があります。そのため、「ポートが開いている」だけでは不十分です。

最も一般的なOpenSSLエラーの意味

• ホスト名の不一致：リバースプロキシが異なるホスト名の証明書を提供したか、検出レコードが証明書でカバーされていないホスト名にフェデレーションを指示しています。
• ローカル発行者証明書を取得できません / 最初の証明書を検証できません:サーバーに証明書チェーン内の中間 CA 証明書が欠落しているか、クライアントの信頼ストアが発行 CA を信頼していないことが原因である可能性があります。
• 証明書の有効期限が切れているか、まだ有効ではありません。証明書を更新するとともに、サーバーと厳密に管理されたプライベートフェデレーションクライアントの両方でシステムクロックを確認してください。
• 自己署名証明書：パブリックフェデレーションでは通常拒否されます。プライベートフェデレーションの場合は、プライベートCAを使用し、検証を全体的に無効にするのではなく、信頼関係を明示的に設定してください。

3. リバースプロキシでのホスト名の不一致を修正する

ホスト名の不一致は、クライアント側のサイトとフェデレーションエンドポイントが異なる仮想ホストを使用している場合に特によく発生します。たとえば、 がexample.comWeb サイトをホストし、 がmatrix.example.comSynapse をプロキシしている場合などです。.well-knownファイルが に委任する場合matrix.example.com:443、そのホスト上の TLS エンドポイントは に対して有効な証明書を提供する必要がありますmatrix.example.com。

Nginxの場合、使用しようとしていた設定ファイルだけでなく、アクティブな仮想ホストを調べてください。

sudo nginx -T | less

、リスニングポート、および証明書パスを確認してくださいserver_name。一般的なTLSセクションでは、完全な証明書チェーンが使用されます。

server {
    listen 443 ssl;
    server_name matrix.example.com;

    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

    location /_matrix {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

設定テストが成功した後にのみ、検証と再読み込みを行ってください。

sudo nginx -t && sudo systemctl reload nginx

Synapseは、一般的なデプロイメントにおいてリバースプロキシの使用を推奨しており、通常のクライアントポート443とデフォルトのフェデレーションポート8448を区別しています。最新のプロキシ要件については、 Synapseの公式リバースプロキシドキュメントを参照してください。

4. 証明書チェーン全体を提供する

リーフ証明書は、既に使用しているブラウザでは正しく表示されていても、サーバーが必要な中間証明書を送信しない場合は、別のホームサーバーでは失敗する可能性があります。Synapse のドキュメントには、Synapse 自体が証明書で構成されているときは、PEM ファイルに完全なチェーンを含める必要があると明記されています。Certbot の場合、これはfullchain.pemだけでなくを使用することを意味しますcert.pem。

TLSがNginx、Caddy、HAProxy、またはその他のプロキシで終端する場合も同じ原則が適用されます。つまり、そのプロキシが正しい完全なチェーンを提示するように設定する必要があります。ディスク上に存在するものだけでなく、実際に提供されているものも確認してください。

openssl s_client   -connect matrix.example.com:443   -servername matrix.example.com   -showcerts </dev/null

リーフ証明書に続いて、必要な中間証明書が表示されるはずです。通常、クライアントは信頼ストアを通じてルートCAを信頼しているため、ルートCAはサーバーから送信する必要はありません。

5. DNSとMatrixディスカバリで古いルーティングや分割されたルーティングがないか確認する。

一方のマシン上の証明書が正しいにもかかわらず、リモートフェデレーションが別の証明書を報告する場合、DNSが一部のクライアントを別の場所に誘導している可能性があります。IPv4とIPv6の両方のレコードを確認し、リモートホームサーバーがIPv6を優先する場合、有効なAレコードがあっても古いAAAAレコードを補うことはできないことに注意してください。

dig +short A example.com
dig +short AAAA example.com
dig +short A matrix.example.com
dig +short AAAA matrix.example.com

また、意図的に使用しているフェデレーションSRVレコードも確認してください。

dig +short SRV _matrix-fed._tcp.example.com

最近設定を変更した場合は.well-known、キャッシュを有効にしてください。Matrix仕様では、クライアントが検出応答や失敗した検出試行を一定期間キャッシュすることが許可されています。つまり、リモートサーバーが以前に検出されたルーティングを一時的に使用し続けていても、現在の設定は正しくても問題ないということです。

AとAAAAの両方が存在する場合は、必要に応じて各ルートに対してTLSチェックを実行します。ロードバランサーが複数のプロキシノードの前面に配置されている場合は、すべてのノードが同じ最新の証明書と証明書チェーンを持っていることを確認します。

6. パブリックフェデレーションを弱体化させることなく、プライベートCA間の信頼関係を修正する

プライベートフェデレーションは、パブリックCAが適切でない主な正当なケースです。Synapseはfederation_custom_ca_listカスタム認証局を提供します。現在のドキュメントには重要な動作が記載されています。このリストは、オペレーティング環境によって提供されるCA証明書を置き換えます。したがって、このリストを設定する場合は、デプロイメントで実際に必要な信頼セット全体を含めるようにしてください。

federation_custom_ca_list:
  - /etc/synapse/ca/private-federation-ca.pem

信頼設定を変更した後は、インストール環境に応じたサービスメカニズムを使用してSynapseを再起動し、ログに証明書エラーがないか確認してください。コンテナ展開の場合も特に注意が必要です。ホストはプライベートCAを信頼しているのに、Synapseコンテナは信頼していない可能性があるためです。信頼マテリアルがコンテナにマウントされていること、および設定されたパスがコンテナ内から読み取り可能であることを確認してください。

Synapse は、federation_certificate_verification_whitelistグローバルfederation_verify_certificatesスイッチも公開していますが、公式ドキュメントでは、これらは例外的なシナリオに限定されています。グローバルに検証を無効にすると、エラーは解消されますが、根本的な ID の問題は解決されないままになる可能性があります。通常のパブリックフェデレーションの場合は、証明書またはルーティングを修復してください。

7. まずTLSレイヤーで修復を確認する

変更を加えた後、以前失敗したOpenSSLコマンドを再度実行してください。目標は、Matrixディスカバリが解決するエンドポイントのホスト名とチェーンの検証を成功させることです。

次に、フェデレーションエンドポイントに対してHTTPSリクエストを行います。8448番ポートの直接エンドポイントの場合：

curl -v https://example.com:8448/_matrix/federation/v1/version

443番ポートの委任エンドポイントの場合：

curl -v https://matrix.example.com/_matrix/federation/v1/version

正常なTLSの結果は、証明書の検証が成功したことを示します。Matrixエンドポイントは、証明書の検証中にエラーになるのではなく、ホームサーバーまたはプロキシパスからHTTPレスポンスを返します。バージョンエンドポイント自体は到達可能性テストに役立ちますが、すべてのルームまたはリモートサーバーが正しくフェデレーションすることを保証するものではありません。

8. Synapseログを確認し、TLSエラーと上位レベルのフェデレーションエラーを区別する。

TLS検証が成功してもフェデレーションが失敗する場合は、証明書の問題として扱うのをやめてください。スタックを遡ってSynapseログを調べ、DNSエラー、接続タイムアウト、HTTPステータスエラー、署名キーの問題、認証エラー、またはリモートサーバーのバックオフがないか確認してください。

systemdベースのインストールでは、一般的な開始点は次のとおりです。

journalctl -u matrix-synapse -n 200 --no-pager

Docker の場合は、Synapse サービスのコンテナログを使用してください。古い証明書メッセージはもはや関連性がない可能性があるため、それに依存するのではなく、新しいフェデレーション試行のタイムスタンプ付近を検索してください。

迅速な意思決定表

問題が本当に解決したかどうかを知る方法

「サービスがエラーなく再起動した」ことを成功基準として使用しないでください。確実な修復には、次の3つの兆候が見られます。正確なフェデレーションホスト名がホスト名検証を通過すること、サービスチェーンが信頼できる認証局（CA）に対して検証されること、そして新しいフェデレーションHTTPSリクエストがTLS検証例外なしにSynapseに到達することです。

これらのチェック後もリモートホームサーバーのうち1台だけが失敗する場合は、キャッシュ、そのリモートサーバーのトラストストア、またはエンドポイント固有のネットワークパスを検討してください。関連性のない多数のパブリックホームサーバーが同様に失敗する場合は、まず自身の証明書、IPv6ルート、ロードバランサーノード、および検出構成を再確認してください。

本番システムでは、証明書の検証を有効にし、証明書の更新状況を可視化してください。根本的な解決策は検証を無効にすることではなく、Matrixディスカバリ、DNS、SNI、リバースプロキシ、および証明書チェーンがすべて同じフェデレーションエンドポイントを記述するようにすることです。