Cómo configurar alias de salas Matrix personalizadas en su dominio

Un alias de sala de Matrix le asigna a una sala una dirección legible, como #support:example.org. La parte que aparece después de los dos puntos es el nombre del servidor del servidor principal , el dominio propietario del espacio de nombres del alias. No se trata de una etiqueta de dominio arbitraria que se pueda modificar añadiendo un registro DNS. Para usar su propio dominio, su servidor principal debe estar configurado con ese dominio como nombre de servidor; la federación se puede delegar a un host independiente.

Esta guía utiliza example.orgcomo dominio, matrix.example.orgcomo host de Synapse y #support:example.orgcomo alias de destino. Reemplace estos marcadores de posición con sus propios valores. Se centra en Synapse autoalojado. Si utiliza un proveedor de Matrix alojado, compruebe si le permite usar un nombre de servidor personalizado; muchas cuentas alojadas solo pueden crear alias bajo el dominio del proveedor.

¿Qué hace un alias de habitación de Matrix?

Un servidor principal es el servidor Matrix que almacena los datos de las salas de los usuarios y se conecta a otros servidores. Un ID de sala , como !opaqueid:example.org, identifica técnicamente una sala. Un alias de sala , como #support:example.org, es una entrada de directorio legible que se resuelve en un ID de sala y una lista de servidores que pueden ayudar a un usuario a unirse.

Un alias no cambia el nombre de la sala, ni su privacidad, ni garantiza que aparezca en un directorio público de salas. Estas son configuraciones de sala independientes. Una sala puede tener varios alias. Un alias canónico es la dirección preferida que muestran o comparten los clientes; se publica como estado de la sala, mientras que el servidor principal mantiene la correspondencia entre el alias y la sala. La especificación Matrix advierte que las correspondencias de alias pueden cambiar, por lo que conviene resolver una dirección antes de confiar en ella.

Antes de comenzar

• Controla el dominio que quieres usar, como por ejemplo example.org, incluyendo la capacidad de servir contenido HTTPS en ese dominio.
• Ejecuta un servidor doméstico como Synapse con su matriz server_nameconfigurada en example.org. Este valor se elige cuando se configura el servidor y no debe cambiarse posteriormente sin más: los ID de usuario y los alias lo utilizan como su espacio de nombres.
• Disponer de un certificado TLS y una ruta de federación que funcionen. El host delegado de Matrix, como por ejemplo matrix.example.org, debe presentar un certificado válido.
• Debes estar unido a la sala y tener los permisos necesarios para cambiar sus direcciones. Synapse también cuenta con reglas del servidor que permiten o deniegan la creación de alias.

Si el servidor ya está funcionando con un nombre de servidor diferente, por ejemplo provider.net, crear #support:example.orgun nuevo dominio no es un atajo para la asignación de dominios. Consulte con el proveedor sobre la compatibilidad con dominios personalizados o planifique una implementación y migración de servidor doméstico independiente. Matrix no define un proceso para que un servidor doméstico cree alias en el espacio de nombres de otro servidor.

Paso 1: Elija el nombre del servidor y la ruta de federación.

Decida qué nombre aparecerá después de los dos puntos antes de configurar el servidor principal. En este ejemplo, Synapse usa example.orgcomo nombre de servidor, mientras que sus servicios de cliente y federación se ejecutan en matrix.example.org. Un registro DNS envía el tráfico para matrix.example.orgal host o proxy inverso. El registro DNS por sí solo no establece el espacio de nombres de alias; lo hace el nombre del servidor de Synapse.

Cuando el servidor principal no es directamente accesible en example.orgel puerto de federación predeterminado 8448, Matrix necesita una forma de descubrir su punto final de federación. Un método común es la delegación .well-known : una pequeña respuesta JSON HTTPS en el dominio server-name dirige el tráfico de federación al host real de Matrix. Sirva esto en https://example.org/.well-known/matrix/server:

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

Asegúrese de que la respuesta sea JSON válido, se sirva a través de HTTPS y que el host de destino tenga un certificado válido y enrute las solicitudes de federación a Synapse. El puerto se puede omitir cuando el punto final de federación usa el puerto 8448; en este ejemplo, se especifica el puerto 443. Si Synapse ya ofrece federación en el dominio server-name en el puerto 8448, es posible que no se necesite la delegación. El /.well-known/matrix/clientarchivo del cliente es un mecanismo de descubrimiento diferente y no sustituye la delegación del servidor.

La documentación de configuración actual de Synapse incluye la serve_server_wellknownopción para los casos en que las solicitudes al dominio server-name en el puerto 443 se enrutan a Synapse. Utilice esta opción solo si su proxy y el enrutamiento del dominio cumplen con los requisitos documentados. De lo contrario, configure la respuesta JSON en su servidor web o proxy.

Paso 2: Compruebe las políticas de alias de Synapse.

