OIDC dla TYPO3

Jak projekty TYPO3 bez własnego stosu tożsamości podłączają się do Azure AD, Keycloak lub Okta

W każdej firmie, która prowadzi Microsoft 365, Google Workspace lub centralny Keycloak, zarządzanie użytkownikami jest już dawno rozstrzygnięte: wszystkie konta pracownicze żyją w IdP, a każda nowa aplikacja ma się tam podłączać, a nie zarządzać własnymi hasłami. Rozszerzenie OIDC dla TYPO3 obsługuje dokładnie ten wzorzec, osadzając OpenID Connect jako protokół uwierzytelniania w TYPO3 i tym samym udostępniając Azure AD, Keycloak, Okta, Google Workspace lub Auth0 jako IdP, bez konieczności prowadzenia własnego Shibboleth SP. Grupą docelową są portale firmowe, intranety, obszary logowania klienta i wszystkie instalacje TYPO3, które mają się wpasować w istniejące enterprise’owe krajobrazy tożsamości.

Typowe scenariusze zastosowania

Koncern maszynowy z 14 000 pracowników prowadzi swój intranet pracowniczy na TYPO3. Dział IT już dawno zdecydował, że każda nowa aplikacja uwierzytelnia się przez Azure AD i wymusza tam Multi-Factor-Authentication. Rozszerzenie OIDC pobiera ID-Tokens z Azure AD, odczytuje przypisania grup zawarte w claimie i tworzy z tego grupy fe_user. Intranet otrzymuje Single Sign-On, MFA i Conditional Access bez dodatkowej infrastruktury, wyłącznie przez porządną konfigurację.

Drugi scenariusz pochodzi z sektora MSP: dostawca oprogramowania z portalem klienta na TYPO3 używa Keycloak jako centralnego brokera, bo jego klienci przychodzą z loginami użytkowników albo z social-loginami jak Google czy GitHub. Keycloak ujednolica to i mówi na zewnątrz OIDC. TYPO3 używa rozszerzenia OIDC i otrzymuje dostęp do wszystkich wariantów logowania, samo nie wiedząc, że w tle działa social-login.

Trzeci przypadek to urzędy i administracje wojewódzkie, które przechodzą na konta obywatelskie oparte na Keycloak. Portal TYPO3, przez który obywatele składają wnioski, może przez rozszerzenie OIDC podłączyć się do wojewódzkiego Keycloak. Atrybut eID z brokera ląduje bezpośrednio w fe_user, a poziom uwierzytelnienia można ocenić przez claim acr.

Architektura techniczna: Authorization-Code-Flow w TYPO3

OpenID Connect to warstwa uwierzytelniania na OAuth 2.0, a rozszerzenie OIDC implementuje dokładnie Authorization-Code-Flow. Przebieg jest prostszy niż SAML: TYPO3 przekierowuje użytkownika z Authorization Request do IdP, po pomyślnym zalogowaniu otrzymuje z powrotem kod, wymienia go po stronie serwera na ID-Token i waliduje podpis przez JSON Web Key Set (JWKS) providera. Claimy z ID-Tokena, zazwyczaj sub, email, name, groups i roles, są mapowane na pola użytkownika TYPO3.

Konfiguracja rozszerzenia odbywa się przez konfigurację rozszerzenia TYPO3 i Discovery-Endpoint, który każdy provider zgodny z OIDC udostępnia pod /.well-known/openid-configuration. Rozszerzenie odczytuje z tego URL-a endpointy tokena, URL JWKS i wspierane flows automatycznie, co redukuje manualne błędy. Claim-mapping odbywa się przez konfigurację YAML lub TypoScript, która odwzorowuje lokalne nazwy pól na ścieżki claim.

Częste problemy i rozwiązania

Pierwszy problem dotyczy formatów claim: Azure AD dostarcza grupy jako ID obiektów (GUID), a nie jako czytelne nazwy. Kto oczekuje claimu group_ids, a otrzymuje group_names, widzi puste grupy użytkowników w TYPO3. Porządne rozwiązanie leży w samej aplikacji Azure-AD: w bloku Token-Configuration można ustalić, które atrybuty są zwracane jako claimy, a dodatkowo regułowy zestaw Claim-Transformation może przekładać GUID na czytelne nazwy.

Drugi problem to Redirect-URI. Każdy klient OIDC musi zarejestrować w IdP dokładnie ten Redirect-URI, do którego jest odsyłany po zalogowaniu. Różnice w wielkości liter, zapomniane slashe końcowe albo przejście z HTTP na HTTPS powodują natychmiastowe błędy logowania, które nie są widoczne w logu TYPO3, bo błąd występuje w IdP. Gosign konfiguruje oddzielnych klientów dla staging i production z czystymi Redirect-URI i dokumentuje każdą zmianę w procesie deploymentu.

Trzeci temat to odświeżanie tokenów. Kto chce dłuższych sesji, potrzebuje Refresh-Tokens, które IdP wystawia tylko wtedy, gdy scope offline_access został zażądany przy logowaniu. Bez tego scope sesja TYPO3 kończy się, gdy tylko wygasa ID-Token, zwykle po godzinie. Konfiguracja w backendzie rozszerzenia musi zatem przekazywać scope offline_access i aktywować logikę odświeżania tokenów.

Czwarty problem dotyczy wylogowania. OIDC zna Front-Channel i Back-Channel-Logout i oba nie zawsze są aktywne w rozszerzeniu. Kto oczekuje prawdziwego Single Logout na wielu aplikacjach, musi skonfigurować odpowiedni End-Session-Endpoint providera i zapewnić, że TYPO3 wywołuje URL wylogowania IdP przy końcu sesji. Bez tej konfiguracji użytkownik pozostaje zalogowany w IdP, mimo że wylogował się z TYPO3.

Migracja i kompatybilność wersji

Rozszerzenie OIDC jest obecnie zalecanym standardem dla TYPO3 v12 i v13, podczas gdy starsze projekty v11 często jeszcze używają samoróbek OAuth lub shibboleth_auth. Ścieżka migracji z Shibboleth na OIDC jest dobrze ugruntowana, o ile IdP mówi oboma protokołami: Keycloak, ADFS i Azure AD potrafią obsługiwać SAML i OIDC równolegle, dzięki czemu przejście bez big-bang jest możliwe.

Kto migruje z czysto bazodanowego zarządzania fe_user, musi odwzorować istniejące konta na claimy OIDC za pomocą strategii matchingu. Adres e-mail jest typowym kotwicznym identyfikatorem, ale nie zawsze wystarcza, bo adresy mailowe mogą się zmieniać. Claim sub, zapisany jako trwały unikalny identyfikator w fe_user, jest bardziej solidnym rozwiązaniem. Gosign przejmuje takie migracje wraz z dopasowaniem istniejących kont i okresem przejściowym, w którym oba ścieżki uwierzytelniania działają równolegle.

Dla zespołów, które właśnie uruchamiają nowy projekt TYPO3, OIDC jest w zdecydowanej większości przypadków pierwszym wyborem. Konfiguracja jest smuklejsza niż przy SAML, nakład pracy klienta mniejszy, a każdy nowoczesny IdP natywnie wspiera protokół. Wyjątki są uzasadnione tylko tam, gdzie wymagania regulacyjne lub federacyjne wyraźnie wymagają SAML, jak we wspomnianych federacjach akademickich. We wszystkich innych scenariuszach, zwłaszcza przy chmurowych IdP i integracjach enterprise, OIDC dostarcza lepszy kompromis między prostotą, bezpieczeństwem i utrzymywalnością.