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 SensioLabs
  1. Home
  2. Documentation
  3. Bundles
  4. SchebTwoFactorBundle
  5. Installation
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

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

Installation

Edit this page

Installation

Prerequisites

You're currently looking at the documentation of SchebTwoFactorBundle version 5. This bundle version is compatible with Symfony 4.4 or Symfony 5.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
6
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
composer require scheb/2fa-qr-code                # Add to render QR-codes for Google Authenticator / TOTP

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: IS_AUTHENTICATED_ANONYMOUSLY }
        # 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 form)
  • Symfony\Component\Security\Guard\Token\PostAuthenticationGuardToken (guard-based security)
  • Symfony\Component\Security\Http\Authenticator\Token\PostAuthenticationToken (authenticator-based security)

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
7
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    security_tokens:
        - Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken
        - Symfony\Component\Security\Guard\Token\PostAuthenticationGuardToken
        - 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
    We stand with Ukraine.
    Version:
    Show your Sylius expertise

    Show your Sylius expertise

    Code consumes server resources. Blackfire tells you how

    Code consumes server resources. Blackfire tells you how

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Luca Lorenzini, a Symfony contributor

    Thanks Luca Lorenzini for being a Symfony contributor

    1 commit • 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?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • 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

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

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

      Deployed on

    Follow Symfony

    Search by Meilisearch