Scheb Two-Factor Bundle

https://github.com/scheb/2fa
Admin
A comprehensive two-factor authentication bundle for Symfony applications with support for TOTP,...
Tokens:99,181
Snippets:621
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install scheb/2fa-trusted-device

Source: https://github.com/scheb/2fa/blob/8.x/doc/trusted_device.rst

Install the trusted device feature package via Composer.

```bash
composer require scheb/2fa-trusted-device
```

--------------------------------

### Install TOTP provider with Composer

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/totp.rst

Install the scheb/2fa-totp package to enable TOTP authentication.

```bash
composer require scheb/2fa-totp
```

--------------------------------

### Install dependencies with Composer

Source: https://github.com/scheb/2fa/blob/8.x/CONTRIBUTING.md

Run this command in the project root to install the project dependencies before running quality checks.

```bash
composer install
```

--------------------------------

### Install scheb/2fa-backup-code

Source: https://github.com/scheb/2fa/blob/8.x/doc/backup_codes.rst

Install the backup code feature package via Composer.

```terminal
composer require scheb/2fa-backup-code
```

--------------------------------

### Install scheb/2fa-email

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Installs the email provider package via Composer.

```bash
composer require scheb/2fa-email
```

--------------------------------

### Install Google Authenticator bundle

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/google.rst

Use Composer to install the required package for Google Authenticator support.

```bash
composer require scheb/2fa-google-authenticator
```

--------------------------------

### Full TOTP configuration example

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/totp.rst

Complete configuration for the TOTP provider with all options: enabled, server_name, issuer, leeway, parameters, and template. The leeway must be less than or equal to the TOTP period.

```yaml
scheb_two_factor:
    totp:
        enabled: true                  # If TOTP authentication should be enabled, default false
        server_name: Server Name       # Server name used in QR code
        issuer: Issuer Name            # Issuer name used in QR code
        leeway: 0                      # Acceptable time drift in seconds, must be less or equal than the TOTP period
        parameters:                    # Additional parameters added in the QR code
            image: 'https://my-service/img/logo.png'
        template: security/2fa_form.html.twig   # Template used to render the authentication form
```

--------------------------------

### Install symfony/mailer

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Installs the default mailer package required by the bundle's default email sending implementation.

```bash
composer require symfony/mailer
```

--------------------------------

### Install SchebTwoFactorBundle with Composer

Source: https://github.com/scheb/2fa/blob/8.x/doc/installation.rst

Install the bundle with Composer. Use 'composer require 2fa' if you have Symfony Flex, otherwise use 'composer require scheb/2fa-bundle'.

```terminal
composer require 2fa
```

```terminal
composer require scheb/2fa-bundle
```

--------------------------------

### Install optional SchebTwoFactorBundle packages

Source: https://github.com/scheb/2fa/blob/8.x/doc/installation.rst

Optionally install additional packages to extend the bundle's features. Each package adds a specific two-factor authentication method or feature.

```terminal
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
```

--------------------------------

### scheb_two_factor google and totp leeway configuration (6.x to 7.x)

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

The window configuration options for google and totp have been removed. Use leeway instead. The example shows the YAML configuration for both google and totp, with a comment noting the acceptable time drift.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
   google:
       leeway: 10  # Acceptable time drift in seconds, must be less or equal than 30 seconds

   # TOTP authentication config
   totp:
       leeway: 10  # Acceptable time drift in seconds, must be less or equal than the TOTP period
```

--------------------------------

### needsPreparation method signature

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/custom.rst

Determines if the provider needs preparation. If false, prepareAuthentication is not called and the provider is considered prepared from the start, useful for stateless firewalls.

```php
public function needsPreparation(): bool;
```

--------------------------------

### Run PHP-CS-Fixer

Source: https://github.com/scheb/2fa/blob/8.x/CONTRIBUTING.md

Run PHP-CS-Fixer v3 to automatically fix code style issues. The tool is not provided with the library and must be installed locally.

```bash
php-cs-fixer fix
```

--------------------------------

### Configure email authentication digits

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Sets the number of digits for the generated authentication code. The default is not specified, but this example sets it to 6.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    email:
        digits: 6
```

--------------------------------

### Before: csrf_token_generator configuration

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

Old configuration using the removed csrf_token_generator option. Replace with enable_csrf: true as shown in the 'After' example.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        yourFirewallName:
            # ...
            two_factor:
                csrf_token_generator: security.csrf.token_manager
```

--------------------------------

### Implement BackupCodeInterface in User entity

Source: https://github.com/scheb/2fa/blob/8.x/doc/backup_codes.rst

User entity implementing BackupCodeInterface with methods to check, invalidate, and add backup codes. The example assumes codes are already generated; implement (re-)generation as preferred.

```php-annotations
<?php

namespace Acme\Demo\Entity;

use Doctrine\ORM\Mapping as ORM;
use Scheb\TwoFactorBundle\Model\BackupCodeInterface;

