Para agregar el inicio de sesión de Keycloak a Element Web, configure Keycloak como proveedor de OpenID Connect (OIDC) en Synapse y asegúrese de que Element Web utilice ese servidor Synapse. Synapse gestiona la redirección y la devolución de llamada de autenticación; Element Web no necesita la clave secreta del cliente de Keycloak.
Escenario hipotético: una pequeña organización ejecuta Element Web en chat.example.org, Synapse en matrix.example.orgy Keycloak en login.example.org. La misma secuencia se aplica a otros nombres de host, pero cada URL debe coincidir con su configuración pública real. Este ejemplo es ilustrativo, no un informe de una configuración en producción.
Lo que necesitas antes de cambiar la configuración
Utilice URL HTTPS públicas para Keycloak y Synapse. La documentación OIDC de Synapse requiere un origen seguro para el proveedor de identidad, y su función de devolución de llamada debe ser accesible a través de la URL pública de Synapse. Confirme el nombre del reino en Keycloak, el de Synapse public_baseurly la URL del servidor principal que se proporciona a Element Web. Si un proxy inverso se encuentra delante de cualquiera de los servicios, debe redirigir las solicitudes al backend correcto y conservar el host y el esquema HTTPS externos.
La configuración actual de Synapse utiliza una oidc_providerslista. El formato anterior de proveedor único oidc_configestá obsoleto. Mantenga una cuenta de administrador activa y una copia de la configuración actual durante las pruebas. No desactive el inicio de sesión con contraseña ni el registro hasta que haya verificado el flujo de SSO y haya decidido cómo se aprovisionarán las cuentas.
1. Registra Synapse como cliente en Keycloak.
En el entorno de Keycloak donde se encuentran los usuarios de su organización, cree un cliente OpenID Connect para Synapse. El ejemplo oficial de Keycloak de Synapse utiliza un cliente confidencial con ID de cliente synapse. Establezca la URI de redireccionamiento válida a esta función de devolución de llamada exacta, sustituyendo el nombre de host de Synapse:
https://matrix.example.org/_synapse/client/oidc/callback
Para la configuración hipotética, establezca el tipo de acceso del cliente como confidencial y habilite el cliente. En la pestaña Credenciales, copie el secreto del cliente generado en su sistema de gestión de secretos; no lo coloque en la sección pública de Element Web config.jsonni lo publique en un repositorio.
La URI de redireccionamiento suele ser una fuente frecuente de fallos. Debe utilizar la URL pública de Synapse, la /_synapse/client/oidc/callbackruta exacta y el mismo esquema y nombre de host que Synapse ve en el navegador. Evite usar una función de devolución de llamada con comodines cuando una URI exacta funcione. Si posteriormente habilita el cierre de sesión mediante canal secundario, añada también el punto final de canal secundario documentado de Synapse en Keycloak; esto es opcional e independiente del inicio de sesión básico.
2. Agregue el proveedor Keycloak a Synapse.
Edita el archivo activo homeserver.yaml. Reemplaza el reino y el secreto a continuación con tus valores y confirma la URL del emisor del documento de descubrimiento OpenID del reino. El emisor de reino estándar de Keycloak tiene esta estructura:
https://login.example.org/realms/your-realm
Para una implementación que utilice el punto final de descubrimiento estándar y las reclamaciones que se muestran en el ejemplo de Keycloak de Synapse, la entrada del proveedor es:
oidc_providers:
- idp_id: keycloak
idp_name: "Company Login"
issuer: "https://login.example.org/realms/your-realm"
client_id: "synapse"
client_secret: "REPLACE_WITH_THE_KEYCLOAK_SECRET"
scopes: ["openid", "profile"]
user_mapping_provider:
config:
localpart_template: "{{ user.preferred_username }}"
display_name_template: "{{ user.name }}"
El emisor debe coincidir con el emisor del reino de Keycloak, no solo con la raíz del servidor de Keycloak. Discovery permite que Synapse obtenga los puntos finales de autorización, token e información del usuario de dicho emisor. El mapeo utiliza la información de Keycloak preferred_usernamepara formar una parte local de Matrix y namecomo nombre para mostrar; asegúrese de que estas declaraciones estén presentes y sean estables para sus usuarios. Una parte local de Matrix es un identificador de cuenta, por lo que cambiar el mapeo posteriormente puede generar confusión en la coincidencia de cuentas o producir un ID de Matrix diferente.
Conserva la lista existente oidc_providerssi hay otros proveedores de identidad configurados; añade esta entrada en lugar de reemplazar proveedores no relacionados. Protege el secreto del cliente como secreto y establece los permisos de archivo según tu implementación. Valida la indentación YAML y, a continuación, reinicia Synapse utilizando el procedimiento de servicio o contenedor correspondiente a tu instalación. Las instalaciones empaquetadas pueden incluir dependencias OIDC; para una instalación en un entorno virtual, Synapse documenta la instalación matrix-synapse[oidc]. Sigue las instrucciones del responsable del paquete para otros métodos de instalación.
3. Elemento web de punto en el mismo servidor principal.
Element Web config.jsondebe identificar el servidor Synapse como su servidor principal, por ejemplo, mediante default_server_config.mHomeserver.base_url. Utilice la URL real del servidor principal, no la del emisor de Keycloak. Element Web es un cliente estático: vuelva a implementar o recargue su configuración utilizando su método de alojamiento después de cambiar la URL del servidor principal. No incluya el secreto de cliente de Keycloak en este archivo, ya que los navegadores pueden leerlo.
En el ejemplo hipotético, Element Web está alojado en https://chat.example.orgy se conecta a https://matrix.example.org. Cuando un usuario selecciona la opción SSO en la pantalla de inicio de sesión de Element, el navegador debería seguir el flujo de inicio de sesión de Synapse hasta el dominio de Keycloak y regresar a la función de devolución de llamada de Synapse. La redacción exacta del botón y el diseño de la pantalla de inicio de sesión pueden variar según la versión de Element Web y la configuración del servidor; pruebe el comportamiento en lugar de basarse en una etiqueta específica.
4. Realice una prueba con una cuenta antes de implementar el inicio de sesión único (SSO).
Abra Element Web en una ventana de incógnito y seleccione la opción de inicio de sesión único (SSO). Inicie sesión con un usuario de prueba de Keycloak, apruebe el acceso solicitado si se le pide y confirme que el navegador regresa al servidor principal previsto y abre la cuenta de Matrix esperada. Verifique que el ID de Matrix resultante tenga la parte local correcta. Revise los registros de Synapse y Keycloak si el navegador muestra algún error.
Si la redirección falla, compare la URL de devolución de llamada de Keycloak carácter por carácter con la URL de devolución de llamada pública de Synapse. Un error de "emisor no coincidente" indica un emisor de dominio o nombre de host de proxy inverso incorrecto. Un nombre de usuario faltante o un error de asignación significa que la declaración configurada no existe o no es adecuada; inspeccione las declaraciones del usuario de prueba y ajuste la asignación según sea necesario. Si el navegador llega a Keycloak pero no devuelve ninguna respuesta, verifique los certificados TLS y el enrutamiento del proxy para la devolución de llamada de Synapse.
Cierre de sesión opcional: Synapse admite el cierre de sesión mediante canal secundario OIDC. Para usarlo, configúrelo backchannel_logout_enabled: trueen este proveedor y configure la URL de cierre de sesión mediante canal secundario de Keycloak como https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse también documenta cómo habilitar la opción session-required en Keycloak. Esto gestiona las notificaciones de cierre de sesión iniciadas por el proveedor; no es necesario para que funcione el inicio de sesión SSO inicial.
Antes del despliegue: decida si SSO debe crear nuevos usuarios de Matrix o solo autenticar las cuentas que aprovisione por separado, luego revise las opciones OIDC de Synapse para su versión instalada. Las etiquetas de configuración y la interfaz de administración de Keycloak pueden cambiar entre versiones. Los pasos aquí descritos siguen la documentación OIDC de Synapse disponible el 10 de octubre de 2026 y asumen un reino Keycloak estándar y una implementación de Synapse que utiliza el formato de proveedor documentado. Consulte la guía de Synapse OpenID Connect y Keycloak , la referencia de configuración de Synapse y la documentación oficial de Keycloak antes de aplicar configuraciones específicas de la versión. Una vez que la cuenta de prueba inicie sesión correctamente y tenga una ruta de recuperación, documente la asignación final de devolución de llamada, emisor y reclamación para los administradores.