OIDC für TYPO3

Wie TYPO3-Projekte ohne eigenen Identity-Stack an Azure AD, Keycloak oder Okta anschließen

In jedem Unternehmen, das Microsoft 365, Google Workspace oder einen zentralen Keycloak betreibt, ist die Benutzerverwaltung längst entschieden: Alle Mitarbeiter-Accounts leben im IdP, und jede neue Anwendung soll sich dort anbinden, nicht eigene Passwörter verwalten. Die OIDC-Extension für TYPO3 bedient genau dieses Muster, indem sie OpenID Connect als Auth-Protokoll in TYPO3 einbettet und damit Azure AD, Keycloak, Okta, Google Workspace oder Auth0 als IdP nutzbar macht, ohne einen eigenen Shibboleth SP betreiben zu müssen. Zielgruppe sind Unternehmens-Portale, Intranets, Kunden-Login-Bereiche und alle TYPO3-Setups, die in bestehende Enterprise-Identitätslandschaften hineingehören.

Typische Einsatzszenarien

Ein Maschinenbau-Konzern mit 14.000 Mitarbeitern betreibt sein Mitarbeiter-Intranet auf TYPO3. Der IT-Betrieb hat längst entschieden, dass jede neue Anwendung gegen Azure AD authentifiziert und Multi-Factor-Authentication dort durchsetzt. Die OIDC-Extension holt sich die ID-Tokens aus Azure AD, liest die im Claim enthaltenen Gruppenzuordnungen und erzeugt daraus fe_user-Gruppen. Das Intranet bekommt Single Sign-On, MFA und Conditional Access ohne zusätzliche Infrastruktur, allein durch saubere Konfiguration.

Ein zweites Szenario kommt aus dem Mittelstand: Ein Softwareanbieter mit einem Kunden-Portal auf TYPO3 setzt Keycloak als zentralen Broker ein, weil die eigenen Kunden mit Usernames oder mit Social-Logins wie Google oder GitHub ankommen. Keycloak vereinheitlicht das und spricht nach außen OIDC. TYPO3 nutzt die OIDC-Extension und bekommt Zugriff auf alle Login-Varianten, ohne selbst zu wissen, dass es im Hintergrund Social-Login ist.

Der dritte Fall sind Behörden und Landesverwaltungen, die auf Keycloak-basierte Bürgerkonten wechseln. Ein TYPO3-Portal, über das Bürgerinnen und Bürger Antragsformulare einreichen, kann sich über die OIDC-Extension an den Landes-Keycloak anschließen. Das eID-Attribut aus dem Broker landet direkt im fe_user, und die Authentifizierungsstufe lässt sich über den acr-Claim auswerten.

Technische Architektur: Authorization-Code-Flow in TYPO3

OpenID Connect ist eine Authentifizierungs-Schicht auf OAuth 2.0, und die OIDC-Extension implementiert genau den Authorization-Code-Flow. Der Ablauf ist einfacher als SAML: TYPO3 leitet den Nutzer mit einem Authorization Request an den IdP um, erhält nach erfolgreicher Anmeldung einen Code zurück, tauscht diesen serverseitig gegen ein ID-Token und validiert die Signatur über die JSON Web Key Set (JWKS) des Providers. Die Claims aus dem ID-Token, typischerweise sub, email, name, groups und roles, werden auf TYPO3-User-Felder gemappt.

Konfiguriert wird die Extension über die TYPO3-Extension-Konfiguration und einen Discovery-Endpunkt, den jeder OIDC-konforme Provider unter /.well-known/openid-configuration anbietet. Die Extension liest aus dieser URL die Token-Endpunkte, die JWKS-URL und die unterstützten Flows automatisch, was manuelle Fehler reduziert. Claim-Mapping erfolgt über eine YAML- oder TypoScript-Konfiguration, die lokale Feldnamen auf Claim-Pfade abbildet.

Häufige Probleme und Lösungen

