Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • SensioLabs Professional services to help you with Symfony
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by
  1. Home
  2. Documentation
  3. Bundles
  4. SchebTwoFactorBundle
  5. Installation

Installation

Edit this page

Prerequisites

You're currently looking at the documentation of SchebTwoFactorBundle version 7. This bundle version is compatible with Symfony 6.4 or Symfony 7.x.

If you're using anything other than Doctrine ORM to manage the user entity you will have to implement a persister service.

Installation

Step 1: Install with Composer

The bundle is organized into sub-repositories, so you can choose the exact feature set you need and keep installed dependencies to a minimum.

If you're using Symfony Flex, use the following command to install the bundle via Composer:

1
composer require 2fa

Alternatively, use the following Composer command:

1
composer require scheb/2fa-bundle

Optionally, install any additional packages to extend the bundle's feature according to your needs:

1
2
3
4
5
composer require scheb/2fa-backup-code            # Add backup code feature
composer require scheb/2fa-trusted-device         # Add trusted devices feature
composer require scheb/2fa-totp                   # Add two-factor authentication using TOTP
composer require scheb/2fa-google-authenticator   # Add two-factor authentication with Google Authenticator
composer require scheb/2fa-email                  # Add two-factor authentication using email

Note

There are 3rd-party packages for adding different two-factor authentication methods. Check out the related packages on Packagist.org.

Step 2: Enable the bundle

Note

If you're using Symfony Flex, this step happens automatically.

Enable this bundle in your config/bundles.php:

1
2
3
4
return [
    // ...
    Scheb\TwoFactorBundle\SchebTwoFactorBundle::class => ['all' => true],
];

Step 3: Define routes

Note

If you're using Symfony Flex, a default config file is created automatically. Though make sure the preconfigured paths are located within your firewall's pattern.

In config/routes/scheb_2fa.yaml (create the file if it doesn't exist) you need to add two routes:

  • a route for the two-factor authentication form
  • another route for checking the two-factor authentication code

The routes must be located within the path pattern of the firewall, the one which uses two-factor authentication.

1
2
3
4
5
6
7
8
9
10
# config/routes/scheb_2fa.yaml
2fa_login:
    path: /2fa
    defaults:
        # "scheb_two_factor.form_controller" references the controller service provided by the bundle.
        # You don't HAVE to use it, but - except you have very special requirements - it is recommended.
        _controller: "scheb_two_factor.form_controller::form"

2fa_login_check:
    path: /2fa_check

If you have multiple firewalls with two-factor authentication, each one needs its own set of login and check routes that must be located within the associated firewall's path pattern.

Step 4: Configure the firewall

Enable two-factor authentication per firewall and configure access_control for the 2fa routes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            two_factor:
                auth_form_path: 2fa_login    # The route name you have used in the routes.yaml
                check_path: 2fa_login_check  # The route name you have used in the routes.yaml

    # The path patterns shown here have to be updated according to your routes.
    # IMPORTANT: ADD THESE ACCESS CONTROL RULES AT THE VERY TOP OF THE LIST!
    access_control:
        # This makes the logout route accessible during two-factor authentication. Allows the user to
        # cancel two-factor authentication, if they need to.
        - { path: ^/logout, role: PUBLIC_ACCESS }
        # This ensures that the form can only be accessed when two-factor authentication is in progress.
        - { path: ^/2fa, role: IS_AUTHENTICATED_2FA_IN_PROGRESS }
        # Other rules may follow here...

More per-firewall configuration options can be found in the configuration reference.

Step 5: Configure the security tokens

Your firewall may offer different ways to login. By default (without any configuration), the bundle is listening only to these tokens:

  • Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken (username+password authentication)
  • Symfony\Component\Security\Http\Authenticator\Token\PostAuthenticationToken (default token used by authenticators)

If you want to support two-factor authentication with another login method, you have to register its token class in the scheb_two_factor.security_tokens configuration option.

1
2
3
4
5
6
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    security_tokens:
        - Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken
        - Symfony\Component\Security\Http\Authenticator\Token\PostAuthenticationToken
        - Acme\AuthenticationBundle\Token\CustomAuthenticationToken

Step 6: Enable two-factor authentication methods

If you have installed any of the two-factor authentication methods provided as sub-packages, you have to enable these separately. Read how to do this for:

  • scheb/2fa-totp TOTP authentication
  • scheb/2fa-google-authenticator Google Authenticator
  • scheb/2fa-email Code-via-Email authentication

Step 7: Detailed configuration

You probably want to configure some details of the bundle. See the all configuration options.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    Symfony Code Performance Profiling

    Symfony Code Performance Profiling

    Be safe against critical risks to your projects and businesses

    Be safe against critical risks to your projects and businesses

    Version:

    Table of Contents

    • Prerequisites
    • Installation
      • Step 1: Install with Composer
      • Step 2: Enable the bundle
      • Step 4: Configure the firewall
      • Step 5: Configure the security tokens
      • Step 6: Enable two-factor authentication methods
      • Step 7: Detailed configuration

    Symfony footer

    Avatar of Marc Verney, a Symfony contributor

    Thanks Marc Verney for being a Symfony contributor

    2 commits • 2 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • What is Symfony?
      • Symfony at a Glance
      • Symfony Components
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • Symfony Community
      • SymfonyConnect
      • Events & Meetups
      • Projects using Symfony
      • Contributors
      • Symfony Jobs
      • Backers
      • Code of Conduct
      • Downloads Stats
      • Support
    • Blog

      • All Blog Posts
      • A Week of Symfony
      • Case Studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Living on the edge
      • Releases
      • Security Advisories
      • Symfony Insight
      • Twig
      • SensioLabs Blog
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Powered by

    Follow Symfony