class User implements BackupCodeInterface
{
    /**
     * @ORM\Column(type="json")
     */
    private array $backupCodes = [];

    // [...]

    /**
     * Check if it is a valid backup code.
     */
    public function isBackupCode(string $code): bool
    {
        return in_array($code, $this->backupCodes);
    }

    /**
     * Invalidate a backup code
     */
    public function invalidateBackupCode(string $code): void
    {
        $key = array_search($code, $this->backupCodes);
        if ($key !== false){
            unset($this->backupCodes[$key]);
        }
    }

    /**
     * Add a backup code
     */
    public function addBackUpCode(string $backUpCode): void
    {
        if (!in_array($backUpCode, $this->backupCodes)) {
            $this->backupCodes[] = $backUpCode;
        }
    }
}
```

```php-attributes
<?php

namespace Acme\Demo\Entity;

use Doctrine\ORM\Mapping as ORM;
use Scheb\TwoFactorBundle\Model\BackupCodeInterface;

class User implements BackupCodeInterface
{
    #[ORM\Column(type: 'json')]
    private array $backupCodes = [];

    // [...]

    /**
     * Check if it is a valid backup code.
     */
    public function isBackupCode(string $code): bool
    {
        return in_array($code, $this->backupCodes);
    }

    /**
     * Invalidate a backup code
     */
    public function invalidateBackupCode(string $code): void
    {
        $key = array_search($code, $this->backupCodes);
        if ($key !== false){
            unset($this->backupCodes[$key]);
        }
    }

    /**
     * Add a backup code
     */
    public function addBackUpCode(string $backUpCode): void
    {
        if (!in_array($backUpCode, $this->backupCodes)) {
            $this->backupCodes[] = $backUpCode;
        }
    }
}
```

--------------------------------

### Configure JSON login success handler in security.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

Configuration snippet for setting up a JSON login success handler in the security firewall. This is part of the setup for API-based authentication where a custom success handler is used.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            json_login:  # The authentication mechanism you're using
                success_handler: your_api_success_handler
```

--------------------------------

### UserTotpCode validator options before and after (7.x to 8.x)

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

Under Symfony 8, the UserTotpCode and UserGoogleTotpCode constraints no longer accept an associative array for options. Use constructor arguments, optionally with named arguments. The before example shows the old array syntax, the after example shows the new named argument syntax.

```php
// Attribute
#[UserTotpCode(['message': 'The authentication code is invalid'])]
public string $code;

// Programmatic
new UserTotpCode(['message': 'The authentication code is invalid'])
```

```php
// Attribute
#[UserTotpCode(message: 'The authentication code is invalid')]
public string $code;

// Programmatic
new UserTotpCode(message: 'The authentication code is invalid')
```

--------------------------------

### Create CustomFormRenderer class implementing TwoFactorFormRendererInterface

Source: https://github.com/scheb/2fa/blob/8.x/doc/firewall_template.rst

Define a custom form renderer that selects a template based on the current firewall name. It uses FirewallMapInterface to get the firewall config and renders the corresponding template from a map. The class must implement TwoFactorFormRendererInterface and return a Response.

```php
<?php

namespace Acme\Demo;

use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorFormRendererInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Http\FirewallMapInterface;
use Twig\Environment;

class CustomFormRenderer implements TwoFactorFormRendererInterface
{
    public function __construct(
        private Environment $twigEnvironment,
        private FirewallMapInterface $firewallMap,
        private array $templates, // Map of [firewall name => template path]
    ) {
    }

    public function renderForm(Request $request, array $templateVars): Response
    {
        $firewallName = $this->firewallMap->getFirewallConfig($request)->getName();
        $template = $this->templates[$firewallName];

        $content = $this->twigEnvironment->render($template, $templateVars);
        $response = new Response();
        $response->setContent($content);

        return $response;
    }
}
```

--------------------------------

### Register CustomFormRenderer as a service in config/services.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/firewall_template.rst

Register the custom form renderer as a service with arguments for the Twig environment, the security firewall map, and a map of firewall names to template paths. The map example includes 'main' and 'admin' firewalls.

```yaml
# config/services.yaml
services:
    acme.custom_form_renderer:
        class: Acme\Demo\CustomFormRenderer
        arguments:
            - '@twig'
            - '@security.firewall.map'
            # This is a map of firewall name to template path
            - { main: 'security/2fa_google.html.twig', admin: 'admin/security/2fa_google.html.twig' } ]
```

--------------------------------

### Set post_only to false for check_path

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

YAML configuration to allow the two-factor authentication code to be accepted via GET requests. By default, the check_path only accepts POST requests. Set post_only: false on the firewall to change this.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        yourFirewallName:
            # ...
            two_factor:
                post_only: false
