SAML2 dla TYPO3

SAML 2.0 umożliwia Single Sign-On w TYPO3 bez instalacji Shibboleth na serwerze

Uczelnie, urzędy i koncerny prowadzą Identity Providers (IdP) oparte o SAML 2.0: Microsoft ADFS, Okta, Keycloak, PingFederate. Kto chciał wykorzystać te tożsamości w TYPO3, dotąd potrzebował Shibboleth Service Provider na serwerze WWW, czyli dodatkowej warstwy oprogramowania z własną konfiguracją, własnymi certyfikatami i osobnym utrzymaniem. Rozszerzenie TYPO3 saml2 sprawia, że Shibboleth SP jest zbędny. Implementuje ono SAML 2.0 SP bezpośrednio w PHP i komunikuje się z IdP bez middleware. Znacząco upraszcza to architekturę serwera, zwłaszcza w środowiskach shared hosting lub w deploymentach kontenerowych, gdzie Shibboleth SP trudno zainstalować.

Dla organizacji, których IdP nie wspiera OIDC (OpenID Connect), SAML 2.0 jest jedyną ustandaryzowaną drogą do Single Sign-On. Rozszerzenie wypełnia dokładnie tę lukę w ekosystemie TYPO3.

Typowe scenariusze dotyczą uczelnianych intranetów, portali urzędów i ekstranetów koncernów

Najczęstszym scenariuszem jest intranet uczelniany. Uniwersytet prowadzi Shibboleth IdP w federacji PIONIER.Id lub w ramach federacji USOS, łączącej polskie szkoły wyższe. Studenci i pracownicy logują się swoim identyfikatorem uczelnianym i otrzymują dostęp do chronionych stron TYPO3: skryptów, wewnętrznych komunikatów, wyników egzaminów. Rozszerzenie saml2 sprawdza token SAML-Assertion, w razie potrzeby zakłada użytkownika frontendu TYPO3 i przypisuje grupy na podstawie atrybutów IdP (np. studenci -> grupa “student”, wykładowcy -> grupa “staff”).

Drugim scenariuszem są portale urzędowe z integracją profilu zaufanego. Profil Zaufany ePUAP udostępnia interfejs SAML, który gminy i urzędy mogą podłączyć do swojej witryny TYPO3 przez saml2. Obywatele logują się Profilem Zaufanym i uzyskują dostęp do spersonalizowanych usług elektronicznych, np. wniosków, harmonogramów posiedzeń rady gminy czy dokumentów do pobrania.

Trzeci scenariusz: ekstranety koncernów. Producent samochodów prowadzi portal dla dilerów na TYPO3. Dilerzy logują się przez IdP koncernu (Microsoft ADFS) i widzą cenniki, materiały szkoleniowe oraz formularze zamówień przypisane do ich grupy. Rozszerzenie saml2 mapuje grupy ADFS na grupy frontendu TYPO3 i steruje w ten sposób dostępem do chronionych obszarów treści.

Architektura techniczna implementuje SAML 2.0 SP jako bibliotekę PHP w TYPO3

saml2 opiera się na bibliotece PHP onelogin/php-saml (lub jej odpowiedniku), która w pełni pokrywa profil SAML 2.0 Web Browser SSO: AuthnRequest, walidacja Response, parsowanie Assertion, weryfikacja podpisu, logout. Biblioteka jest dołączana jako zależność Composera i rejestrowana przez rozszerzenie jako Authentication Service TYPO3.

Konfiguracja odbywa się w backendzie TYPO3 lub przez TypoScript: URL metadanych IdP (lub ręcznie: Entity ID, SSO-URL, SLO-URL, certyfikat), Entity ID SP, mapowanie atrybutów (który atrybut IdP odpowiada któremu polu TYPO3: email, username, firstname, lastname, groups). Rozszerzenie wspiera zarówno SP-initiated SSO (użytkownik klika “Login” na stronie TYPO3), jak i IdP-initiated SSO (użytkownik trafia bezpośrednio z portalu IdP).

Użytkownicy frontendu są zakładani automatycznie przy pierwszym logowaniu i aktualizowani przy każdym kolejnym. Przypisywanie grup można konfigurować statycznie (wszyscy użytkownicy SAML w grupie X) lub dynamicznie (atrybut IdP “role” = “admin” staje się grupą TYPO3 “admin”).

Dla logowania backendu (BE-User) SAML również jest konfigurowalny, jednak z większym ryzykiem: gdy IdP padnie, dostęp do backendu jest niemożliwy. Zalecamy zachowanie przynajmniej jednego lokalnego konta administratora jako fallback.

Częste problemy dotyczą certyfikatów, odchyleń czasu i mapowania atrybutów

Najczęstszym problemem przy integracjach SAML są wygasłe lub błędnie skonfigurowane certyfikaty. IdP podpisuje SAML-Response swoim certyfikatem. Gdy certyfikat na SP nie zostanie zaktualizowany po jego rotacji w IdP, weryfikacja podpisu się nie powiedzie i logowanie zakończy się kryptycznym błędem. Rozwiązanie: rotację certyfikatów wpisać do kalendarza utrzymania. Większość IdP daje 30 dni wyprzedzenia przed rotacją.

Drugi problem: odchylenia czasu między IdP a SP. Assercje SAML mają okno czasowe (NotBefore / NotOnOrAfter). Gdy zegary systemowe serwera IdP i serwera TYPO3 rozjeżdżają się o więcej niż 120 sekund, asercja jest odrzucana jako nieważna. Rozwiązanie: skonfigurować NTP na obu serwerach.

Trzeci temat: błędne mapowanie atrybutów. Każdy IdP nazywa atrybuty inaczej. Microsoft ADFS dostarcza “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”, Keycloak dostarcza “email”, Shibboleth dostarcza “urn:oid:0.9.2342.19200300.100.1.3”. Rozszerzenie musi wiedzieć, pod jaką nazwą atrybut email znajduje się w tokenie SAML. Błędne mapowanie prowadzi do pustych pól w profilu użytkownika TYPO3. Logowanie debug otrzymywanych atrybutów pomaga zidentyfikować właściwe klucze mapowania.

TYPO3 v12 jest wspierany, kompatybilność z v13 zależy od API Authentication Service

Rozszerzenie saml2 rejestruje się jako Authentication Service TYPO3. To API w core TYPO3 jest stabilne od lat, ale w v12 i v13 zostało w pojedynczych miejscach dostosowane. Aktualna wersja rozszerzenia działa stabilnie pod v12. Dla v13 rejestracja Authentication Service musi być dostosowana do nowej konfiguracji service’ów. Gosign przy projektach SSO sprawdza, czy biblioteka PHP-SAML jest aktualna (łatki bezpieczeństwa) i czy rozszerzenie jest kompatybilne z używaną wersją TYPO3. Gdy rozszerzenie społecznościowe nie jest już utrzymywane, jako alternatywę polecamy rozszerzenie oidc, jeśli IdP wspiera OpenID Connect.