Lors de la fédération, les journaux de Matrix Synapse SSL: CERTIFICATE_VERIFY_FAILEDpeuvent révéler des problèmes : blocage lors de la connexion, rejet de la connexion par un serveur distant ou non-réception des messages. Commencez par identifier le certificat défaillant : celui du serveur distant lors d'une requête sortante ou celui de votre point de terminaison de fédération lors de la connexion d'un autre serveur. Corrigez ensuite la chaîne de certificats, le nom d'hôte ou la configuration de confiance identifiés par les journaux et un test de fédération. La désactivation de la vérification TLS n'est pas une solution générale.
Le trafic serveur à serveur de Matrix utilise HTTPS, et la spécification Matrix exige que la destination présente un certificat TLS signé par une autorité de certification reconnue. Une erreur de vérification signifie généralement que le certificat présenté est expiré, incomplet, émis pour un nom d'hôte différent ou signé par une autorité de certification à laquelle le serveur de connexion ne fait pas confiance. Un proxy inverse peut également servir un certificat incorrect même si la configuration de Synapse semble correcte.
1. Identifiez le côté défaillant avant de modifier la configuration.
Consultez le journal Synapse relatif à l'erreur et notez le nom du serveur distant ainsi que l'erreur de certificat exacte. Si Synapse signale l'erreur lors d'une requête vers un autre serveur d'accueil, le certificat du serveur distant ou l'autorité de certification utilisée par votre processus Synapse est probablement en cause. Si d'autres serveurs ne peuvent pas se fédérer avec votre domaine, examinez plutôt votre point de terminaison TLS public et la découverte des serveurs.
Vérifiez le nom de votre serveur Matrix homeserver.yaml, en particulier `/etc/matrix.json` server_name. Il s'agit du domaine de votre identifiant Matrix local, qui détermine comment les autres serveurs peuvent vous joindre. Ne le confondez pas avec le nom d'hôte interne de votre machine ou conteneur. La documentation d'installation de Synapse explique que le nom du serveur est une identité de fédération et recommande de le choisir avant l'installation.
2. Tester le certificat public et la route de fédération
Utilisez l' outil de test de fédération Matrix avec le nom de votre serveur Matrix. Il vérifie la découverte de la fédération et la connectivité, et peut révéler si le certificat visible de l'extérieur ou le routage présente une défaillance. Corrigez l'élément identifié avant de modifier les paramètres de confiance sortante de Synapse.
Depuis une machine pouvant accéder à votre point de terminaison de fédération, examinez le certificat TLS. Remplacez ` matrix.example.org<hostname>` par le nom d'hôte qui doit présenter le certificat et indiquez le port de fédération utilisé. Le port 8448 est courant, mais un proxy inverse ou un serveur délégué peut utiliser un autre port.
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org -showcerts </dev/null
Cette -servernameoption envoie l'indication du nom de serveur (SNI), permettant ainsi à un proxy virtuel de choisir le certificat correspondant au nom demandé. Vérifiez que la vérification a réussi, puis examinez le sujet et la date de validité du certificat.
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org </dev/null 2>/dev/null | \
openssl x509 -noout -subject -issuer -dates -ext subjectAltName
Le nom utilisé par la fédération Matrix doit correspondre à un nom DNS figurant dans le champ « Subject Alternative Name » du certificat. Vérifiez également la validité du certificat et assurez-vous que le point de terminaison transmet bien ses certificats intermédiaires. Si vous utilisez un proxy inverse, testez son adresse publique : un certificat valide sur l’hôte Synapse est inutile si le proxy utilise un certificat obsolète ou non pertinent.
3. Corrigez le certificat servi par Synapse.
Si le testeur signale un problème de certificat pour votre serveur, renouvelez ou réémettez le certificat du nom d'hôte de la fédération et configurez le point de terminaison TLS public pour qu'il prenne en charge la chaîne complète. Le manuel de configuration actuel de Synapse précise que ce tls_certificate_pathpoint de terminaison doit pointer vers un certificat PEM incluant les certificats intermédiaires ; pour Certbot, utilisez `<nom_du_certificat_PEM>` fullchain.pem, et non `<nom_du_certificat_PEM> cert.pem`. Conservez la clé privée dans un tls_private_key_pathfichier séparé et protégez-la de tout accès public.
Lorsque la connexion TLS s'arrête au niveau de Nginx, Caddy ou d'un autre proxy inverse, mettez à jour le certificat et la chaîne dans la configuration de ce proxy, puis rechargez-le en utilisant la méthode appropriée à votre installation. Dans cette configuration, les chemins de certificat TLS de Synapse peuvent ne pas contrôler le certificat vu par les pairs de la fédération. Suivez la documentation officielle de Synapse relative aux proxys inverses pour la configuration du serveur et du proxy que vous utilisez.
Vérifiez également la découverte DNS et le serveur Matrix. La fédération peut résoudre directement le nom de votre serveur ou suivre une /.well-known/matrix/serverdélégation vers un autre nom d'hôte et un autre port. Le certificat doit être valide pour le nom d'hôte atteint par cette voie de découverte. Un enregistrement DNS obsolète ou une délégation incorrecte peut diriger les pairs vers un point de terminaison présentant un certificat non valide.
4. Rétablir la confiance sortante pour une fédération privée
Si le certificat défaillant appartient à un serveur distant sur un réseau privé, vérifiez d'abord qu'il a bien été émis par votre autorité de certification (AC) privée. Installez et gérez cette AC sur l'hôte Synapse lorsque cela est possible. Synapse prend également federation_custom_ca_listen charge les certificats d'AC personnalisés pour la fédération. Cette option attend des fichiers PEM et remplace la liste des AC fournie par le système d'exploitation ; assurez-vous donc d'inclure toutes les AC nécessaires à votre déploiement plutôt que d'ajouter une seule AC privée sans discernement.
federation_custom_ca_list:
- /etc/matrix-synapse/certs/private-root-ca.pem
Indiquez le chemin d'accès à un certificat d'autorité de certification, et non à la clé privée du serveur. Assurez-vous que le processus Synapse peut le lire, vérifiez l'indentation YAML, puis redémarrez ou rechargez Synapse selon votre méthode de déploiement. Le manuel de configuration de Synapse précise que cette option est généralement destinée aux réseaux domestiques privés.
Ne pas configurer cette option federation_verify_certificates: falsepour masquer une erreur de fédération publique. Son comportement par défaut est truedésactivé ; la désactiver supprime la vérification des certificats pour la fédération sortante et affaiblit la protection contre l'usurpation d'identité. Cette option distincte federation_certificate_verification_whitelistest réservée à des cas spécifiques et limités, tels que les services cachés Tor ou les configurations privées contrôlées, et ne remplace pas la réparation d'un certificat public. Pour une infrastructure privée, une autorité de certification privée de confiance est généralement préférable.
5. Vérifier l'heure et refaire le test
Si les dates de certificat apparaissent invalides alors que le certificat est à jour, vérifiez l'horloge système et la synchronisation horaire sur l'hôte Synapse et tout proxy. Un décalage horaire important peut faire apparaître un certificat valide comme invalide ou expiré. Assurez-vous également que le renouvellement automatique a bien mis à jour le fichier accessible publiquement ; le renouvellement du certificat sur disque ne garantit pas son rechargement par le proxy.
Après la correction, relancez le testeur de fédération et répétez la connexion qui a échoué. Vérifiez que le testeur affiche bien le nom d'hôte attendu, des dates valides et une chaîne de confiance. Consultez ensuite les journaux Synapse pour détecter d'éventuelles nouvelles tentatives de fédération sans erreur de vérification de certificat. Si le testeur réussit mais qu'un serveur distant échoue toujours, notez son nom, l'horodatage et l'entrée de journal correspondante (anonymisée) : son propre certificat ou environnement de confiance pourrait être à l'origine du problème. Ne partagez ni clés privées, ni jetons d'accès, ni le contenu des messages utilisateur pendant le dépannage.