#110448Modernizing TYPO3 Authentication — Phase 1: The Authentication Pipeline
Description
Why we are doing this
Authentication is some of the oldest code we have in TYPO3. AbstractUserAuthentication dates back to the early 2000s, and it shows: it is a god class that fetches sessions, sniffs login credentials out of POST data on every single request, runs a string-typed ““auth service”” chain (T3_SERVICES, numeric priorities, addService()) that predates dependency injection by 15 years, sets cookies, writes log entries and mutates global state ($GLOBALS['BE_USER'], $GLOBALS['TSFE']->fe_user) along the way.
The practical pains coming out of this:
- Login is buried in
start(), not explicit. In the backend, any request carrying the right POST fields triggers authentication — there is no login route, which makes SSO integrations, rate limiting and auditing unnecessarily hard. In the frontend, ““the login form can live on any page”” is a feature everybody uses (felogin posts back to the page you are on) and we keep it — but the way it works today is the same credential sniffing on every single request, impossible to reason about or extend. - Extending authentication means registering a legacy service with magic numbers (what does
processLoginDatareturning200mean again?), no types, no DI. Every SSO/LDAP extension author suffers through this. - MFA is bolted on via an exception (
MfaRequiredException) that only the backend knows how to catch. Frontend MFA is structurally impossible right now. - No concept for machine/API authentication. Tokens, service accounts, headless — everything has to fake being a cookie-based user.
- You cannot test it. The 235-line
checkAuthentication()method had no dedicated test coverage until we wrote characterization tests in Phase 0.
What Phase 1 introduces
Phase 1 puts a small, boring, typed pipeline underneath the existing behavior. No behavior changes for users, no changes for extensions — the new code is internal@ for now and the old APIs keep working.
The new pieces and what each one is responsible for:
- @Principal@ — an immutable value object answering ““who is authenticated?”“: user id, realm, username, groups, claims, how they authenticated (password? session?) and when. This is the thing the rest of the system should care about — not a 1500-line user object.
- @Realm@ — answers ““authenticated where?”“: backend, or frontend per site. It also knows which routes don’t need authentication (currently the hard-coded public route list from the middleware).
- @AuthenticatorInterface@ — one strategy for proving identity. Each authenticator says whether it applies to a request (
supports()) and returns exactly one of four typed results:Authenticated(here is a Principal),Challenge(I need more — e.g. an MFA response to redirect to),Failure(wrong password) orNotApplicable. This replaces the numeric service return codes. - @AuthenticationManager@ — runs the DI-tagged authenticators in priority order, first conclusive result wins. That’s the whole class. Registering a custom authenticator becomes: implement an interface, tag a service.
- Native
SessionAuthenticator+PasswordAuthenticator(BE and FE) — reimplement what the legacyAuthenticationServicechain does for a plain install: session lookup, password check with rehash-on-login, rate limiting, request-token check, session fixation protection. In the backend, password handling is now bound to the login routes. In the frontend, the trigger stays what it is today — an explicitlogintype=loginparameter on whatever page the login plugin sits on, because login-on-any-page is a feature, not an accident. The difference: the trigger is now an explicit, testable condition (parameter + signed request token) instead of code buried deep in the user object. - @LocalIdentityProvider@ — the one place that looks up be_users/fe_users rows (enable fields, storage pids). Authenticators don’t build queries anymore.
- Legacy wrappers + detector — the entire old service chain is wrapped as one authenticator. As soon as an extension registers an auth service, we detect that and run the full legacy chain exactly as before. Clean installs run the native path. Nothing breaks either way.
- MFA as a
Challenge— instead of throwing an exception, the pipeline returns a redirect/401 response. Same backend behavior as today, but the mechanism is realm-agnostic, which is what will eventually enable frontend MFA. - @UserAspect@ — becomes an immutable snapshot and can be built from a
Principaldirectly, cutting the core→frontend dependency it had.
The honest downsides
- We temporarily have two implementations of login (native + wrapped legacy chain). That’s the price for not breaking a single existing SSO extension. Characterization and functional tests pin both paths to the same behavior.
- The native path has two deliberate behavior changes: credentials POSTed to arbitrary backend URLs are ignored (BE login belongs to the login routes; frontend login-on-any-page is untouched), and MFA redirects instead of throwing. We consider both features, not regressions.
- The pipeline is
internal@ in 15.0. Extension authors should look, comment — but not build on it yet. It becomes public API once the login endpoints (end of Phase 1) settle. - The god classes are still there. Phase 1 changes who is in charge, not yet who holds the data.
Where this is going
Phase 1 is the foundation everything else plugs into:
- Phase 2 — Identity & machine auth:
sys_identityaccount linking,sys_token+TokenAuthenticatorwith scopes, service accounts (bye_cli_), a statelessapirealm for headless. - Phase 3 — Federation: an OIDC sysext (login button, PKCE, back-channel logout), passkeys/WebAuthn, frontend MFA — all just more authenticators and challenges on the same pipeline.
- Phase 4 — Decoupling:
$GLOBALS['BE_USER']replaced by Principal + Context, permissions extracted from the user class, preview/simulation as derived Principals instead of in-place mutation. - v16: the legacy service chain,
checkAuthentication()and friends are removed. Everything new lands and gets deprecated within v15 — v16 only deletes.
Reviews 23
- main 97756[TASK] Share session resolution of native authenticators
- main 96580[TASK] Add check whether a user may read a record
- main 95783[TASK] Provide the principal to the authorization checker
- main 97746[TASK] Share password check of native authenticators
- main 95288[FEATURE] Add native frontend authenticators
- main 95287[FEATURE] Add native backend authenticators
- main 95284[TASK] Authenticate users via the auth pipeline
- main 96561[TASK] Initialize stateless backend users from a principal
- main 96556[TASK] Add authentication pipeline contracts
- main 96393[TASK] Add auth principal and local identity provider
- main 95782[FEATURE] Implement Symfony UserInterface on auth objects
- main 95787[TASK] Deprecate auth services and addService('auth')
- main 95785[FEATURE] Register tagged authenticators and AuthenticatorManager
- main 95786[FEATURE] Authenticate via AuthenticatorManager in user middlewares
- main 96660[TASK] Derive argument schemas from signatures
- main 96582[TASK] Use the record read access check in backend
- main 96581[TASK] Add query restriction for records a user may read
- main 96682[FEATURE] Add MCP system extension and endpoint
- main 95289[FEATURE] Allow creating UserAspect from a Principal
- main 95286[TASK] Process frontend authentication via authentication pipeline
- main 95285[TASK] Process backend authentication via authentication pipeline
- main 95209[FEATURE] Add route option to allow backend routes without user
- main 95283[TASK] Make UserAspect an immutable snapshot
Subtasks 8
- Task #110924Add new classes for separation of concerns for Identity and Local DB Provider
- Task #110971Add authentication pipeline contracts
- Feature #110972Resolve backend and frontend authentication through the authentication pipeline
- Task #110977Add factory to build backend users from an authentication principal
- Task #111006Derive argument schemas from method signatures
- Feature #111399Add native backend authenticators
- Feature #111400Add native frontend authenticators
- Task #111470Share password verification between native backend and frontend authenticators
Related issues 3
History 13
-
Georg Ringer changed status
NewAccepted <span data-processor="relativetime" data-value="2026-08-12T14:01:29+00:00" > 08/12/26, 14:01 </span> -
Georg Ringer changed Related to #108298 <span data-processor="relativetime" data-value="2026-08-13T09:24:28+00:00" > 08/13/26, 09:24 </span>
-
Simon Schaufelberger changed Related to #109183 <span data-processor="relativetime" data-value="2026-08-14T11:56:11+00:00" > 08/14/26, 11:56 </span>
-
Benni Mack changed subtask #110924 <span data-processor="relativetime" data-value="2026-10-06T07:55:35+00:00" > 10/06/26, 07:55 </span>
-
Oliver Bartsch changed Related to #110971 <span data-processor="relativetime" data-value="2026-10-08T21:24:34+00:00" > 10/08/26, 21:24 </span>
-
Oliver Bartsch changed subtask #110971 <span data-processor="relativetime" data-value="2026-10-08T21:25:58+00:00" > 10/08/26, 21:25 </span>
-
Oliver Bartsch changed subtask #110972 <span data-processor="relativetime" data-value="2026-10-08T21:26:37+00:00" > 10/08/26, 21:26 </span>
-
Oliver Bartsch changed subtask #110977 <span data-processor="relativetime" data-value="2026-10-09T11:26:13+00:00" > 10/09/26, 11:26 </span>
-
Oliver Bartsch changed subtask #111006 <span data-processor="relativetime" data-value="2026-10-09T21:52:32+00:00" > 10/09/26, 21:52 </span>
-
Benni Mack changed Related to #111235 <span data-processor="relativetime" data-value="2026-10-25T14:15:10+00:00" > 10/25/26, 14:15 </span>
-
Benni Mack changed subtask #111399 <span data-processor="relativetime" data-value="2026-11-10T18:12:52+00:00" > 11/10/26, 18:12 </span>
-
Benni Mack changed subtask #111400 <span data-processor="relativetime" data-value="2026-11-10T18:13:10+00:00" > 11/10/26, 18:13 </span>
-
Oliver Bartsch changed subtask #111470 <span data-processor="relativetime" data-value="2026-11-17T10:08:39+00:00" > 11/17/26, 10:08 </span>