OIDC para TYPO3

Cómo los proyectos TYPO3 se conectan a Azure AD, Keycloak u Okta sin stack de identidad propio

En cualquier empresa que utilice Microsoft 365, Google Workspace o un Keycloak central, la gestión de usuarios ya está decidida: todas las cuentas de empleados viven en el IdP, y cada aplicación nueva debe conectarse ahí en lugar de gestionar sus propias contraseñas. La extensión OIDC para TYPO3 cubre exactamente ese patrón incorporando OpenID Connect como protocolo de autenticación en TYPO3 y haciendo utilizables como IdP Azure AD, Keycloak, Okta, Google Workspace o Auth0, sin necesidad de operar un Shibboleth SP propio. El público objetivo son portales corporativos, intranets, áreas de login para clientes y cualquier instalación TYPO3 que deba encajar en paisajes enterprise de identidad existentes.

Escenarios típicos de uso

Un grupo industrial español con 14.000 empleados opera su intranet sobre TYPO3. El departamento de IT ha decidido hace tiempo que cada aplicación nueva debe autenticarse contra Azure AD y aplicar allí la autenticación multifactor. La extensión OIDC obtiene los ID tokens de Azure AD, lee las asignaciones de grupos contenidas en el claim y genera a partir de ahí grupos fe_user. La intranet consigue Single Sign-On, MFA y Conditional Access sin infraestructura adicional, simplemente mediante una configuración limpia.

Un segundo escenario proviene de empresas medianas: un proveedor de software con un portal de clientes sobre TYPO3 utiliza Keycloak como broker central porque sus propios clientes acceden con usernames o con Social-Logins como Google o GitHub. Keycloak unifica eso y habla OIDC hacia afuera. TYPO3 utiliza la extensión OIDC y obtiene acceso a todas las variantes de login sin tener que saber que, por detrás, se trata de un Social-Login.

El tercer caso son administraciones estatales y autonómicas que cambian a cuentas ciudadanas basadas en Keycloak. Un portal TYPO3 a través del cual los ciudadanos envían solicitudes puede conectarse al Keycloak autonómico mediante la extensión OIDC. El atributo eID del broker acaba directamente en el fe_user, y el nivel de autenticación puede evaluarse mediante el acr-claim.

Arquitectura técnica: Authorization Code Flow en TYPO3

OpenID Connect es una capa de autenticación sobre OAuth 2.0, y la extensión OIDC implementa exactamente el Authorization Code Flow. El proceso es más sencillo que SAML: TYPO3 redirige al usuario mediante un Authorization Request al IdP, recibe tras un login exitoso un código, lo intercambia en el servidor por un ID token y valida la firma mediante el JSON Web Key Set (JWKS) del proveedor. Los claims del ID token, típicamente sub, email, name, groups y roles, se mapean sobre campos de usuario TYPO3.

La extensión se configura mediante la configuración de extensión de TYPO3 y un discovery endpoint que todo proveedor compatible con OIDC ofrece bajo /.well-known/openid-configuration. La extensión lee de esa URL los token endpoints, la URL JWKS y los flows soportados automáticamente, lo que reduce errores manuales. El claim mapping se realiza mediante una configuración YAML o TypoScript que mapea nombres de campos locales a rutas de claims.

Problemas frecuentes y soluciones

El primer problema afecta a los formatos de claim: Azure AD entrega los grupos como IDs de objeto (GUIDs), no como nombres legibles. Quien espera un claim group_ids y recibe group_names ve grupos de usuarios vacíos en TYPO3. La solución limpia está en la propia aplicación de Azure AD: en el token configuration blade puede definirse qué atributos se exponen como claims y, adicionalmente, un conjunto de reglas de claim transformation puede traducir GUIDs a nombres legibles.

El segundo problema es la Redirect URI. Todo cliente OIDC debe registrar en el IdP exactamente la Redirect URI a la que será enviado tras el login. Diferencias en mayúsculas y minúsculas, trailing slashes olvidadas o un cambio de HTTP a HTTPS provocan fallos de login inmediatos que no aparecen en el log de TYPO3 porque el error ocurre en el IdP. Gosign configura clientes separados para staging y producción con Redirect URIs limpias y documenta cada cambio en el proceso de despliegue.

El tercer tema es el token refresh. Quien quiere sesiones más largas necesita Refresh Tokens, que el IdP solo emite si se ha solicitado el scope offline_access en el login. Sin ese scope, la sesión de TYPO3 termina en cuanto caduca el ID token, normalmente al cabo de una hora. La configuración en el backend de la extensión debe, por tanto, incluir el scope offline_access y activar la lógica de token refresh.

Un cuarto problema afecta al cierre de sesión. OIDC conoce Front-Channel y Back-Channel Logout, y ninguno de los dos está necesariamente activado en la extensión. Quien espera un verdadero Single Logout a través de varias aplicaciones debe configurar el End Session Endpoint correspondiente del proveedor y asegurar que TYPO3 llame a la URL de logout del IdP al final de la sesión. Sin esa configuración, el usuario permanece conectado en el IdP aunque haya cerrado sesión en TYPO3.

Migración y compatibilidad de versiones

La extensión OIDC es actualmente el estándar recomendado para TYPO3 v12 y v13, mientras que proyectos más antiguos en v11 siguen apoyándose con frecuencia en implementaciones OAuth caseras o en shibboleth_auth. La ruta de migración de Shibboleth a OIDC está bien establecida, siempre que el IdP hable ambos: Keycloak, ADFS y Azure AD pueden servir SAML y OIDC en paralelo, de modo que una transición sin Big Bang es posible.

Quien migra desde una gestión de fe_users meramente basada en base de datos debe mapear las cuentas existentes con una estrategia de matching contra los claims OIDC. La dirección de correo es el anclaje habitual, pero no siempre basta, porque los correos pueden cambiar. Un sub-claim, almacenado en el fe_user como identificador persistente unívoco, es la solución más robusta. Gosign asume estas migraciones incluyendo la conciliación de cuentas existentes y una fase de transición en la que ambos caminos de autenticación funcionan en paralelo.

Para equipos que están montando un proyecto TYPO3 nuevo, OIDC es en la gran mayoría de los casos la primera opción. La configuración es más ligera que en SAML, el esfuerzo de cliente menor y todo IdP moderno soporta el protocolo de forma nativa. Las excepciones solo están justificadas cuando requisitos regulatorios o federativos exigen explícitamente SAML, como en las federaciones universitarias mencionadas. En todos los demás escenarios, sobre todo con IdPs en la nube e integraciones enterprise, OIDC ofrece el mejor compromiso entre sencillez, seguridad y mantenibilidad.