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 przypisuje użytkownika do pasujących grup 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 Access-Token i pobiera nim dane użytkownika z endpointu UserInfo providera. Claimy z tej odpowiedzi, zazwyczaj sub, email, name, groups i roles, są mapowane na pola użytkownika TYPO3.

Konfiguracja rozszerzenia odbywa się przez konfigurację rozszerzenia TYPO3, w której endpointy autoryzacji, tokena i UserInfo providera wpisuje się pojedynczo. Wartości te podaje dokument discovery, który każdy provider zgodny z OIDC udostępnia pod /.well-known/openid-configuration. Claim-mapping dla fe_users odbywa się przez konfigurację 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 po zalogowaniu dalej korzysta z Access-Tokena, na przykład do wywołań API w IdP, potrzebuje Refresh-Tokens, które IdP wystawia tylko wtedy, gdy scope offline_access został zażądany przy logowaniu. Sesja TYPO3 od tego nie zależy: jej długość ustala samo TYPO3, nawet gdy token wygaśnie, zwykle po godzinie. Kto potrzebuje Refresh-Tokens, dodaje scope offline_access w konfiguracji rozszerzenia; świeży token pobiera własny kod przez metodę getFreshAccessToken() rozszerzenia.

Czwarty problem dotyczy wylogowania. OIDC zna Front-Channel i Back-Channel-Logout; rozszerzenie nie obsługuje żadnego z nich, więc wylogowanie u providera trzeba podłączyć samodzielnie. 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 obsługuje obecnie TYPO3 od v12 do v14 (5.x dla v12 i v13, 6.x dla v13 i v14), 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 w 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ą.