Cuando los registros de Matrix Synapse muestran errores SSL: CERTIFICATE_VERIFY_FAILEDdurante la federación, es posible que la conexión se bloquee, que un servidor remoto rechace la conexión o que no lleguen los mensajes. Primero, determine qué certificado está fallando: el certificado de un servidor remoto durante una solicitud saliente o el certificado de su propio punto final de federación cuando otro servidor se conecta. Luego, repare la cadena de certificados, el nombre de host o la configuración de confianza que identifiquen el registro y una prueba de federación. No desactive la verificación TLS como solución general.
El tráfico entre servidores de Matrix utiliza HTTPS, y la especificación de Matrix exige que el destino presente un certificado TLS firmado por una autoridad de certificación reconocida. Un error de verificación suele indicar que el certificado presentado ha caducado, está incompleto, se ha emitido para un nombre de host diferente o está firmado por una CA en la que el servidor que se conecta no confía. Un proxy inverso también puede servir un certificado incorrecto, incluso cuando la configuración de Synapse parece correcta.
1. Identifique el lado que falla antes de cambiar la configuración.
Revise el registro de Synapse correspondiente al fallo y anote el nombre del servidor remoto y el error exacto del certificado. Si Synapse informa del fallo al realizar una solicitud a otro servidor principal, el problema podría estar en el certificado del servidor remoto o en la confianza de la CA utilizada por su proceso Synapse. Si otros servidores no pueden federarse con su dominio, inspeccione su punto final TLS público y la detección de servidores.
Confirme el nombre de su servidor Matrix desde homeserver.yaml, especialmente server_name. Esta es la parte del dominio de las ID locales de Matrix y determina cómo otros servidores domésticos se comunican con usted. No lo confunda con el nombre de host interno de la máquina o contenedor. La documentación de instalación actual de Synapse explica que el nombre del servidor es una identidad de federación y recomienda seleccionarlo antes de la instalación.
2. Probar el certificado público y la ruta de federación.
Utilice el comprobador de federación de Matrix con el nombre de su servidor Matrix. Este comprueba la detección de la federación y la conectividad, y puede revelar si el certificado visible externamente o el enrutamiento están fallando. Solucione el problema que identifique antes de ajustar la configuración de confianza de salida de Synapse.
Desde una máquina que pueda acceder a su punto final de federación, inspeccione el certificado TLS. Reemplace matrix.example.orgcon el nombre de host que debería presentar el certificado y utilice su puerto de federación real. El puerto 8448 es común, pero un proxy inverso o un servidor delegado podría usar otro puerto.
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org -showcerts </dev/null
Esta -servernameopción envía SNI (Indicación de Nombre de Servidor), de modo que un proxy virtualizado pueda seleccionar el certificado para el nombre solicitado. Compruebe la salida para verificar que la verificación sea exitosa y, a continuación, examine el sujeto y las fechas de validez del certificado.
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
El nombre utilizado por la federación Matrix debe coincidir con un nombre DNS en el Nombre Alternativo del Sujeto del certificado. Compruebe también que el certificado sea válido y que el punto final envíe sus certificados intermedios. Si utiliza un proxy inverso, pruebe la dirección pública del proxy: un archivo de certificado correcto en el host de Synapse no sirve de nada si el proxy proporciona un certificado obsoleto o irrelevante.
3. Corrige el certificado que proporciona Synapse.
Si el probador informa de un problema con el certificado de su servidor, renueve o vuelva a emitir el certificado para el nombre de host de la federación y configure el punto final TLS público para que sirva la cadena completa. El manual de configuración actual de Synapse especifica que tls_certificate_pathdebe apuntar a un certificado PEM que incluya certificados intermedios; para Certbot, use fullchain.pem, no cert.pem. Mantenga la clave privada en un archivo separado tls_private_key_pathy protéjala del acceso público.
Cuando TLS finaliza en Nginx, Caddy u otro proxy inverso, actualice el certificado y la cadena en la configuración de dicho proxy y, a continuación, recargue el proxy utilizando el método adecuado para su instalación. Es posible que las rutas de certificado TLS de Synapse no controlen el certificado que ven los pares de federación en esta configuración. Siga la documentación oficial del proxy inverso de Synapse para la configuración del oyente y del proxy que utilice.
Verifique también el DNS y el descubrimiento del servidor Matrix. La federación puede resolver el nombre de su servidor directamente o seguir una /.well-known/matrix/serverdelegación a un nombre de host y puerto diferentes. El certificado debe ser válido para el nombre de host alcanzado por esa ruta de descubrimiento. Un registro DNS obsoleto o una delegación incorrecta pueden dirigir a los pares a un punto final que presenta un certificado no relacionado.
4. Reparar la confianza saliente para una federación privada
Si el certificado defectuoso pertenece a un servidor remoto en una red privada, confirme primero que su autoridad de certificación (CA) privada lo haya emitido intencionadamente. Instale y mantenga dicha CA en el host de Synapse siempre que sea posible. Synapse también admite federation_custom_ca_listcertificados de CA personalizados para la federación. Esta opción requiere archivos PEM y reemplaza la lista de CA proporcionada por el sistema operativo, por lo que debe incluir todas las CA que su implementación necesite, en lugar de añadir solo una CA privada sin más.
federation_custom_ca_list:
- /etc/matrix-synapse/certs/private-root-ca.pem
Establezca la ruta a un certificado de CA, no a la clave privada del servidor. Asegúrese de que el proceso de Synapse pueda leerlo, valide la indentación YAML y reinicie o recargue Synapse según su método de implementación. El manual de configuración de Synapse indica que esta opción suele estar destinada a redes privadas de servidores domésticos.
No configure esta opción federation_verify_certificates: falsepara silenciar un error de federación pública. Su valor predeterminado es true; desactivarla elimina la verificación de certificados para la federación saliente y debilita la protección contra la suplantación de identidad. Esta opción federation_certificate_verification_whitelistexiste para casos específicos y limitados, como servicios ocultos de Tor o configuraciones privadas controladas, no como sustituto de la reparación de un certificado público. Para infraestructuras privadas, generalmente se prefiere una CA privada de confianza.
5. Compruebe la hora y vuelva a realizar la prueba.
Si las fechas del certificado aparecen como inválidas aunque el certificado esté vigente, verifique la hora del sistema y la sincronización horaria en el host de Synapse y en cualquier proxy. Un reloj con una desincronización significativa puede hacer que un certificado válido aparezca como no válido o caducado. Confirme también que la renovación automática haya actualizado el archivo disponible públicamente; la renovación del certificado en disco no garantiza que el proxy lo haya recargado.
Tras la corrección, vuelva a ejecutar el Probador de federación y repita la conexión que falló. Confirme que el probador detecta el nombre de host esperado, fechas válidas y una cadena de confianza, y revise los registros de Synapse en busca de nuevos intentos de federación sin el error de verificación del certificado. Si el probador funciona correctamente, pero un servidor remoto sigue fallando, capture el nombre de ese servidor, la marca de tiempo y la entrada de registro correspondiente (sin información confidencial): es posible que el problema restante se deba a su propio certificado o entorno de confianza. No comparta claves privadas, tokens de acceso ni el contenido de los mensajes de usuario durante la resolución de problemas.