```

--------------------------------

### Example JSON payload for 2FA code

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

Shows a JSON payload with the auth code nested under the data property. Use this when sending the 2FA code via a JSON POST request.

```json
{"data": {"authCode": "1234"}}
```

--------------------------------

### Bypass 2FA with FLAG_2FA_COMPLETE

Source: https://github.com/scheb/2fa/blob/8.x/doc/custom_conditions.rst

Example of a custom authenticator that sets the TwoFactorAuthenticator::FLAG_2FA_COMPLETE attribute on the token to bypass two-factor authentication when this authenticator is used. The createToken method is overridden to set the attribute.

```php
<?php

namespace Acme\Demo;

use Scheb\TwoFactorBundle\Security\Http\Authenticator\TwoFactorAuthenticator;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;

class MyAuthenticator extends AbstractAuthenticator
{
    public function createToken(Passport $passport, string $firewallName): TokenInterface
    {
        $token = parent::createAuthenticatedToken($passport, $firewallName);

        // Set this to bypass 2fa for this authenticator
        $token->setAttribute(TwoFactorAuthenticator::FLAG_2FA_COMPLETE, true);

        return $token;
    }

    // ...
}
```

--------------------------------

### Get TOTP QR code content

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/totp.rst

Retrieve the QR code content for a user from the TOTP service to generate a QR code image. Render the image yourself and do not pass the content to an external service, as it exposes the secret code.

```php
$qrCodeContent = $container->get("scheb_two_factor.security.totp_authenticator")->getQRContent($user);
```

--------------------------------

### Get QR code content for Google Authenticator

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/google.rst

PHP code to retrieve the QR code content from the Google Authenticator service. Use a QR code rendering library to render the image. Security note: keep the content within your application and render the image yourself; do not pass it to an external service.

```php
$qrCodeContent = $container->get("scheb_two_factor.security.google_authenticator")->getQRContent($user);
```

--------------------------------

### Configure two_factor options in security.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

Set prepare_on_login and prepare_on_access_denied to true on the firewall to enable two-factor authentication preparation.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            # ...
            two_factor:
                prepare_on_login: true
                prepare_on_access_denied: true
```

--------------------------------

### Run unit tests

Source: https://github.com/scheb/2fa/blob/8.x/CONTRIBUTING.md

Run the unit test suite using PHPUnit.

```bash
vendor/bin/phpunit
```

--------------------------------

### Run Psalm

Source: https://github.com/scheb/2fa/blob/8.x/CONTRIBUTING.md

Run Psalm static analysis and address any error-level issues.

```bash
vendor/bin/psalm
```

--------------------------------

### Enable SchebTwoFactorBundle in config/bundles.php

Source: https://github.com/scheb/2fa/blob/8.x/doc/installation.rst

Enable the bundle in config/bundles.php. This step is automatic if you use Symfony Flex.

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

--------------------------------

### Enable TOTP in configuration

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/totp.rst

Add this YAML configuration to enable the TOTP authentication method.

```yaml
scheb_two_factor:
    totp:
        enabled: true
```

--------------------------------

### Validate TOTP code with UserTotpCode constraint

Source: https://github.com/scheb/2fa/blob/8.x/doc/validator_constraints.rst

Use the UserTotpCode constraint to validate codes from the TOTP authentication provider. The example shows a Symfony form property with NotBlank and UserTotpCode constraints.

```php
use Scheb\TwoFactorBundle\Security\TwoFactor\Validator\Constraints\UserTotpCode;
use Symfony\Component\Validator\Constraints as Assert;

class SecuritySettingsForm
{
    #[Assert\NotBlank(message: 'Please enter your authentication code')]
    #[UserTotpCode(message: 'The authentication code is invalid')]
    public string $totpCode;
}
```

--------------------------------

### Configure scheb_2fa.yaml options

Source: https://github.com/scheb/2fa/blob/8.x/doc/configuration.rst

Configuration for the scheb/2fa bundle. Defines IP whitelist entries, custom service providers for whitelist, token factory, conditions, provider decider, code reuse cache and its duration, and a default handler for reused codes. Each custom service must implement the corresponding interface.

