Rendez votre serveur Matrix Synapse accessible pour la fédération

Pour fédérer un serveur Matrix Synapse, assurez-vous que son nom de serveur soit accessible depuis Internet via HTTPS, puis redirigez les requêtes entre serveurs Matrix vers Synapse. Dans une configuration courante, un proxy inverse gère le protocole TLS sur le port 443 et un /.well-known/matrix/serverfichier de configuration configure votre domaine Matrix pour pointer vers ce proxy. Si Synapse répond déjà sur le port 8448 de votre domaine, la délégation n'est peut-être pas nécessaire.

Ce guide utilise example.comcomme nom de serveur Matrix permanent et matrix.example.comcomme machine ou point de terminaison proxy. Remplacez ces deux noms par les vôtres. Un serveur d'accueil stocke les comptes et les salles Matrix ; la fédération permet aux serveurs d'accueil de communiquer entre eux. La configuration DNS, les règles de pare-feu, la syntaxe du proxy, le réseau des conteneurs et les certificats dépendent de votre hôte.

Avant de modifier la configuration

Choisissez le format des identifiants Matrix des utilisateurs : `<nom_utilisateur>` @name:example.comou ` <nom_utilisateur> @name:matrix.example.com`. La valeur de ` server_name<nom_utilisateur>` homeserver.yamlsera intégrée aux identifiants Matrix et aux adresses des salles. La documentation d'installation de Synapse recommande de faire ce choix avant l'installation, car toute modification ultérieure aura des conséquences. Si Synapse est déjà utilisé, ne modifiez pas `<nom_utilisateur>` simplement pour qu'il corresponde à une adresse web ; utilisez la délégation pour conserver les identifiants existants.

Un éditeur YAML affiche server_name : example.com et un rappel invitant à choisir la valeur avant l’installation.
Le nom du serveur fait partie des identifiants Matrix, veuillez donc le confirmer avant de continuer.

Avant toute modification, assurez-vous de pouvoir accéder à Synapse, au proxy et au DNS public, et de disposer d'un certificat TLS valide pour le point de terminaison de fédération. Sauvegardez homeserver.yamlla clé de signature, qui établit l'identité du serveur principal. Conservez cette clé en lieu sûr ; la configuration standard de la fédération ne nécessite pas sa régénération.

Mettre en place la voie publique

1. Confirmer l'écouteur HTTP de Synapse

Synapse écoute généralement le trafic HTTP sur un port 8008situé derrière un proxy inverse. Dans le composant qui accepte le trafic du proxy, configurez Synapse pour qu'il puisse utiliser l'adresse et le schéma du client transféré par le proxy. Le proxy doit définir les en - têtes x_forwarded: trueappropriés , plutôt que de transmettre des valeurs arbitraires fournies par des clients externes.X-Forwarded-ForX-Forwarded-Proto

Un extrait d'écouteur YAML montre Synapse sur le port HTTP 8008 avec x_forwarded activé et une adresse de liaison de bouclage.
Le module d'écoute accepte les requêtes HTTP provenant d'un proxy local et active la gestion des en-têtes transférés par Synapse.

L'utilisation de cette méthode 127.0.0.1est appropriée lorsque le proxy s'exécute sur le même hôte. Elle n'est pas adaptée si le proxy se trouve dans un autre conteneur ou sur une autre machine, sauf si cette adresse est accessible depuis le proxy. Dans un déploiement conteneurisé, utilisez l'adresse réseau ou le nom de service accessible par le proxy et limitez l'accès via le réseau du conteneur ou le pare-feu. Conservez la structure d'écoute existante et modifiez les valeurs pertinentes ; ne copiez pas un fragment de configuration sans l'adapter au reste de votre configuration.

2. Chemins de la matrice de routage via le proxy

Configurez l'hôte virtuel HTTPS du proxy pour rediriger les deux chemins /_matrixvers /_synapse/clientl'écouteur HTTP de Synapse. Le premier chemin transporte les API Matrix, notamment la fédération ; le second est utilisé pour les points de terminaison clients de Synapse. Suivez l'exemple officiel de votre logiciel proxy, conservez le chemin de la requête et envoyez les en-têtes attendus par Synapse. Ne normalisez, ne décodez ni ne réécrivez les chemins d'URI : les signatures des requêtes Matrix peuvent échouer si un proxy modifie le chemin encodé.

