SAML2 para TYPO3

SAML 2.0 permite Single Sign-On en TYPO3 sin instalar Shibboleth en el servidor

Universidades, administraciones públicas y grandes empresas operan proveedores de identidad (IdP) basados en SAML 2.0: Microsoft ADFS, Okta, Keycloak, PingFederate. Quien quisiera usar estas identidades en TYPO3 necesitaba hasta ahora un Shibboleth Service Provider en el servidor web, una capa de software adicional con su propia configuración, sus propios certificados y su propio mantenimiento. La extensión saml2 para TYPO3 hace innecesario el Shibboleth SP. Implementa el SP de SAML 2.0 directamente en PHP y se comunica con el IdP sin middleware. Esto simplifica considerablemente la arquitectura del servidor, especialmente en entornos de hosting compartido o en despliegues con contenedores, donde un Shibboleth SP es difícil de instalar.

Para organizaciones cuyo IdP no soporta OIDC (OpenID Connect), SAML 2.0 es el único camino estandarizado hacia el Single Sign-On. La extensión cubre exactamente ese vacío en el ecosistema TYPO3.

Los escenarios típicos abarcan intranets universitarias, portales de administraciones públicas y extranets corporativos

El escenario más frecuente es la intranet universitaria. Una universidad opera un IdP Shibboleth en una federación académica (por ejemplo SIR2 o RedIRIS en España). Estudiantes y personal se autentican con sus credenciales universitarias y obtienen acceso a páginas TYPO3 protegidas: apuntes, noticias internas, calificaciones. La extensión saml2 verifica el token de aserción SAML, crea si es necesario un usuario de frontend en TYPO3 y asigna grupos basándose en los atributos del IdP (por ejemplo, estudiantes = grupo “student”, docentes = grupo “staff”).

Un segundo escenario son los portales de administraciones públicas con conexión a Cl@ve. Cl@ve es la plataforma común de identificación electrónica para servicios públicos en España. SAML 2.0 es uno de los protocolos soportados. Un ayuntamiento puede conectar su sitio web TYPO3 a Cl@ve mediante saml2, de modo que los ciudadanos puedan autenticarse con su DNI electrónico o certificado digital y acceder a servicios personalizados.

Tercer escenario: extranets corporativos. Un fabricante de automoción opera un portal de concesionarios sobre TYPO3. Los concesionarios se autentican a través del IdP corporativo (Microsoft ADFS) y ven listas de precios, material formativo y formularios de pedido asignados a su grupo concesionario. La extensión saml2 mapea los grupos de ADFS a grupos de frontend TYPO3 y controla así el acceso a las áreas de contenido protegidas.

La arquitectura técnica implementa el SP de SAML 2.0 como librería PHP en TYPO3

saml2 se apoya en la librería PHP onelogin/php-saml (o una implementación equivalente), que cubre íntegramente el Web Browser SSO Profile de SAML 2.0: AuthnRequest, validación de respuestas, parseo de aserciones, verificación de firmas, logout. La librería se incluye como dependencia de Composer y la extensión la registra como servicio de autenticación de TYPO3.

La configuración se realiza desde el backend de TYPO3 o mediante TypoScript: URL de metadatos del IdP (o manualmente: Entity ID, URL SSO, URL SLO, certificado), Entity ID del SP, mapeo de atributos (qué atributo del IdP corresponde a qué campo TYPO3: email, username, firstname, lastname, groups). La extensión soporta tanto SSO iniciado por el SP (el usuario pulsa “Login” en la página TYPO3) como SSO iniciado por el IdP (el usuario llega directamente desde el portal del IdP).

Los usuarios de frontend se crean automáticamente en el primer inicio de sesión y se actualizan en cada acceso posterior. La asignación de grupos puede configurarse de forma estática (todos los usuarios SAML en el grupo X) o dinámica (atributo “role” del IdP = “admin” se traduce al grupo “admin” de TYPO3).

Para el inicio de sesión en el backend (usuarios BE) también es posible configurar SAML, aunque con mayor riesgo: si el IdP deja de estar disponible, no habrá acceso al backend. Recomendamos mantener al menos una cuenta de administrador local como respaldo.

Los problemas habituales afectan a certificados, desviaciones de hora y mapeo de atributos

El problema más frecuente en integraciones SAML son los certificados caducados o mal configurados. El IdP firma la respuesta SAML con su certificado. Si el certificado del SP no se actualiza después de que el IdP lo rote, la verificación de firma falla y el inicio de sesión se interrumpe con un mensaje de error críptico. La solución: incorporar la rotación de certificados al calendario de mantenimiento. La mayoría de IdPs dan un preaviso de 30 días antes de la rotación.

Segundo problema: desviaciones horarias entre IdP y SP. Las aserciones SAML tienen una ventana temporal (NotBefore / NotOnOrAfter). Si los relojes del servidor IdP y del servidor TYPO3 difieren en más de 120 segundos, la aserción se rechaza como inválida. La solución: configurar NTP en ambos servidores.

Tercer tema: mapeo de atributos incorrecto. Cada IdP nombra los atributos de forma distinta. Microsoft ADFS entrega “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”, Keycloak entrega “email”, Shibboleth entrega “urn:oid:0.9.2342.19200300.100.1.3”. La extensión debe saber bajo qué nombre aparece el atributo de correo electrónico en el token SAML. Un mapeo incorrecto se traduce en campos vacíos en el perfil de usuario de TYPO3. El logging de depuración de los atributos recibidos ayuda a identificar las claves de mapeo correctas.

TYPO3 v12 está soportado, la compatibilidad con v13 depende de la API de Authentication Service

La extensión saml2 se registra como TYPO3 Authentication Service. Esta API lleva años estable en el core de TYPO3, pero se ha ajustado en puntos concretos en v12 y v13. La versión actual de la extensión funciona sin problemas en v12. Para v13 el registro del servicio de autenticación debe adaptarse a la nueva configuración de servicios. En los proyectos SSO, Gosign verifica que la librería PHP-SAML esté actualizada (parches de seguridad) y que la extensión sea compatible con la versión de TYPO3 desplegada. Si la extensión comunitaria deja de mantenerse, recomendamos como alternativa la extensión oidc, siempre que el IdP soporte OpenID Connect.