DOCSEARCHbyAlgolia
Submit Docs

scheb/2fa

repository·8.x·Indexed 20 days ago

https://github.com/scheb/2fa

A modular two-factor authentication bundle for Symfony applications. It provides a core bundle (scheb/2fa-bundle) with brute-force and CSRF protection, alongside specialized packages for TOTP, Google Authenticator, email-based authentication, backup codes, and trusted device support.

Tokens
30.9K
Snippets
101
Records
126
Agent score
69%

What's inside scheb/2fa

  1. Overview of SchebTwoFactorBundle

    8.x

    SchebTwoFactorBundle provides two-factor authentication (2FA) for Symfony applications. It integrates directly into the Symfony security layer by listening to authentication events.

    When a user logs in and has 2FA enabled, the bundle places the authentication into an intermediate state. Access and privileges are temporarily withheld until the user successfully provides a valid 2FA code. Only after successful 2FA completion are the user's full roles and IS_AUTHENTICATED_FULLY status granted.

  2. Overview of scheb/2fa features and sub-packages

    8.x

    The scheb/2fa bundle provides two-factor authentication for Symfony applications. It is modular, allowing you to install only the specific sub-packages you need to minimize dependencies.

    Core Bundle: scheb/2fa-bundle

    Provides the foundation, including:

    • Interface for custom two-factor authentication methods
    • Trusted IPs
    • Multi-factor authentication (more than 2 steps)
    • CSRF protection
    • Brute-force protection
    • Authentication code reuse protection
    • Whitelisted routes (accessible during two-factor authentication)
    • Customizable conditions for triggering two-factor authentication

    Additional Feature Packages

    • scheb/2fa-trusted-device: Allows users to bypass 2FA on recognized devices.
    • scheb/2fa-backup-code: Provides single-use backup codes for recovery.
    • QR code support for mobile device scanning.

    Authentication Methods

    • scheb/2fa-totp: Time-based One-time Password algorithm.
    • scheb/2fa-google-authenticator: Google Authenticator support.
    • scheb/2fa-email: Authentication via email codes.

  3. Overview of scheb/2fa-trusted-device

    8.x
    The scheb/2fa-trusted-device package provides trusted device support for Symfony applications using the scheb/2fa-bundle. It allows users to mark specific devices as 'trusted' to bypass or simplify the two-factor authentication process on subsequent logins.

  5. Use scheb/2fa-email for email-based 2FA

    8.x
    This package provides the implementation for two-factor authentication via email. It works as a sub-component of the scheb/2fa ecosystem and extends the capabilities of scheb/2fa-bundle by adding email as a valid 2FA method.

  6. Use scheb/2fa-backup-code for backup code support

    8.x
    The scheb/2fa-backup-code package extends the core scheb/2fa-bundle by adding support for backup codes. This allows users to authenticate using pre-generated backup codes if they lose access to their primary two-factor authentication method (like an OTP app).

  7. Implement a custom 2FA Persister

    8.x
    By default, the bundle uses Doctrine to persist two-factor data in the user object. If your user entity is managed by something else (e.g., an external API), you must implement a custom persister by implementing the Scheb\TwoFactorBundle\Model\PersisterInterface.

  8. Prerequisites for Two-Factor Authentication in an API

    8.x

    To use two-factor authentication in a Symfony API, your firewall must be stateful (stateless: false or not configured, as stateful is the default). The session is required to track whether the user has completed the two-factor authentication process.

    If using a custom authenticator, ensure it does not authenticate on every request, but only when the specific authentication route is called.

  9. How the 2FA authentication process works

    8.x

    The bundle manages the transition between a standard login and a fully authenticated session using a specific intermediate state.

    During the 2FA challenge, the user is granted a temporary attribute similar to a role: IS_AUTHENTICATED_2FA_IN_PROGRESS. You can use this attribute in is_granted() calls to detect if a user is currently in the middle of the 2FA process.

    Crucially, the standard IS_AUTHENTICATED_FULLY attribute is withheld until the two-factor authentication step is completed successfully. This ensures that users cannot access protected resources that require full authentication until they have passed the 2FA check.

  11. Configure the 2FA firewall and access control

    8.x

    Enable 2FA within your firewall configuration by specifying the auth_form_path and check_path (referencing the route names defined in your routes file).

    Important: You must add specific access_control rules at the very top of your list:

    1. Allow PUBLIC_ACCESS to the /logout path so users can cancel 2FA.
    2. Restrict the 2FA form path (e.g., /2fa) to the IS_AUTHENTICATED_2FA_IN_PROGRESS role to ensure it is only accessible during the 2FA process.
    # config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            two_factor:
                auth_form_path: 2fa_login    # Route name from routes.yaml
                check_path: 2fa_login_check  # Route name from routes.yaml

    access_control:
        # MUST BE AT THE TOP
        - { path: ^/logout, role: PUBLIC_ACCESS }
        - { path: ^/2fa, role: IS_AUTHENTICATED_2FA_IN_PROGRESS }
        # ... other rules

  12. Run the local demo application

    8.x
    To test two-factor authentication in a real Symfony environment, you can set up the small test application included in this repository. Detailed instructions are located in the app/README.md file.