Cómo configurar el inicio de sesión único (SSO) con Keycloak en Element Web

Element Web no se autentica directamente con Keycloak. Element solicita a su servidor principal Matrix los métodos de inicio de sesión compatibles; el servidor principal completa la conexión OpenID Connect (OIDC) con Keycloak y devuelve el usuario a Element. Para una implementación de Synapse que utilice su compatibilidad integrada con OIDC, configure un cliente OIDC confidencial en Keycloak, añada ese proveedor a Synapse y, opcionalmente, ajuste la configuración de Element Web config.jsonpara que muestre o inicie automáticamente el inicio de sesión único (SSO).

Esta guía utiliza el proveedor OIDC integrado de Synapse, que es una ruta de implementación común. Si su servidor principal delega la autenticación al Servicio de Autenticación de Matrix (MAS), utilice la configuración de devolución de llamada y proveedor de MAS que se describe a continuación. Las dos URL de devolución de llamada son diferentes. Las instrucciones se verificaron con la documentación de configuración de Element Web, la guía OIDC de Synapse v1.144, la guía SSO ascendente actual de MAS y la guía de administración de Keycloak 26.8.0 el 6 de octubre de 2026; el empaquetado de la implementación y las etiquetas de la interfaz de usuario pueden variar según la versión.

Primero, identifique qué ruta de autenticación utiliza.

Antes de crear un cliente, revise la configuración y la documentación de implementación de Synapse. La función de devolución de llamada debe pertenecer al componente que se comunica con Keycloak; no registre la URL del sitio web de Element como función de devolución de llamada.

Lo que necesitas

• Una URL HTTPS pública para Synapse, como https://matrix.example.com, y un emisor de reino Keycloak accesible, como https://sso.example.com/realms/company.
• Acceso administrativo al dominio de Keycloak y a la configuración y el servicio de Synapse.
• Una copia de seguridad de la configuración actual y una forma de utilizar los registros de Synapse o la consola del servidor si falla el inicio de sesión.
• Una decisión sobre el aprovisionamiento de cuentas: qué usuarios de Keycloak pueden iniciar sesión, qué declaración los identifica y si deben conservarse las cuentas de Matrix existentes.

Configurar Keycloak para Synapse OIDC

1. Cree un cliente OIDC confidencial

En el dominio utilizado para las cuentas de Matrix, cree un cliente para Synapse utilizando el protocolo OpenID Connect. Habilite el código de autorización o el flujo estándar y la autenticación del cliente para que Synapse pueda usar un secreto de cliente en el punto final del token. Establezca el ID del cliente en un valor que también utilizará en Synapse, por ejemplo synapse.

Establezca la URI de redireccionamiento válida en la función de devolución de llamada exacta de Synapse:

https://matrix.example.com/_synapse/client/oidc/callback

Sustituya el nombre de host de ejemplo por la URL base pública configurada para Synapse. No utilice un comodín amplio, como *en entornos de producción. Keycloak valida las URI de redireccionamiento, por lo que una discrepancia en el host, el esquema, la ruta o la barra diagonal final puede provocar un error de "URI de redireccionamiento no permitida".

Guarda el cliente, copia su clave secreta generada y guárdala como clave secreta del servidor. Evita incluirla en config.jsonel control de versiones, capturas de pantalla y JavaScript del cliente de Element Web. La consola de administración de Keycloak puede mostrar la autenticación o las credenciales del cliente de forma diferente en cada versión; verifica que el cliente resultante sea confidencial y pueda usar el flujo de código de autorización estándar.

2. Confirmar el emisor y las reclamaciones

El emisor identifica el reino, no la raíz del servidor Keycloak. Para este ejemplo, utilice https://sso.example.com/realms/company. Confirme que la configuración OpenID del reino sea accesible en <issuer>/.well-known/openid-configurationy que su emisor anunciado coincida exactamente con el valor que le proporcionará a Synapse.

Synapse necesita una declaración de identidad estable para asociar la cuenta de Keycloak con un usuario de Matrix. Su proveedor OIDC normalmente identifica al sujeto externo mediante la declaración de sujeto OIDC; el mapeo de nombre de usuario que se muestra a continuación utiliza preferred_usernamela parte local de Matrix. Asegúrese de que Keycloak devuelva dicha declaración y de que los nombres de usuario sean únicos y estables según la política de su cuenta. Si su organización permite cambios de nombre de usuario, elija y pruebe una estrategia de mapeo antes de la puesta en producción; un cambio inesperado en el mapeo puede afectar a la cuenta de Matrix a la que accede un usuario.

Configurar Synapse

3. Añada el proveedor OIDC.

Agregue una entrada de proveedor a la configuración principal de Synapse, generalmente homeserver.yaml. Incorpórela con el YAML existente en lugar de reemplazar otras configuraciones. Sustituya su emisor de reino y el secreto de cliente real:

oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://sso.example.com/realms/company"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_CLIENT_SECRET"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

Los ámbitos solicitados controlan qué información de usuario puede devolver Keycloak; no garantizan que se completen todas las reclamaciones. Si no necesita importar el correo electrónico o el nombre para mostrar, reduzca los ámbitos y la asignación en consecuencia. Mantenga el archivo de configuración legible únicamente por el administrador del servicio y el proceso Synapse, según corresponda a su implementación. Si administra Synapse mediante contenedores o un gráfico, coloque la configuración del proveedor en la fuente de configuración compatible en lugar de editar un archivo generado que se sobrescribirá.