Un éditeur de configuration de proxy inverse affiche les chemins d'accès à l'API Matrix et au client Synapse routés vers le port 8008 de l'hôte local avec les en-têtes transférés.
Le proxy doit transmettre les deux chemins d'accès à l'API Matrix à Synapse sans réécrire l'URI.

La configuration exacte diffère selon le fournisseur (Nginx, Caddy, Apache, équilibreur de charge, hébergement géré). Utilisez la syntaxe actuelle du fournisseur et la documentation du proxy inverse Synapse comme référence. Une règle de proxy qui dessert le client web mais omet le chemin d'accès à l'API de fédération est insuffisante.

3. Assurez-vous que le DNS, le protocole HTTPS et le port choisi correspondent.

Dans cet exemple, l' matrix.example.comadresse IP doit pointer vers le proxy ou l'équilibreur de charge, et le port 443doit être accessible depuis l'extérieur. Le proxy nécessite un certificat valide pour l' adresse IP matrix.example.com. Si vous gérez la fédération directement à l'adresse IP example.com:8448, publiez cette route et ce certificat, puis ouvrez le port 8448. Utilisez soit le port 8448 (port par défaut classique), soit la délégation vers un autre hôte et un autre port, par exemple le port 443.

Vérifiez les règles DNS, de pare-feu ou de groupe de sécurité cloud, ainsi que le certificat externe à votre réseau privé. Si un CDN ou un tunnel est utilisé, sa compatibilité avec le trafic Matrix requis dépend de sa configuration actuelle ; consultez sa documentation et testez le routage réel plutôt que de présumer de sa compatibilité.

Publier la découverte de fédération en cas de besoin

4. Ajouter une délégation de serveur pour un point de terminaison distinct

Si le domaine de l'identifiant Matrix est example.comdifférent de celui de Synapse matrix.example.com:443, ce JSON sera servi via HTTPS à l'adressehttps://example.com/.well-known/matrix/server :

{
  "m.server": "matrix.example.com:443"
}
Une vue JSON de style navigateur à l'adresse example.com/.well-known/matrix/server contient la valeur m.server matrix.example.com:443.
Cet enregistrement de découverte de fédération délègue example.com au point de terminaison HTTPS à matrix.example.com sur le port 443.

Le port 443 est explicitement indiqué dans cet exemple ; si vous omettez un port, la découverte Matrix utilisera par défaut le port 8448. Ne confondez pas ce fichier avec le fichier ` /.well-known/matrix/clientserverwell-known.conf`, qui permet aux clients de trouver l'API client-serveur et est indépendant de la fédération serveur à serveur. Synapse peut diffuser lui-même un fichier `serverwell-known.conf` lorsque le domaine du nom de serveur est routé directement vers Synapse, mais avec un point de terminaison distinct, vous publiez généralement le fichier sur le serveur web du domaine du nom de serveur.

La découverte de fédération est définie par Matrix et documentée par Synapse. La spécification Matrix autorise la découverte via/.well-known/matrix/server ; consultez les instructions de délégation de Synapse avant de choisir une autre méthode, comme un enregistrement SRV, qui influe également sur les attentes TLS.

Test effectué depuis l'extérieur du serveur

5. Vérifiez l'enregistrement, puis effectuez une vérification de fédération.

Demandez l'URL de découverte depuis une machine située hors du réseau privé du serveur. Elle devrait renvoyer l'objet JSON ci-dessus via HTTPS, sans page de connexion, redirection HTML, avertissement de certificat ni site web non pertinent. Vérifiez ensuite que le nom d'hôte délégué est résolu, que son certificat est valide et que son port annoncé est accessible par Synapse. Avant de tester, utilisez l'outil de vérification de configuration de votre proxy et effectuez un rechargement.