```yaml
# config/packages/scheb_2fa.yaml

       # A list of IP addresses or netmasks, which will not trigger two-factor authentication.
       # Supports IPv4, IPv6 and IP subnet masks.
       ip_whitelist:
           - 127.0.0.1  # One IPv4
           - 192.168.0.0/16  # One IPv4 subnet
           - 2001:0db8:85a3:0000:0000:8a2e:0370:7334  # One IPv6
           - 2001:db8:abcd:0012::0/64  # One IPv6 subnet
           - !php/const Symfony\Component\HttpFoundation\IpUtils::PRIVATE_SUBNETS # All private IPv4 and IPv6 subnets

       # If you want to have your own implementation to retrieve the whitelisted IPs.
       # The configuration option "ip_whitelist" becomes meaningless in that case.
       # Must implement Scheb\TwoFactorBundle\Security\TwoFactor\IpWhitelist\IpWhitelistProviderInterface
       ip_whitelist_provider: acme.custom_ip_whitelist_provider

       # If you want to exchange/extend the TwoFactorToken class, which is used by the bundle, you can have a factory
       # service providing your own implementation.
       # Must implement Scheb\TwoFactorBundle\Security\Authentication\Token\TwoFactorTokenFactoryInterface
       two_factor_token_factory: acme.custom_two_factor_token_factory

       # If you need custom conditions when to perform two-factor authentication.
       # Must implement Scheb\TwoFactorBundle\Security\TwoFactor\Condition\TwoFactorConditionInterface
       two_factor_condition: acme.custom_two_factor_condition

       # If you need custom conditions to decide what two factor provider to prefer.
       # Must implement  Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorProviderDeciderInterface
       two_factor_provider_decider: acme.custom_two_factor_provider_decider

       # If you want to disable multiple uses of the same two-factor code (as recommended by
       # NIST) you can provide a cache implementation that will be used to cache the used codes
       # Must implement Psr\Cache\CacheItemPoolInterface or Symfony\Contracts\Cache\CacheInterface
       # You can use "cache.app", which is a preconfigured cache pool coming with Symfony framework.
       # Remove the key or set the value to an empty string to disable this check
       code_reuse_cache: acme.custom_code_reuse_cache

       # By default the time to cache a 2FA-code is 60 seconds. After that the 2FA code should be
       # invalidated by the 2FA provider anyhow. Should your 2FA provider allow valid codes for
       # more than that, you should increase this amount!
       code_reuse_cache_duration: 60

       # If you need to handle reused codes differently you can create your own EventListener for the
       # Scheb\TwoFactorBundle\Security\TwoFactor\Event\TwoFactorAuthenticationEvents::CODE_REUSED event
       # The default handler throws a Scheb\TwoFactorBundle\Security\Authentication\Exception\ReusedTwoFactorCodeException
       # If that is not what you want, you can provide a different default handler here.
       code_reuse_default_handler: scheb_two_factor.security.listener.throw_exception_on_two_factor_code_reuse
```

--------------------------------

### Validate Google Authenticator code with UserGoogleTotpCode constraint

Source: https://github.com/scheb/2fa/blob/8.x/doc/validator_constraints.rst

Use the UserGoogleTotpCode constraint to validate codes from the Google Authenticator provider. The example shows a Symfony form property with NotBlank and UserTotpCode constraints.

```php
use Scheb\TwoFactorBundle\Security\TwoFactor\Validator\Constraints\UserGoogleTotpCode;
use Symfony\Component\Validator\Constraints as Assert;

class LoginForm
{
    #[Assert\NotBlank(message: 'Please enter your authentication code')]
    #[UserTotpCode(message: 'The authentication code is invalid')]
    public string $authCode;
}
```

--------------------------------

### Bundle Configuration (scheb_2fa.yaml)

Source: https://github.com/scheb/2fa/blob/8.x/doc/configuration.rst

Complete YAML configuration for the scheb/2fa bundle, covering trusted_device, backup_codes, email, google, totp, persister, model_manager_name, and security_tokens options. Includes comments explaining each setting.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:

    # Trusted device feature
    trusted_device:
        enabled: false                 # If the trusted device feature should be enabled
        manager: acme.custom_trusted_device_manager  # Use a custom trusted device manager
        lifetime: 5184000              # Lifetime of the trusted device token
        extend_lifetime: false         # Automatically extend lifetime of the trusted cookie on re-login
        key: null                      # Encryption key for JWT token, must be at least 32 characters. If not set the
                                       # application's kernel.secret is used.
        cookie_name: trusted_device    # Name of the trusted device cookie
        cookie_secure: false           # true|false|auto Set the 'Secure' (HTTPS Only) flag on the trusted device cookie
        cookie_same_site: "lax"        # The same-site option of the cookie, can be "lax", "strict" or null
        cookie_domain: ".example.com"  # Domain to use when setting the cookie, fallback to the request domain if not set
        cookie_path: "/"               # Path to use when setting the cookie

    # Backup codes feature
    backup_codes:
        enabled: false                 # If the backup code feature should be enabled
        manager: acme.custom_backup_code_manager  # Use a custom backup code manager

    # Email authentication config
    email:
        enabled: true                  # If email authentication should be enabled, default false
        mailer: acme.custom_mailer_service  # Use alternative service to send the authentication code
        code_generator: acme.custom_code_generator_service  # Use alternative service to generate authentication code
        sender_email: me@example.com   # Sender email address
        sender_name: John Doe          # Sender name
        digits: 4                      # Number of digits in authentication code
        template: security/2fa_form.html.twig   # Template used to render the authentication form
        form_renderer: acme.custom_form_renderer  # Use a custom form renderer service

    # Google Authenticator config
    google:
        enabled: true                  # If Google Authenticator should be enabled, default false
        server_name: Server Name       # Server name used in QR code
        issuer: Issuer Name            # Issuer name used in QR code
        digits: 6                      # Number of digits in authentication code
        leeway: 0                      # Acceptable time drift in seconds, must be less or equal than 30 seconds
        template: security/2fa_form.html.twig   # Template used to render the authentication form
        form_renderer: acme.custom_form_renderer  # Use a custom form renderer service

    # TOTP authentication config
    totp:
        enabled: true                  # If TOTP authentication should be enabled, default false
        server_name: Server Name       # Server name used in QR code
        issuer: Issuer Name            # Issuer name used in QR code
        leeway: 0                      # Acceptable time drift in seconds, must be less or equal than the TOTP period
        parameters:                    # Additional parameters added in the QR code
            image: 'https://my-service/img/logo.png'
        template: security/2fa_form.html.twig   # Template used to render the authentication form
        form_renderer: acme.custom_form_renderer  # Use a custom form renderer service

    # The service which is used to persist data in the user object. By default Doctrine is used. If your entity is
    # managed by something else (e.g. an API), you have to implement a custom persister.
    # Must implement Scheb\TwoFactorBundle\Model\PersisterInterface
    persister: acme.custom_persister

    # If your Doctrine user object is managed by a model manager, which is not the default one, you have to
    # set this option. Name of entity manager or null, which uses the default one.
    model_manager_name: ~

    # The security token classes, which trigger two-factor authentication.
    # By default the bundle only reacts to Symfony's username+password authentication. If you want to enable
    # two-factor authentication for other authentication methods, add their security token classes.
    security_tokens:
        - Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken
        - Symfony\Component\Security\Http\Authenticator\Token\PostAuthenticationToken