4. Opcionalmente, configure el cierre de sesión mediante canal secundario.

Por defecto, cerrar sesión en un servicio no necesariamente finaliza la sesión del navegador en todos los demás servicios. Si desea que las notificaciones de cierre de sesión de Keycloak finalicen la sesión de Synapse, habilítelas backchannel_logout_enabled: trueen el proveedor de Keycloak en Synapse y configure la URL de cierre de sesión de Backchannel de Keycloak en:

https://matrix.example.com/_synapse/client/oidc/backchannel_logout

Esto es opcional y depende de tu política de cierre de sesión y la configuración del cliente. Prueba ambas opciones de cierre de sesión: Synapse y Keycloak. No des por sentado que cerrar sesión en Element por sí solo finaliza la sesión de Keycloak.

5. Reinicia y prueba Synapse.

Valida el archivo YAML con las comprobaciones de configuración de tu implementación y, a continuación, reinicia o recarga Synapse utilizando el método compatible con la configuración de tu paquete o contenedor. Revisa los registros de Synapse para detectar errores de detección OIDC, autenticación de cliente, devolución de llamada o asignación de reclamaciones. Utiliza primero una cuenta de prueba y confirma que su ID de Matrix y nombre para mostrar sean los valores esperados.

Configurar Element Web

6. Mantenga el inicio de sesión único (SSO) como opcional o redirija automáticamente.

Una vez que Synapse anuncia el inicio de sesión OIDC, Element Web puede presentar su opción de inicio de sesión SSO. sso_redirect_optionsLa configuración de Element controla la experiencia del navegador; no configura Keycloak ni almacena el secreto del cliente. Agregue una configuración como esta al servidor de Element Web config.jsonsi desea que los visitantes no autenticados que lleguen a la página de bienvenida o de inicio de sesión sean redirigidos al flujo SSO disponible:

{
  "sso_redirect_options": {
    "immediate": false,
    "on_welcome_page": true,
    "on_login_page": true
  }
}

Para una implementación que realmente requiera inicio de sesión único (SSO), configure "immediate": trueel inicio de sesión único para todos los usuarios no autenticados. Esto puede dificultar el acceso mediante contraseña u otras opciones de inicio de sesión, por lo que se recomienda probar la recuperación y el acceso de administrador antes de implementarlo. Si los usuarios deben elegir entre SSO y otro método, desactive la redirección automática y compruebe que la opción de SSO aparezca en el flujo de inicio de sesión.

Si Synapse utiliza el servicio de autenticación Matrix

MAS es un servicio de autenticación independiente y puede actuar como cliente OIDC para Keycloak. En esa arquitectura, configure la URI de redireccionamiento de Keycloak como https://auth.example.com/upstream/callback/<provider-id>, donde el ID del proveedor coincide con la configuración de MAS. Configure el proveedor en upstream_oauth2.providers; Element luego usa el flujo de autenticación basado en MAS del servidor principal. No use Synapse /_synapse/client/oidc/callbackpara esta conexión ascendente. MAS requiere un proveedor OIDC que admita el flujo de código de autorización. Su formato de configuración, ID de proveedor requerido y pasos de migración son distintos de los integrados de Synapse oidc_providers.

Malentendidos comunes y soluciones

• “Solo necesito cambiar la configuración de Element.” Element controla el flujo del navegador, mientras que Synapse o MAS gestionan OIDC. Primero, configure el proveedor correcto del lado del servidor principal.
• Un inicio de sesión exitoso en Keycloak demuestra que la asignación de cuentas es correcta. La autenticación puede tener éxito incluso si se selecciona una reclamación de perfil o parte local incorrecta. Realice una prueba con un usuario que no sea de producción y verifique el ID de matriz resultante.
• El inicio de sesión único (SSO) desactiva automáticamente las contraseñas y el registro. Estas políticas las gestiona el servidor principal y la implementación. Revise por separado la configuración de inicio de sesión y registro de Synapse y confirme la política aprobada.
• Al cerrar sesión en Element, se cierra mi sesión en todas partes. Las sesiones del navegador pueden permanecer activas en Keycloak. Configure y pruebe el cierre de sesión mediante canal secundario si se requiere la finalización centralizada de la sesión.

Lista de verificación

• El cliente Keycloak utiliza el flujo de código de autorización, la autenticación del cliente y la función de devolución de llamada exacta para Synapse o MAS.
• La URL del emisor coincide con los metadatos de descubrimiento del dominio, y el secreto del cliente se almacena en el servidor.
• Synapse o MAS se inician sin errores de configuración OIDC y muestran el método de inicio de sesión previsto.
• Un usuario de prueba puede iniciar sesión desde una nueva sesión del navegador, acceder a la cuenta de Matrix esperada y completar una sesión normal de Element.
• El comportamiento de cierre de sesión, las cuentas existentes, las restricciones de registro y cualquier acceso de administrador alternativo se ajustan a su política.

Referencias oficiales

• Guía de conexión OpenID para Synapse v1.144, incluyendo la configuración del cliente Keycloak y de las devoluciones de llamada.
• Configuración de Element Web: Opciones de redireccionamiento SSO
• Servicio de autenticación de Matrix: configuración de un proveedor de SSO ascendente
• Guía de administración del servidor Keycloak 26.8.0