Comment configurer des alias de salle Matrix personnalisés sur votre domaine

Un alias de salle Matrix attribue à une salle une adresse lisible par un humain, telle que `example.com/` #support:example.org. La partie après les deux-points correspond au nom du serveur d'accueil , c'est-à-dire le domaine propriétaire de l'espace de noms de l'alias. Il ne s'agit pas d'une étiquette de domaine arbitraire modifiable par l'ajout d'un enregistrement DNS. Pour utiliser votre propre domaine, votre serveur d'accueil doit être configuré avec ce domaine comme nom de serveur ; la fédération peut alors être déléguée à un hôte distinct.

Ce guide utilise example.orgcomme domaine, matrix.example.orgcomme hôte Synapse et #support:example.orgcomme alias cible. Remplacez ces valeurs par les vôtres. Il se concentre sur une instance Synapse auto-hébergée. Si vous utilisez un fournisseur Matrix hébergé, vérifiez s'il vous permet d'utiliser un nom de serveur personnalisé ; de nombreux comptes hébergés ne peuvent créer d'alias que sous le domaine du fournisseur.

Que fait un alias de salle Matrix ?

Le serveur principal est le serveur Matrix qui stocke les données des salles des utilisateurs et se connecte aux autres serveurs. Un identifiant de salle , tel que !opaqueid:example.org`<nom_de_salle>`, identifie techniquement une salle. Un alias de salle , tel que #support:example.org`<alias_de_salle>`, est une entrée d'annuaire lisible qui correspond à un identifiant de salle et à une liste de serveurs permettant à un utilisateur de s'y connecter.

Un alias ne renomme pas la salle, ne modifie pas sa confidentialité et ne garantit pas sa présence dans un annuaire public des salles. Ces paramètres sont distincts. Une salle peut avoir plusieurs alias. L' alias canonique est l'adresse privilégiée affichée ou partagée par les clients ; il est publié dans l'état de la salle, tandis que le serveur principal gère la correspondance entre les alias et les salles. La spécification Matrix indique que les correspondances d'alias peuvent changer ; il est donc conseillé de vérifier une adresse avant de s'y fier.

Avant de commencer

• Contrôlez le domaine que vous souhaitez utiliser, par exemple example.org, y compris la possibilité de diffuser du contenu HTTPS sur ce domaine.
• Lancez un serveur domestique tel que Synapse avec sa matrice server_namedéfinie sur example.org. Cette valeur est choisie lors de la configuration du serveur et ne doit pas être modifiée ultérieurement à la légère : les identifiants et alias des utilisateurs l'utilisent comme espace de noms.
• Disposez d'un certificat TLS fonctionnel et d'une route de fédération. L'hôte Matrix délégué, tel que matrix.example.org, doit présenter un certificat valide.
• Vous devez être connecté à la salle et disposer des autorisations nécessaires pour modifier ses adresses. Synapse propose également des règles côté serveur permettant d'autoriser ou d'interdire la création d'alias.

Si le serveur est déjà en cours d'exécution sous un autre nom, par exemple `/var/login` provider.net, la création d' #support:example.orgun alias ne constitue pas un raccourci pour la configuration du domaine. Renseignez-vous auprès de votre fournisseur concernant la prise en charge des domaines personnalisés ou prévoyez un déploiement et une migration distincts pour votre serveur d'accueil. Matrix ne propose aucune procédure permettant à un serveur d'accueil de créer des alias dans l'espace de noms d'un autre serveur.

Étape 1 : Choisissez le nom du serveur et la route de fédération

Avant de configurer le serveur d'accueil, choisissez le nom qui apparaîtra après les deux-points. Dans cet exemple, Synapse utilise « /homeserver » example.orgcomme nom de serveur, tandis que ses services client et de fédération s'exécutent à l'adresse « /homeservermatrix.example.org ». Un enregistrement DNS redirige le trafic vers matrix.example.orgl'hôte ou le proxy inverse. Cet enregistrement DNS ne définit pas l'espace de noms d'alias ; c'est le nom du serveur Synapse qui le fait.

Lorsque le serveur principal n'est pas directement accessible example.orgsur le port de fédération par défaut 8448, Matrix doit pouvoir découvrir son point de terminaison de fédération. Une méthode courante consiste à utiliser la délégation .well-known : une courte réponse JSON HTTPS sur le domaine du nom de serveur redirige le trafic de fédération vers l'hôte Matrix réel. Servez-la à l'adressehttps://example.org/.well-known/matrix/server :

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

Assurez-vous que la réponse est au format JSON valide, servie via HTTPS, et que l'hôte cible possède un certificat valide et achemine les requêtes de fédération vers Synapse. Le port peut être omis si le point de terminaison de fédération utilise le port 8448 ; dans cet exemple, le port 443 est spécifié. Si Synapse assure déjà la fédération sur le domaine du nom de serveur au port 8448, la délégation n'est peut-être pas nécessaire. Le /.well-known/matrix/clientfichier côté client constitue un mécanisme de découverte différent et ne remplace pas la délégation côté serveur.

La documentation de configuration actuelle de Synapse propose une serve_server_wellknownoption permettant de rediriger les requêtes vers le domaine du serveur sur le port 443. Utilisez cette option uniquement si votre proxy et le routage de votre domaine sont conformes aux exigences décrites. Dans le cas contraire, configurez la réponse JSON au niveau de votre serveur web ou proxy.

