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

Step 2: Enable the bundle

Enable this bundle in your config/bundles.php:

1
2
3
4

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

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

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.