Das erste Problem betrifft Claim-Formate: Azure AD liefert Gruppen als Objekt-IDs (GUIDs), nicht als lesbare Namen. Wer einen Claim group_ids erwartet und group_names bekommt, sieht leere Benutzergruppen in TYPO3. Die saubere Lösung liegt in der Azure-AD-Applikation selbst: Im Token-Configuration-Blade lässt sich festlegen, welche Attribute als Claims ausgegeben werden, und zusätzlich kann ein Claim-Transformation-Regelwerk GUIDs auf lesbare Namen übersetzen.

Das zweite Problem ist die Redirect-URI. Jeder OIDC-Client muss beim IdP genau die Redirect-URI registrieren, zu der er nach dem Login geschickt wird. Unterschiede in Groß- und Kleinschreibung, vergessene Trailing-Slashes oder ein Wechsel von HTTP auf HTTPS verursachen sofortige Login-Fehler, die im TYPO3-Log nicht sichtbar sind, weil der Fehler beim IdP auftritt. Gosign konfiguriert für Staging und Production getrennte Clients mit sauberen Redirect-URIs und dokumentiert jede Änderung im Deployment-Prozess.

Das dritte Thema ist Token-Refresh. Wer längere Sessions wünscht, braucht Refresh-Tokens, die der IdP nur ausstellt, wenn der offline_access-Scope beim Login angefordert wurde. Ohne dieses Scope endet die TYPO3-Session, sobald das ID-Token abläuft, meist nach einer Stunde. Die Konfiguration im Extension-Backend muss daher den offline_access-Scope mitgeben und die Token-Refresh-Logik aktivieren.

Ein viertes Problem betrifft das Abmelden. OIDC kennt Front-Channel- und Back-Channel-Logout, und beide sind in der Extension nicht zwangsläufig aktiviert. Wer echtes Single Logout über mehrere Anwendungen hinweg erwartet, muss den entsprechenden End-Session-Endpunkt des Providers konfigurieren und sicherstellen, dass TYPO3 die Logout-URL des IdP beim Session-Ende aufruft. Ohne diese Konfiguration bleibt der Nutzer beim IdP weiter angemeldet, obwohl er sich in TYPO3 ausgeloggt hat.

Migration und Versions-Kompatibilität

Die OIDC-Extension ist aktuell der empfohlene Standard für TYPO3 v12 und v13, während ältere v11-Projekte häufig noch auf selbstgebaute OAuth-Implementierungen oder shibboleth_auth setzen. Der Migrationspfad von Shibboleth zu OIDC ist gut etabliert, sofern der IdP beides spricht: Keycloak, ADFS und Azure AD können SAML und OIDC parallel bedienen, sodass ein Übergang ohne Big-Bang möglich ist.

Wer von einer rein datenbankgestützten fe_user-Verwaltung migriert, muss die bestehenden Accounts mit einer Matching-Strategie auf die OIDC-Claims abbilden. Die E-Mail-Adresse ist dabei der übliche Anker, reicht aber nicht immer aus, weil sich Mail-Adressen ändern können. Ein Sub-Claim, der als eindeutige persistente Kennung im fe_user hinterlegt wird, ist die robustere Lösung. Gosign übernimmt diese Migrationen inklusive Abgleich bestehender Accounts und einer Übergangsphase, in der beide Auth-Wege parallel funktionieren.

Für Teams, die gerade ein neues TYPO3-Projekt aufsetzen, ist OIDC in den allermeisten Fällen die erste Wahl. Die Konfiguration ist schlanker als bei SAML, der Client-Aufwand geringer, und jeder moderne IdP unterstützt das Protokoll nativ. Ausnahmen sind nur dort gerechtfertigt, wo regulatorische oder föderative Vorgaben explizit SAML erfordern, wie in den bereits genannten Hochschul-Föderationen. In allen anderen Szenarien, insbesondere bei Cloud-basierten IdPs und Enterprise-Integrationen, liefert OIDC den besseren Kompromiss aus Einfachheit, Sicherheit und Wartbarkeit.