安装

编辑此页

前提条件

您目前正在查看 SchebTwoFactorBundle 版本 7 的文档。此扩展包版本兼容 Symfony 6.4 或 Symfony 7.x。

如果您使用 Doctrine ORM 以外的任何东西来管理用户实体，您将必须实现一个 持久化服务。

安装

步骤 1：使用 Composer 安装

该捆绑包被组织成子仓库，因此您可以选择您需要的确切功能集，并将已安装的依赖项保持在最低限度。

如果您正在使用 Symfony Flex，请使用以下命令通过 Composer 安装捆绑包

1
composer require 2fa

或者，使用以下 Composer 命令

1
composer require scheb/2fa-bundle

可选地，安装任何额外的包以根据您的需求扩展捆绑包的功能

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

注意

有用于添加不同双因素身份验证方法的第三方包。查看 Packagist.org 上的相关包。

步骤 2：启用扩展包

注意

如果您正在使用 Symfony Flex，则此步骤会自动发生。

在你的 config/bundles.php 中启用此扩展包

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

步骤 3：定义路由

注意

如果您正在使用 Symfony Flex，则会自动创建一个默认配置文件。但是请确保预配置的路径位于防火墙的 pattern 内。

在 config/routes/scheb_2fa.yaml 中（如果文件不存在则创建它），你需要添加两个路由

  • 双因素身份验证表单的路由
  • 另一个用于检查双因素身份验证代码的路由

路由必须位于防火墙 pattern 路径内，即使用双因素身份验证的防火墙。

1
2
3
4
5
6
7
8
9
# config/routes/scheb_2fa.yaml
2fa_login:
    path: /2fa
    # "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

如果你有多个具有双因素身份验证的防火墙，则每个防火墙都需要自己的一组登录和检查路由，这些路由必须位于关联的防火墙路径 pattern 内。

步骤 4：配置防火墙

为每个防火墙启用双因素身份验证，并为 2fa 路由配置 access_control

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...

更多每个防火墙的配置选项可以在 配置参考 中找到。

步骤 5：配置安全令牌

你的防火墙可能提供不同的登录方式。默认情况下（没有任何配置），捆绑包仅监听这些令牌

  • Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken （用户名+密码身份验证）
  • Symfony\Component\Security\Http\Authenticator\Token\PostAuthenticationToken （身份验证器使用的默认令牌）

如果你想支持使用另一种登录方法的双因素身份验证，你必须在 scheb_two_factor.security_tokens 配置选项中注册其令牌类。

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

步骤 6：启用双因素身份验证方法

如果你已经安装了作为子包提供的任何双因素身份验证方法，则必须单独启用它们。阅读如何为以下方法执行此操作

步骤 7：详细配置

你可能想要配置捆绑包的一些详细信息。请参阅 所有配置选项。

这项工作，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。
目录
    版本