SAML2 für TYPO3

SAML 2.0 ermöglicht Single Sign-On in TYPO3 ohne Shibboleth-Installation auf dem Server

Hochschulen, Behörden und Konzerne betreiben Identity Provider (IdP), die auf SAML 2.0 basieren: Microsoft ADFS, Okta, Keycloak, PingFederate. Wer diese Identitäten in TYPO3 nutzen will, brauchte bisher einen Shibboleth Service Provider auf dem Webserver, eine zusätzliche Softwareschicht mit eigener Konfiguration, eigenen Zertifikaten und eigener Wartung. Die TYPO3-Extension saml2 macht den Shibboleth SP überflüssig. Sie implementiert den SAML 2.0 SP direkt in PHP und kommuniziert ohne Middleware mit dem IdP. Das vereinfacht die Server-Architektur erheblich, besonders auf Shared-Hosting-Umgebungen oder in Container-Deployments, wo ein Shibboleth SP schwer zu installieren ist.

Für Organisationen, deren IdP kein OIDC (OpenID Connect) unterstützt, ist SAML 2.0 der einzige standardisierte Weg zum Single Sign-On. Die Extension schliesst genau diese Lücke im TYPO3-Ökosystem.

Typische Einsatzszenarien betreffen Hochschul-Intranets, Behörden-Portale und Konzern-Extranets

Das häufigste Szenario ist das Hochschul-Intranet. Eine Universität betreibt einen Shibboleth IdP im DFN-AAI-Verbund (Deutsches Forschungsnetz). Studierende und Mitarbeitende melden sich mit ihrer Hochschulkennung an und erhalten Zugang zu geschützten TYPO3-Seiten: Skripte, interne Nachrichten, Prüfungsergebnisse. Die saml2-Extension prüft das SAML-Assertion-Token, legt bei Bedarf einen TYPO3-Frontend-User an und weist Gruppen basierend auf den IdP-Attributen zu (z.B. Studierende = Gruppe “student”, Dozierende = Gruppe “staff”).

Ein zweites Szenario sind Behörden-Portale mit BundID-Anbindung. Seit 2023 ist BundID der zentrale Identitätsdienst des Bundes. SAML 2.0 ist eines der unterstützten Protokolle. Eine Kommune kann ihre TYPO3-Website über saml2 an BundID anbinden, sodass Bürger sich mit ihrem Personalausweis (eID) oder Elster-Zertifikat anmelden und auf personalisierte Dienstleistungen zugreifen.

Drittes Szenario: Konzern-Extranets. Ein Automobilhersteller betreibt ein Händlerportal auf TYPO3. Händler melden sich über den Konzern-IdP (Microsoft ADFS) an und sehen Preislisten, Schulungsunterlagen und Bestellformulare, die ihrer Händlergruppe zugeordnet sind. Die saml2-Extension mappt die ADFS-Gruppen auf TYPO3-Frontend-Gruppen und steuert damit den Zugang zu geschützten Inhaltsbereichen.

Technische Architektur implementiert den SAML 2.0 SP als PHP-Library in TYPO3

saml2 basiert auf der PHP-Library onelogin/php-saml (oder einer vergleichbaren Implementation), die den SAML 2.0 Web Browser SSO Profile vollständig abdeckt: AuthnRequest, Response-Validierung, Assertion-Parsing, Signaturprüfung, Logout. Die Library wird als Composer-Dependency eingebunden und von der Extension als TYPO3-Authentication-Service registriert.

Die Konfiguration erfolgt im TYPO3-Backend oder per TypoScript: IdP-Metadata-URL (oder manuell: Entity ID, SSO-URL, SLO-URL, Zertifikat), SP-Entity-ID, Attribute-Mapping (welches IdP-Attribut auf welches TYPO3-Feld: email, username, firstname, lastname, groups). Die Extension unterstützt sowohl SP-initiated SSO (User klickt “Login” auf der TYPO3-Seite) als auch IdP-initiated SSO (User kommt direkt vom IdP-Portal).

Frontend-User werden bei der ersten Anmeldung automatisch angelegt und bei jeder weiteren Anmeldung aktualisiert. Die Gruppenzuordnung kann statisch (alle SAML-User in Gruppe X) oder dynamisch (IdP-Attribut “role” = “admin” wird zu TYPO3-Gruppe “admin”) konfiguriert werden.

Für das Backend-Login (BE-User) ist SAML ebenfalls konfigurierbar, allerdings mit höherem Risiko: Wenn der IdP ausfällt, ist kein Backend-Zugang mehr möglich. Wir empfehlen, mindestens einen lokalen Admin-Account als Fallback beizubehalten.

Häufige Probleme betreffen Zertifikate, Zeitabweichungen und Attribut-Mapping

Das häufigste Problem bei SAML-Integrationen sind abgelaufene oder falsch konfigurierte Zertifikate. Der IdP signiert die SAML-Response mit seinem Zertifikat. Wenn das Zertifikat auf dem SP nicht aktualisiert wird, nachdem der IdP es rotiert hat, scheitert die Signaturprüfung und der Login bricht mit einer kryptischen Fehlermeldung ab. Die Lösung: Zertifikats-Rotation in den Wartungskalender aufnehmen. Die meisten IdPs geben 30 Tage Vorlauf vor der Rotation.

Zweites Problem: Zeitabweichungen zwischen IdP und SP. SAML-Assertions haben ein Zeitfenster (NotBefore / NotOnOrAfter). Wenn die Systemuhren von IdP-Server und TYPO3-Server mehr als 120 Sekunden auseinanderlaufen, wird die Assertion als ungültig abgelehnt. Die Lösung: NTP auf beiden Servern konfigurieren.

Drittes Thema: Falsches Attribut-Mapping. Jeder IdP benennt die Attribute anders. Microsoft ADFS liefert “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”, Keycloak liefert “email”, Shibboleth liefert “urn:oid:0.9.2342.19200300.100.1.3”. Die Extension muss wissen, unter welchem Namen das E-Mail-Attribut im SAML-Token steht. Falsches Mapping führt zu leeren Feldern im TYPO3-User-Profil. Debug-Logging der empfangenen Attribute hilft, die richtigen Mapping-Keys zu identifizieren.

TYPO3 v12 wird unterstützt, v13-Kompatibilität hängt von der Authentication-Service-API ab

Die saml2-Extension registriert sich als TYPO3 Authentication Service. Diese API ist im TYPO3-Core seit Jahren stabil, wurde aber in v12 und v13 an einzelnen Stellen angepasst. Die aktuelle Version der Extension läuft unter v12 stabil. Für v13 muss die Authentication-Service-Registrierung an die neue Service-Konfiguration angepasst werden. Gosign prüft bei SSO-Projekten, ob die PHP-SAML-Library auf aktuellem Stand ist (Sicherheitspatches) und ob die Extension mit der eingesetzten TYPO3-Version kompatibel ist. Wenn die Community-Extension nicht mehr gepflegt wird, empfehlen wir als Alternative die oidc-Extension, sofern der IdP OpenID Connect unterstützt.