SAML2 for TYPO3

SAML 2.0 brings single sign-on to TYPO3 without a Shibboleth installation on the server

Universities, public authorities and large enterprises run identity providers (IdPs) based on SAML 2.0: Microsoft ADFS, Okta, Keycloak, PingFederate. Until now, anyone who wanted to use these identities in TYPO3 needed a Shibboleth service provider on the web server, an additional software layer with its own configuration, its own certificates and its own maintenance. The TYPO3 extension saml2 makes the Shibboleth SP unnecessary. It uses SimpleSAMLphp, a SAML 2.0 SP written in PHP that runs alongside TYPO3. This simplifies the server architecture considerably, especially in shared hosting environments or container deployments, where a Shibboleth SP is hard to install.

For organizations whose IdP does not support OIDC (OpenID Connect), SAML 2.0 is the only standardized route to single sign-on. The extension closes exactly this gap in the TYPO3 ecosystem.

Typical use cases are university intranets, public-sector portals and corporate extranets

The most common scenario is the university intranet. A university runs a Shibboleth IdP within its national research and education federation. In Germany, that is the DFN-AAI of the German National Research and Education Network (DFN), which is linked to other national federations through eduGAIN. Students and staff sign in with their university credentials and gain access to protected TYPO3 pages: lecture notes, internal news, exam results. The saml2 extension leaves the validation of the SAML assertion to SimpleSAMLphp and signs in the matching TYPO3 frontend user; TYPO3 controls access through that user’s groups (for example, students in the group “student” and lecturers in “staff”).

The second scenario is public-sector portals connected to a national citizen identity service. In Germany, that service is BundID, which has been the federal government’s central identity service since 2023 and supports SAML 2.0 among its protocols. A municipality can connect its TYPO3 website to BundID via saml2, so that citizens sign in with their national ID card (eID) or their ELSTER certificate from the German tax portal and access personalized services.

The third scenario is corporate extranets. A car manufacturer runs a dealer portal on TYPO3. Dealers sign in through the group’s IdP (Microsoft ADFS) and see price lists, training materials and order forms assigned to their dealer group. The saml2 extension signs them in as TYPO3 frontend users, and their groups control access to protected content areas.

The technical architecture connects SimpleSAMLphp to TYPO3 as the SAML 2.0 SP

saml2 is based on SimpleSAMLphp, a standalone PHP implementation of SAML 2.0 that handles the AuthnRequest, response validation, assertion parsing and signature verification. SimpleSAMLphp is installed alongside TYPO3; the extension loads it via a configured path and registers itself as a TYPO3 authentication service for the frontend.

Configuration is split between two places. IdP and SP (metadata, entity IDs, certificates) are configured in SimpleSAMLphp. In TYPO3, the extension configuration holds the path to SimpleSAMLphp, the SP profile and the IdP address, while TypoScript defines the attribute used to find the TYPO3 user and the mapping of IdP attributes to frontend user fields. The login starts via the “SAML-Login” plugin on the TYPO3 site (SP-initiated SSO).

The extension does not create frontend users itself: it signs in an existing user, whom it finds via the configured attribute (default: uid), and optionally updates that user’s fields at every login. New accounts are created through registration with femanager, which the extension hooks into.

The extension does not offer a SAML backend login (BE users); it registers its authentication service for the frontend only. Anyone who introduces SAML for the backend as well takes on a higher risk: if the IdP goes down, nobody can reach the backend. In that case, we recommend keeping at least one local admin account as a fallback.

Common problems involve certificates, clock drift and attribute mapping

The most common problem in SAML integrations is expired or misconfigured certificates. The IdP signs the SAML response with its certificate. If the certificate on the SP side is not updated after the IdP has rotated it, signature verification fails and the login aborts with a cryptic error message. The fix: put certificate rotation on the maintenance calendar. Most IdPs give 30 days’ notice before a rotation.

The second problem is clock drift between IdP and SP. SAML assertions have a validity window (NotBefore / NotOnOrAfter). If the system clocks of the IdP server and the TYPO3 server drift further apart than the SAML library tolerates (180 seconds by default in onelogin/php-saml and SimpleSAMLphp), the assertion is rejected as invalid. The fix: configure NTP on both servers.

The third topic is incorrect attribute mapping. Every IdP names its attributes differently. Microsoft ADFS delivers “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”, Keycloak delivers “email”, Shibboleth delivers “urn:oid:0.9.2342.19200300.100.1.3”. The extension needs to know under which name the email attribute appears in the SAML token, and a wrong mapping leads to empty fields in the TYPO3 user profile. Debug logging of the received attributes helps identify the right mapping keys.

The saml2 extension is a 2014 beta for TYPO3 6.2

The saml2 extension in the TER is a beta: version 1.0.0 by Youwe from August 2014, which supports only TYPO3 6.2. There is no newer version in the TER or on Packagist; for current TYPO3 versions, it has to be ported or replaced. In SSO projects, Gosign checks whether the SAML library is up to date (security patches) and which extension fits the TYPO3 version in use. Because the saml2 extension is no longer maintained, we recommend the oidc extension as an alternative, provided the IdP supports OpenID Connect.