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. Korzysta ono z SimpleSAMLphp, czyli SAML 2.0 SP napisanego w PHP i działającego obok TYPO3. 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, która łączy polskie uczelnie i instytucje naukowe. 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 powierza weryfikację SAML-Assertion bibliotece SimpleSAMLphp i loguje odpowiedniego użytkownika frontendu TYPO3; przez jego grupy (np. studenci -> grupa “student”, wykładowcy -> grupa “staff”) TYPO3 steruje dostępem.

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 loguje ich jako użytkowników frontendu TYPO3, a ich grupy sterują dostępem do chronionych obszarów treści.

Architektura techniczna łączy SimpleSAMLphp jako SAML 2.0 SP z TYPO3

saml2 opiera się na SimpleSAMLphp, samodzielnej implementacji SAML 2.0 w PHP, która przejmuje AuthnRequest, walidację Response, parsowanie Assertion i weryfikację podpisu. SimpleSAMLphp instaluje się obok TYPO3; rozszerzenie ładuje je ze skonfigurowanej ścieżki i rejestruje się jako Authentication Service TYPO3 dla frontendu.

Konfiguracja rozkłada się na dwa miejsca. IdP i SP (metadane, Entity ID, certyfikaty) konfiguruje się w SimpleSAMLphp. W TYPO3 konfiguracja rozszerzenia zawiera ścieżkę do SimpleSAMLphp, profil SP i adres IdP, a TypoScript określa atrybut, po którym odnajdywany jest użytkownik TYPO3, oraz mapowanie atrybutów IdP na pola użytkownika frontendu. Logowanie rozpoczyna się przez plugin “SAML-Login” na stronie TYPO3 (SP-initiated SSO).

Rozszerzenie nie zakłada samo użytkowników frontendu: loguje istniejącego użytkownika, którego odnajduje po skonfigurowanym atrybucie (domyślnie: uid), i na życzenie aktualizuje jego pola przy każdym logowaniu. Nowe konta powstają przez rejestrację w femanager, do której rozszerzenie się podłącza.

Logowania do backendu (BE-User) przez SAML rozszerzenie nie oferuje, ponieważ rejestruje swój Authentication Service wyłącznie dla frontendu. Kto wprowadza SAML także dla backendu, ponosi większe ryzyko: gdy IdP padnie, dostęp do backendu jest niemożliwy. Zalecamy wtedy 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ę bardziej, niż toleruje biblioteka SAML (domyślnie 180 sekund w onelogin/php-saml i SimpleSAMLphp), 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.

Rozszerzenie saml2 to wersja beta z 2014 roku dla TYPO3 6.2

Rozszerzenie saml2 w TER jest wersją beta: to wydanie 1.0.0 firmy Youwe z sierpnia 2014, które obsługuje wyłącznie TYPO3 6.2. Nowszej wersji nie ma ani w TER, ani na Packagist; dla aktualnych wersji TYPO3 rozszerzenie wymaga portowania albo zastąpienia. Gosign przy projektach SSO sprawdza, czy biblioteka SAML jest aktualna (łatki bezpieczeństwa) i które rozszerzenie pasuje do używanej wersji TYPO3. Ponieważ rozszerzenie saml2 nie jest już utrzymywane, jako alternatywę polecamy rozszerzenie oidc, jeśli IdP wspiera OpenID Connect.