Synapse puede restringir quién puede crear alias y qué direcciones de sala están permitidas. En homeserver.yaml, compruebe alias_creation_rulessi se deniega una solicitud de creación de alias. Synapse evalúa las reglas configuradas en orden; la primera regla que coincida decide la solicitud, y si ninguna coincide, la solicitud se deniega. Una lista vacía deniega todas las solicitudes de creación de alias. Una lista nula u omitida permite la creación de alias por defecto, sujeta a otras comprobaciones.

Compruebe también require_membership_for_aliasesque, por defecto, requiere que el usuario esté en la sala. Si modifica la configuración de Synapse, siga el proceso normal de validación y reinicio de su implementación y evite flexibilizar la política más de lo necesario. Los niveles de energía de la sala y los controles disponibles del cliente también pueden afectar a la posibilidad de que un miembro habitual establezca el alias preferido.

Paso 3: Crea un alias para la sala.

Únete a la sala deseada en un cliente Matrix y abre su configuración. Busca la sección de dirección o alias; la redacción y el diseño del cliente pueden variar según la versión. Introduce la dirección completa, incluyendo el prefijo #y el dominio del servidor principal, por ejemplo #support:example.org, . Añádela como dirección de sala y, si el cliente ofrece la opción, configúrala como alias canónico o preferido. Guarda los cambios.

Si su cliente no proporciona un control de alias, una solicitud de API cliente-servidor puede crear la asignación. El PUT /_matrix/client/v3/directory/room/{roomAlias}punto final autenticado requiere un ID de sala en el cuerpo de la solicitud. Por ejemplo, un miembro de sala autorizado o una cuenta de servidor puede enviar una solicitud al servidor principal que posee example.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"}'

Reemplace el ID de sala de ejemplo con el ID exacto de la sala y utilice un token de acceso válido con la autorización necesaria. Trate el token como una contraseña: no lo publique, no lo pegue en una publicación de soporte ni lo incluya en el control de versiones. El símbolo de porcentaje se utiliza en la codificación URL #y :en la ruta HTTP. Una respuesta exitosa indica que la asignación se creó correctamente. Una respuesta de "ya existe" significa que el nombre está en uso; confirme quién es el propietario antes de realizar cualquier cambio o eliminación.

Paso 4: Verifica la dirección y compártela.

Resuelva el alias utilizando la API pública cliente-servidor. Esta búsqueda no requiere autenticación.

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

Una respuesta exitosa debería contener la información esperada room_idy una serverslista. Compare el ID de sala devuelto con el de la sala deseada. Un error 404 significa que el alias no tiene ninguna asignación en el servidor que gestiona ese espacio de nombres. Un error 400 indica una dirección con formato incorrecto. A continuación, pruebe el alias completo en una segunda cuenta o cliente de Matrix para confirmar que la sala se resuelve y que se puede acceder a ella según sus reglas de acceso.

Si configuras un alias canónico, revisa los detalles de la sala y confirma que la dirección preferida sea la que deseas publicar. Comparte el alias o un enlace permanente de Matrix solo después de confirmar que dirige a la sala correcta. Recuerda que un alias público no convierte una sala privada en pública; el usuario aún necesita permiso para unirse.

Problemas comunes que se deben evitar

• Si se utiliza un dominio que no pertenece al servidor principal: el nombre del servidor en un alias debe coincidir con el espacio de nombres del servidor principal que lo crea. Un registro DNS CNAME por sí solo no puede autorizar el dominio de otro servidor.
• Mezclar el dominio y el host: example.org puede ser el espacio de nombres del alias, mientras que matrix.example.orges el host del servicio. Configure el nombre del servidor Synapse y la delegación de forma deliberada.
• Colocar el archivo de descubrimiento de clientes en el lugar incorrecto: la delegación de federación utiliza /.well-known/matrix/server. El archivo de descubrimiento de clientes tiene una ruta y un propósito diferentes.
• Suponiendo que un alias publique una sala públicamente: la resolución de alias y la publicación en el directorio público de salas son operaciones separadas regidas por políticas separadas.
• Cambio del nombre del servidor en una implementación establecida: Los ID de Matrix existentes dependen de ese espacio de nombres. Considere un cambio de dominio como una migración arquitectónica, no como una simple configuración de alias.
• Compartir sin verificar la asignación: Resuelva el alias y compare el ID de sala devuelto antes de publicarlo. Una dirección legible es conveniente, pero la asignación del servidor es lo que determina a dónde conduce.

Para obtener detalles sobre el protocolo, consulte el formato de identificador y alias de Matrix y la API de alias de sala de Matrix . Para la configuración de Synapse, consulte la guía de delegación de federación y el manual de configuración de Element . Las opciones de Synapse y las pantallas del cliente pueden variar entre versiones; consulte la documentación de la versión que utiliza.