```

--------------------------------

### Upgrade commands for migrating to scheb/2fa packages

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

Commands to rename configuration files and switch composer packages from scheb/two-factor-bundle to scheb/2fa-* packages. The rename is optional but recommended for consistency and to ensure Symfony Flex removes config files on composer remove. Add feature-specific packages as needed.

```bash
# Rename configuration files. This is actually not required, but good to do for consistency. Also, Symfony
# Flex doesn't remove the config files when the "composer remove" command is later executed.
mv config/packages/scheb_two_factor.yaml config/packages/scheb_2fa.yaml
mv config/routes/scheb_two_factor.yaml config/routes/scheb_2fa.yaml  # Might not exist, then ignore.

# Switch composer packages
composer remove scheb/two-factor-bundle --no-scripts
composer require scheb/2fa-bundle

# Then add the extra packages, depending on what bundle features you're using in your application:
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
```

--------------------------------

### Configure trusted device in scheb_2fa.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/trusted_device.rst

Enable and configure the trusted device feature. The default values are shown; adjust them as needed.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    trusted_device:
        enabled: false                 # If the trusted device feature should be enabled
        lifetime: 5184000              # Lifetime of the trusted device token
        extend_lifetime: false         # Automatically extend lifetime of the trusted cookie on re-login
        cookie_name: trusted_device    # Name of the trusted device cookie
        cookie_secure: false           # Set the 'Secure' (HTTPS Only) flag on the trusted device cookie
        cookie_same_site: "lax"        # The same-site option of the cookie, can be "lax" or "strict"
        cookie_domain: ".example.com"  # Domain to use when setting the cookie, fallback to the request domain if not set
        cookie_path: "/"               # Path to use when setting the cookie
```

--------------------------------

### Register success handler as service and configure success_handler

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

Register the custom success handler as a service and set it as the success_handler for the authentication method.

```yaml
services:
    App\Security\AuthenticationSuccessHandler:
        # ...

security:
    firewalls:
        your_firewall_name:
            # ...
            json_login:
                success_handler: App\Security\AuthenticationSuccessHandler
```

--------------------------------

### Configure custom backup code manager

Source: https://github.com/scheb/2fa/blob/8.x/doc/backup_codes.rst

Register a custom backup code manager service in the configuration.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    backup_codes:
        manager: acme.custom_backup_code_manager  # Use a custom backup code manager
```

--------------------------------

### Implement canSetTrustedDevice method in PHP

Source: https://github.com/scheb/2fa/blob/8.x/doc/trusted_device.rst

PHP method to implement custom logic for allowing trusted devices. Return true to always allow the trusted device feature.

```php
public function canSetTrustedDevice($user, Request $request, string $firewallName): bool
{
    return true; // Always allow trusted device feature
}
```

--------------------------------

### TrustedDeviceManagerInterface methods before and after type hint change

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

Shows the change in `canSetTrustedDevice`, `addTrustedDevice`, and `isTrustedDevice` methods from untyped `$user` to `object` type hint in `Scheb\TwoFactorBundle\Security\TwoFactor\Trusted\TrustedDeviceManagerInterface`.

```php
public function canSetTrustedDevice($user, Request $request, string $firewallName): bool;
public function addTrustedDevice($user, string $firewallName): void;
public function isTrustedDevice($user, string $firewallName): bool;
```

```php
public function canSetTrustedDevice(object $user, Request $request, string $firewallName): bool;
public function addTrustedDevice(object $user, string $firewallName): void;
public function isTrustedDevice(object $user, string $firewallName): bool;
```

--------------------------------

### Enable email authentication with sender configuration

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Enables the email authentication method and sets the sender email and optional sender name.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    email:
        enabled: true
        sender_email: no-reply@example.com
        sender_name: John Doe  # Optional
```

