Issue Epic Accepted

#110448Modernizing TYPO3 Authentication — Phase 1: The Authentication Pipeline

Benni Mack 08/12/26, 11:11 updated 11/17/26, 16:10

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 processLoginData returning 200 mean 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) or NotApplicable. 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 legacy AuthenticationService chain 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 explicit logintype=login parameter 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 Principal directly, 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_identity account linking, sys_token + TokenAuthenticator with scopes, service accounts (bye _cli_), a stateless api realm 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

Subtasks 8

History 13