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 nutzt mit SimpleSAMLphp einen SAML 2.0 SP, der in PHP geschrieben ist und neben TYPO3 läuft. 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 schließt 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 überlässt die Prüfung der SAML-Assertion SimpleSAMLphp und meldet den passenden TYPO3-Frontend-User an; über dessen Gruppen (z.B. Studierende = Gruppe “student”, Dozierende = Gruppe “staff”) steuert TYPO3 den Zugang.

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 meldet sie als TYPO3-Frontend-User an, und deren Gruppen steuern den Zugang zu geschützten Inhaltsbereichen.

Technische Architektur bindet SimpleSAMLphp als SAML 2.0 SP an TYPO3 an

saml2 basiert auf SimpleSAMLphp, einer eigenständigen PHP-Implementierung von SAML 2.0, die AuthnRequest, Response-Validierung, Assertion-Parsing und Signaturprüfung übernimmt. SimpleSAMLphp wird neben TYPO3 installiert; die Extension lädt es über einen konfigurierten Pfad und registriert sich als TYPO3-Authentication-Service für das Frontend.

Die Konfiguration verteilt sich auf zwei Stellen. IdP und SP (Metadaten, Entity-IDs, Zertifikate) konfiguriert man in SimpleSAMLphp. In TYPO3 stehen in der Extension-Konfiguration der Pfad zu SimpleSAMLphp, das SP-Profil und die IdP-Adresse, per TypoScript das Attribut, über das der TYPO3-User gefunden wird, und das Mapping von IdP-Attributen auf Felder des Frontend-Users. Der Login startet über das Plugin “SAML-Login” auf der TYPO3-Seite (SP-initiated SSO).

Frontend-User legt die Extension nicht selbst an: Sie meldet einen vorhandenen User an, den sie über das konfigurierte Attribut findet (Standard: uid), und aktualisiert auf Wunsch bei jeder Anmeldung seine Felder. Neue Konten entstehen über die Registrierung mit femanager, an die sich die Extension anhängt.

Ein Backend-Login (BE-User) per SAML bietet die Extension nicht, sie registriert ihren Authentication-Service nur für das Frontend. Wer SAML auch für das Backend einführt, trägt ein höheres Risiko: Wenn der IdP ausfällt, ist kein Backend-Zugang mehr möglich. Wir empfehlen dann, 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 weiter auseinanderlaufen, als die SAML-Bibliothek toleriert (bei onelogin/php-saml und SimpleSAMLphp standardmäßig 180 Sekunden), 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.

Die saml2-Extension ist eine Beta von 2014 für TYPO3 6.2

Die saml2-Extension im TER ist eine Beta: Version 1.0.0 von Youwe vom August 2014, die nur TYPO3 6.2 unterstützt. Eine neuere Version gibt es weder im TER noch auf Packagist; für aktuelle TYPO3-Versionen muss sie portiert oder ersetzt werden. Gosign prüft bei SSO-Projekten, ob die SAML-Bibliothek auf aktuellem Stand ist (Sicherheitspatches) und welche Extension zur eingesetzten TYPO3-Version passt. Weil die saml2-Extension nicht mehr gepflegt wird, empfehlen wir als Alternative die oidc-Extension, sofern der IdP OpenID Connect unterstützt.