--------------------------------

### Define 2FA routes in config/routes/scheb_2fa.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/installation.rst

Define routes for the two-factor authentication form and check in config/routes/scheb_2fa.yaml. The routes must be located within the firewall's path pattern.

```yaml
# 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
```

--------------------------------

### Run PHP CodeSniffer

Source: https://github.com/scheb/2fa/blob/8.x/CONTRIBUTING.md

Run PHP CodeSniffer using the project's configuration to check code style.

```bash
vendor/bin/phpcs
```

--------------------------------

### TwoFactorProviderInterface methods before and after type hint change

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

Shows the change in `prepareAuthentication` and `validateAuthenticationCode` methods from untyped `$user` to `object` type hint in `Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorProviderInterface`.

```php
public function prepareAuthentication($user): void;
public function validateAuthenticationCode($user, string $authenticationCode): bool;
```

```php
public function prepareAuthentication(object $user): void;
public function validateAuthenticationCode(object $user, string $authenticationCode): bool;
```

--------------------------------

### Configure success handler in security.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

Sets the success_handler for the two_factor authentication method in the firewall configuration. Use this when you need a custom response after successful 2FA.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            two_factor:
                success_handler: your_api_2fa_success_handler
```

--------------------------------

### Register provider with XML service configuration

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/custom.rst

Registers the custom provider as a service using XML syntax with the scheb_two_factor.provider tag and a unique alias.

```xml
<service id="acme.custom_two_factor_provider" class="Acme\Demo\MyTwoFactorProvider">
    <tag name="scheb_two_factor.provider" alias="acme_two_factor_provider" />
</service>
```

--------------------------------

### AuthenticationContextFactoryInterface create method (5.x to 6.x)

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

The signature of the create method in AuthenticationContextFactoryInterface has been adjusted to include a Passport parameter. Custom factory implementations must be updated accordingly.

```php
public function create(Request $request, TokenInterface $token, Passport $passport, string $firewallName): AuthenticationContextInterface
```

--------------------------------

### Configure firewall and access control for two-factor authentication

Source: https://github.com/scheb/2fa/blob/8.x/doc/installation.rst

Configure the firewall to use two-factor authentication and add access control rules. The auth_form_path and check_path must match the route names defined in routes.yaml. The access control rules must be added at the very top of the list to allow logout during 2FA and restrict the 2FA form to users with IS_AUTHENTICATED_2FA_IN_PROGRESS.

```yaml
# 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...
```

--------------------------------

### Enable backup codes in scheb_2fa.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/backup_codes.rst

Enable the backup code feature in the Symfony configuration.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    backup_codes:
        enabled: true  # If the backup code feature should be enabled
```

--------------------------------

### Register custom form renderer service and update configuration

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Shows the YAML configuration to register the custom form renderer service and update the email provider configuration. The service ID and class name are placeholders.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    email:
        form_renderer: acme.my_form_renderer
```

--------------------------------

### Implement TrustedDeviceInterface with annotations

Source: https://github.com/scheb/2fa/blob/8.x/doc/trusted_device.rst

Implement TrustedDeviceInterface in the user entity using Doctrine annotations. The getTrustedTokenVersion method returns the current version used to invalidate trusted cookies.

```php-annotations
<?php

namespace Acme\Demo\Entity;

use Doctrine\ORM\Mapping as ORM;
use Scheb\TwoFactorBundle\Model\TrustedDeviceInterface;

class User implements TrustedDeviceInterface
{
    /**
     * @ORM\Column(type="integer")
     */
    private int $trustedVersion;

    // [...]

    public function getTrustedTokenVersion(): int
    {
        return $this->trustedVersion;
    }
}
```

--------------------------------

### After: enable_csrf configuration

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

New configuration using enable_csrf: true to enable CSRF protection. If a custom CSRF token manager was used, overwrite the service definition scheb_two_factor.csrf_token_manager.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        yourFirewallName:
            # ...
            two_factor:
                enable_csrf: true
```

--------------------------------

### Configure two_factor authentication_required_handler in security.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

Configuration snippet for setting the custom authentication required handler for the two_factor authentication method in the security firewall.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            two_factor:
                authentication_required_handler: your_api_2fa_required_handler
```

--------------------------------

### Register provider with YAML service configuration

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/custom.rst

Registers the custom provider as a service with the scheb_two_factor.provider tag and a unique alias. The aliases 'google', 'totp', and 'email' are reserved.

```yaml
# config/services.yaml
services:
    # ...
    acme.custom_two_factor_provider:
        class: Acme\Demo\MyTwoFactorProvider
        tags:
            - { name: scheb_two_factor.provider, alias: acme_two_factor_provider }