Étape 2 : Vérifier les politiques d’alias de Synapse

Synapse permet de restreindre la création d'alias et les adresses de salles autorisées. Dans la configuration homeserver.yaml, vérifiez alias_creation_rulessi une demande de création d'alias est refusée. Synapse évalue les règles configurées dans l'ordre ; la première règle correspondante tranche la demande, et si aucune règle ne correspond, la demande est refusée. Une liste vide refuse toutes les demandes de création d'alias. Une liste nulle ou omise autorise la création d'alias par défaut, sous réserve d'autres vérifications.

Vérifiez également require_membership_for_aliasesle paramètre par défaut qui exige que l'utilisateur soit dans la salle. Si vous modifiez la configuration de Synapse, suivez la procédure de validation et de redémarrage habituelle de votre déploiement et évitez d'assouplir les règles plus que nécessaire. Le niveau d'accès à la salle et les commandes disponibles sur le client peuvent également influencer la possibilité pour un membre de définir l'alias préféré.

Étape 3 : Créer un alias pour la salle

Rejoignez la salle souhaitée dans un client Matrix et ouvrez ses paramètres. Recherchez la section « Adresse » ou « Alias » ; la formulation et la mise en page peuvent varier selon la version du client. Saisissez l’adresse complète, y compris le #domaine du serveur d’accueil, par exemple : `example.com/ matrix/homeserver/home/homeserver` #support:example.org. Ajoutez-la comme adresse de salle et, si le client le permet, définissez-la comme alias canonique ou préféré. Enregistrez les modifications.

Si votre client ne fournit pas de contrôle d'alias, une requête API client-serveur peut créer le mappage. Le PUT /_matrix/client/v3/directory/room/{roomAlias}point de terminaison authentifié requiert un ID de salle dans le corps de la requête. Par exemple, un membre autorisé de la salle ou un compte serveur peut envoyer une requête au serveur d'accueil propriétaire deexample.org :

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

Remplacez l'identifiant de salle d'exemple par l'identifiant exact de la salle et utilisez un jeton d'accès valide avec l'autorisation requise. Traitez ce jeton comme un mot de passe : ne le publiez pas, ne le collez pas dans une demande d'assistance et ne l'intégrez pas à un système de gestion de versions. Le caractère d'échappement en pourcentage est utilisé dans l'encodage de l'URL #et :pour le chemin HTTP. Une réponse positive indique que le mappage a été créé. Une réponse « déjà utilisé » signifie que le nom est déjà pris ; vérifiez qui en est le propriétaire avant toute modification ou suppression.

Étape 4 : Vérifiez l’adresse et partagez-la

Résolvez l'alias à l'aide de l'API client-serveur publique. Cette recherche ne nécessite aucune authentification.

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

Une réponse positive doit contenir l'identifiant attendu room_idet une serversliste. Comparez l'identifiant de salle renvoyé avec celui de la salle souhaitée. Une erreur 404 signifie que l'alias n'est pas associé au serveur gérant cet espace de noms. Une erreur 400 indique une adresse incorrecte. Testez ensuite l'alias complet dans un autre compte ou client Matrix pour vérifier que la salle est bien résolue et qu'il est possible de la rejoindre conformément à ses règles.

Si vous définissez un alias canonique, vérifiez à nouveau les détails de la salle et assurez-vous que l'adresse préférée est bien celle que vous souhaitez publier. Ne partagez l'alias ou un lien permanent Matrix qu'après avoir vérifié qu'il pointe vers la bonne salle. N'oubliez pas qu'un alias public ne rend pas une salle privée publique ; un utilisateur doit toujours obtenir une autorisation pour la rejoindre.

Problèmes courants à éviter

• Utilisation d'un domaine n'appartenant pas au serveur d'accueil : le nom du serveur dans un alias doit correspondre à l'espace de noms du serveur d'accueil qui le crée. Un enregistrement CNAME DNS seul ne peut pas autoriser le domaine d'un autre serveur.
• Confondre le domaine et l'hôte : example.org il peut s'agir de l'espace de noms d'alias tandis que matrix.example.orgl'hôte du service est spécifié. Configurez le nom du serveur Synapse et la délégation de manière appropriée.
• Emplacement incorrect du fichier de découverte client : la délégation de fédération utilise /.well-known/matrix/serverun emplacement différent. Le fichier de découverte client a un chemin et un objectif différents.
• Si un alias publie une salle publiquement : la résolution d’alias et la publication publique dans l’annuaire des salles sont des opérations distinctes régies par des politiques distinctes.
• Modification du nom du serveur sur un déploiement existant : les identifiants Matrix existants dépendent de cet espace de noms. Considérez un changement de domaine comme une migration architecturale, et non comme une simple configuration d’alias.
• Partage sans vérification de la correspondance : résolvez l’alias et comparez l’identifiant de salle renvoyé avant de publier. Une adresse lisible est pratique, mais c’est la correspondance du serveur qui détermine la destination.

Pour plus de détails sur le protocole, consultez le format des identifiants et alias Matrix ainsi que l' API des alias de salles Matrix . Pour la configuration de Synapse, reportez-vous au guide de délégation de fédération et au manuel de configuration d'Element . Les options et l'interface client de Synapse peuvent varier d'une version à l'autre ; consultez la documentation de la version que vous utilisez.