scheb/2fa-bundle

scheb/2fa-bundle is the core Symfony bundle of the scheb/2fa suite, providing a generic, provider-agnostic framework for adding two-factor authentication to Symfony applications. It integrates with Symfony’s security system to insert a second authentication step and coordinates one or more two-factor providers such as TOTP, email codes, and backup codes.

Rather than locking you into a single method, it defines the interfaces, event flow, and firewall integration that individual provider packages plug into, giving you a consistent 2FA experience with control over conditions, trusted devices, and the authentication UI.

What You Get

• Firewall integration that adds a two-factor step to Symfony’s authentication flow
• A provider interface so multiple 2FA methods (TOTP, email, backup codes) share one pipeline
• Event-driven hooks for customizing conditions, trusted devices, and completion handling
• A controller and templates for the two-factor challenge form

Common Use Cases

• Adding two-factor authentication to a Symfony application’s login flow
• Supporting multiple second-factor methods behind a single, consistent interface
• Customizing when 2FA is required and how the challenge is presented to users

Under The Hood

Architecture - The bundle wires into Symfony security via its Security directory, inserting a two-factor authenticator into the firewall that intercepts authenticated-but-not-yet-verified sessions. A Controller renders the challenge form, Model classes track authentication state, and DependencyInjection configuration exposes settings and registers provider services that implement the bundle’s two-factor interfaces.

Tech Stack - It is a PHP Symfony bundle (composer type symfony-bundle) built on a wide set of Symfony components including security-bundle, framework-bundle, http-kernel, event-dispatcher, twig-bundle, and property-access, and it is distributed as a read-only Composer split of the scheb/2fa monorepo.

Code Quality - The parent scheb/2fa project runs CI and tracks coverage with Codecov across all of its packages, and this core bundle is a long-lived, widely-adopted component with a mature, layered structure separating security, model, controller, and DI concerns.

API Design - The bundle is intentionally provider-agnostic: it defines interfaces and an event flow that provider packages implement, and exposes configuration for conditions, trusted-device handling, and the challenge UI. This keeps the core small while letting applications compose exactly the factors they need.