```

--------------------------------

### Implement AuthenticationSuccessHandlerInterface for two-factor auth

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

PHP class that implements the AuthenticationSuccessHandlerInterface to return a response when two-factor authentication is successfully completed. The response indicates that authentication including two-factor is now complete.

```php
<?php

namespace App\Security;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;

class TwoFactorAuthenticationSuccessHandler implements AuthenticationSuccessHandlerInterface
{
    public function onAuthenticationSuccess(Request $request, TokenInterface $token): Response
    {
        // Return the response to tell the client that authentication including two-factor
        // authentication is complete now.
        return new Response('{"login": "success", "two_factor_complete": true}');
   }
}
```

--------------------------------

### beginAuthentication method signature

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/custom.rst

Defines the method that decides if the user should be asked for two-factor authentication from this provider. Returns true to ask, false otherwise.

```php
public function beginAuthentication(AuthenticationContextInterface $context): bool;
```

--------------------------------

### BackupCodeManagerInterface methods before and after type hint change

Source: https://github.com/scheb/2fa/blob/8.x/UPGRADE.md

Shows the change in `isBackupCode` and `invalidateBackupCode` methods from untyped `$user` to `object` type hint in `Scheb\TwoFactorBundle\Security\TwoFactor\Backup\BackupCodeManagerInterface`.

```php
public function isBackupCode($user, string $code): bool;
public function invalidateBackupCode($user, string $code): void;
```

```php
public function isBackupCode(object $user, string $code): bool;
public function invalidateBackupCode(object $user, string $code): void;
```

--------------------------------

### Configure failure handler in security.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

Registers the failure handler as a service and configures it as the failure_handler for the two_factor authentication method. Use this to return a custom response when 2FA fails.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            two_factor:
                failure_handler: your_api_2fa_failure_handler
```

--------------------------------

### Configure email two-factor authentication in scheb_2fa.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Configuration for enabling email two-factor authentication. Sets the sender, code length, and template, and optionally overrides the mailer and code generator services.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    email:
        enabled: true                  # If email authentication should be enabled, default false
        mailer: acme.custom_mailer_service  # Use alternative service to send the authentication code
        code_generator: acme.custom_code_generator_service  # Use alternative service to generate authentication code
        sender_email: me@example.com   # Sender email address
        sender_name: John Doe          # Sender name
        digits: 4                      # Number of digits in authentication code
        template: security/2fa_form.html.twig   # Template used to render the authentication form
```

--------------------------------

### Implement TrustedDeviceInterface with attributes

Source: https://github.com/scheb/2fa/blob/8.x/doc/trusted_device.rst

Implement TrustedDeviceInterface in the user entity using PHP attributes. The getTrustedTokenVersion method returns the current version used to invalidate trusted cookies.

```php-attributes
<?php

namespace Acme\Demo\Entity;

use Doctrine\ORM\Mapping as ORM;
use Scheb\TwoFactorBundle\Model\TrustedDeviceInterface;

class User implements TrustedDeviceInterface
{
    #[ORM\Column(type: 'integer')]
    private int $trustedVersion;

    // [...]

    public function getTrustedTokenVersion(): int
    {
        return $this->trustedVersion;
    }
}
```

--------------------------------

### Configure custom form renderer for Google Authenticator

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/google.rst

YAML configuration to set a custom form renderer service for the Google Authenticator provider. Replace 'acme.custom_form_renderer_service' with your service ID.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    google:
        form_renderer: acme.custom_form_renderer_service
```

--------------------------------

### Configure custom trusted device manager in scheb_2fa.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/trusted_device.rst

YAML configuration to use a custom trusted device manager by setting the 'manager' option under 'trusted_device'.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    trusted_device:
        manager: acme.custom_trusted_device_manager  # Use a custom trusted device manager
```

--------------------------------

### Implement custom mailer with AuthCodeMailerInterface

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Custom mailer implementation for sending the authentication code. Must implement AuthCodeMailerInterface and use the user's email auth code.

```php
<?php

namespace Acme\Demo\Mailer;

use Scheb\TwoFactorBundle\Model\Email\TwoFactorInterface;
use Scheb\TwoFactorBundle\Mailer\AuthCodeMailerInterface;

class MyAuthCodeMailer implements AuthCodeMailerInterface
{
    // [...]

    public function sendAuthCode(TwoFactorInterface $user): void
    {
        $authCode = $user->getEmailAuthCode();

        // Send email
    }
}
```

--------------------------------

### prepareAuthentication method signature

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/custom.rst

Performs preparation work for the provider, such as generating and sending a code (e.g., email provider).

```php
public function prepareAuthentication(object $user): void;
```

--------------------------------

### Add image parameter to TOTP QR code

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/totp.rst

Adds an 'image' parameter to the provisioning URI in the QR code. This parameter is common for all users and may not be supported by all applications; FreeOTP supports it to associate the QR code with a logo.

```yaml
scheb_two_factor:
    totp:
        parameters:
            image: 'https://my-service/img/logo.png'