Enfin, saisissez le nom de votre serveur (par exemple, ` example.commatrix_host`, et non le nom d'hôte délégué, sauf s'il s'agit de votre serveur server_name) dans l' outil de test de fédération Matrix officiel . Le guide de fédération Synapse suggère également de tester en rejoignant une salle publique telle que ` #synapse:matrix.orgmatrix_host`. Un test réussi confirme que les vérifications de découverte et d'accessibilité courantes ont été effectuées ; il ne garantit cependant pas le bon fonctionnement de tous les serveurs distants ni de toutes les opérations de salle, car les politiques distantes et les conditions réseau varient.

Si le testeur signale que votre serveur est inaccessible, vérifiez le domaine et le port utilisés, la configuration DNS, les règles de pare-feu, le nom du certificat, les chemins de proxy, les en-têtes transférés et si une redirection a modifié la requête. La documentation actuelle de la fédération Synapse indique clairement que les serveurs fédérateurs de Synapse peuvent ne pas suivre les redirections HTTP 308 dans certains cas. Évitez de vous fier à une redirection 308 pour le point de terminaison de la fédération et effectuez un nouveau test après avoir corrigé le problème. Consultez la documentation correspondant à votre version de Synapse pour connaître le comportement spécifique à cette version.

La fédération nécessite que les serveurs distants découvrent et accèdent à votre API de fédération. La configuration seule ne permet pas de vérifier si cela fonctionne pour chaque serveur distant. Confirmez le chemin d'accès avec un testeur et une connexion à une salle réelle, puis examinez le point de terminaison défaillant ou l'erreur spécifique.

Ces panneaux d'interface sont des exemples schématiques de données de configuration et de découverte, et non des captures d'écran d'un serveur en production. Références documentaires vérifiées le 10 octobre 2026.

Laisser un commentaire

Résoudre les erreurs d'autorisation d'administrateur de la salle Matrix par action

Identifiez l'origine de M_FORBIDDEN en fonction des niveaux de puissance de la salle, des membres ou de l'accès administrateur du serveur Synapse, puis rétablissez uniquement l'autorisation nécessaire à l'action bloquée.

Rendez votre serveur Matrix Synapse accessible pour la fédération

Rendez votre serveur Matrix Synapse accessible pour la fédération

Configurez la découverte Synapse, le protocole HTTPS et le routage proxy pour que les autres serveurs domotiques Matrix puissent trouver votre serveur et le contacter.

Connectez Element Web à Keycloak via Synapse OIDC

Configurez un client Keycloak OIDC et un fournisseur Synapse afin que les utilisateurs d'Element Web puissent se connecter via votre serveur d'identité sans exposer les secrets du client.

Configurez la sauvegarde des clés et la signature croisée en toute sécurité

Configurez la sauvegarde des clés et la signature croisée en toute sécurité

Sauvegardez une clé de récupération, vérifiez vos sessions Element et assurez-vous que les clés de messages chiffrés peuvent être restaurées sans confondre la sauvegarde avec le mot de passe de votre compte.

Résolution des problèmes de mémoire de Matrix Synapse lors de la synchronisation du client

Diagnostiquer les échecs de synchronisation de Synapse (faute de mémoire), ajuster la mise en cache en toute sécurité, identifier les arriérés de requêtes et vérifier une utilisation stable de la mémoire.

Résoudre les erreurs de certificat TLS de la fédération Synapse

En cas de défaillance du certificat de fédération Trace Matrix, remontez jusqu'au serveur approprié, réparez la chaîne TLS ou la confiance de l'autorité de certification et vérifiez la correction sans désactiver les contrôles de sécurité.

Installez un serveur Synapse Matrix derrière Cloudflare en toute sécurité

Installez un serveur Synapse Matrix derrière Cloudflare en toute sécurité

Les clients Route Matrix et la fédération via Cloudflare sur HTTPS 443 préservent la découverte Synapse et évitent la mise en cache du trafic API ou l'interruption des chargements de médias.

Restaurez Matrix Synapse en toute sécurité à l'aide d'une sauvegarde PostgreSQL.

Sauvegardez Synapse avec pg_dump, protégez sa clé de signature et son support, et restaurez-le dans une base de données PostgreSQL propre sans réutiliser de clés à usage unique obsolètes.

Exécutez Mjölnir comme bot de modération de salle Matrix avec Docker

Exécutez Mjölnir comme bot de modération de salle Matrix avec Docker

Configurez Mjölnir avec un compte Matrix dédié, une salle de gestion chiffrée, Docker Compose, une liste de politiques et des contrôles d'autorisation.

Activez la synchronisation matricielle native pour un chargement mobile plus rapide

Activez la synchronisation matricielle native pour un chargement mobile plus rapide

Ignorez le proxy obsolète et configurez la synchronisation glissante intégrée de Synapse. Vérifiez la détection des clients, puis mesurez le chargement de la liste des salons et le comportement de reconnexion sur un téléphone compatible.