```

--------------------------------

### Implement custom form renderer class

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Creates a class implementing TwoFactorFormRendererInterface to fully customize form rendering. The renderForm method receives the request and template variables and must return a Response.

```php
<?php

namespace Acme\Demo\FormRenderer;

use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorFormRendererInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class MyFormRenderer implements TwoFactorFormRendererInterface
{
    // [...]

    public function renderForm(Request $request, array $templateVars): Response
    {
        // Customize form rendering
    }
}
```

--------------------------------

### Configure two_factor_condition service

Source: https://github.com/scheb/2fa/blob/8.x/doc/custom_conditions.rst

YAML configuration for the scheb_2fa bundle to set the custom two-factor condition service. The service name must match the registered service.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    two_factor_condition: acme.custom_two_factor_condition
```

--------------------------------

### Configure custom persister service in scheb_2fa.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/persister.rst

YAML configuration for the scheb_two_factor bundle to use a custom persister service. Set the 'persister' option to the service name of your custom persister implementation.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    persister: acme.custom_persister
```

--------------------------------

### Enable Google Authenticator in scheb_2fa.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/google.rst

Enables the Google Authenticator two-factor provider. Add this to your application's Symfony configuration to activate the provider.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    google:
        enabled: true
```

--------------------------------

### Configure login_throttling in security.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/brute_force_protection.rst

Enable Symfony's built-in login throttling on a firewall to automatically limit login and two-factor authentication attempts. Configure max_attempts and interval as needed; see Symfony Security Bundle documentation for full details.

```yaml
# config/packages/security.yaml
    security:
        firewalls:
            your_firewall_name:
                login_throttling:
                    max_attempts: 3
                    interval: '15 minutes'
```

--------------------------------

### Register custom mailer service in scheb_2fa.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/email.rst

Configuration to use the custom mailer service for email two-factor authentication.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    email:
        mailer: acme.custom_mailer_service
```

--------------------------------

### Configure access_control for 2fa routes in security.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/troubleshooting.rst

Adds an access_control rule to allow access to the 2fa form during authentication. The rule must be placed at the very top of the access_control list, and the path regex must match your configured 2fa route. Additional options like host or ip must also match.

```yaml
# config/packages/security.yaml
security:
    # IMPORTANT: THE ACCESS CONTROL RULE NEEDS TO BE AT THE VERY TOP OF THE LIST!
    access_control:
        # This ensures that the form can only be accessed when two-factor authentication is in progress.
        # The path may be different, depending on how you've configured the route.
        - { path: ^/2fa, role: IS_AUTHENTICATED_2FA_IN_PROGRESS }
        # Other rules may follow here...
```

--------------------------------

### getFormRenderer method signature

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/custom.rst

Provides a service for rendering the authentication form. The service must implement TwoFactorFormRendererInterface.

```php
public function getFormRenderer(): TwoFactorFormRendererInterface;
```

--------------------------------

### Allow logout route in security.yaml access_control

Source: https://github.com/scheb/2fa/blob/8.x/doc/troubleshooting.rst

Add this access control rule to allow the logout route to be publicly accessible. Place it first in the access_control list because rules are evaluated in order. Ensure the path regex matches your logout path and that any additional options like host or ip also match.

```yaml
# config/packages/security.yaml
security:
    access_control:
        - { path: ^/logout, role: PUBLIC_ACCESS }
        # More rules here ...
```

--------------------------------

### TwoFactorFormRendererInterface renderForm method

Source: https://github.com/scheb/2fa/blob/8.x/doc/providers/custom.rst

Renders the authentication form. Must return a Response, which could be a RedirectResponse to an external service. A default Twig implementation is available as DefaultTwoFactorFormRenderer.

```php
public function renderForm(Request $request, array $templateVars): Response;
```

--------------------------------

### Implement TwoFactorConditionInterface

Source: https://github.com/scheb/2fa/blob/8.x/doc/custom_conditions.rst

Define a custom condition class that implements TwoFactorConditionInterface. The shouldPerformTwoFactorAuthentication method receives an AuthenticationContextInterface and returns a boolean indicating whether 2FA should be performed. Register this class as a service and configure it in scheb_2fa.yaml.

```php
<?php

use Scheb\TwoFactorBundle\Security\TwoFactor\AuthenticationContextInterface;
use Scheb\TwoFactorBundle\Security\TwoFactor\Condition\TwoFactorConditionInterface;

class MyTwoFactorCondition implements TwoFactorConditionInterface
{
    public function shouldPerformTwoFactorAuthentication(AuthenticationContextInterface $context): bool
    {
        // Your conditions here
    }
}
```

--------------------------------

### Configure auth code parameter name in security.yaml

Source: https://github.com/scheb/2fa/blob/8.x/doc/api.rst

Sets the auth_code_parameter_name to customize the POST parameter name for the 2FA code. The default is _auth_code.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            # ...
            two_factor:
                auth_code_parameter_name: _auth_code  # Name of the parameter for the two-factor authentication code
```
Tokens:
Raw