### Install TOTP Bundle

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

Use Composer to install the TOTP authentication provider package.

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

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

### Install scheb/2fa-google-authenticator

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/google.html

Install the scheb/2fa-google-authenticator package to enable Google Authenticator two-factor authentication.

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

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

### Install bundle with Symfony Flex

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/installation.html

Use this command if your project is configured with Symfony Flex.

```bash
composer require 2fa
```

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

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

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/backup_codes.html

Use Composer to install the backup code package for the two-factor authentication bundle.

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

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

### Install scheb/2fa-trusted-device via Composer

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/trusted_device.html

Install the package 'scheb/2fa-trusted-device' via Composer to enable the trusted device feature.

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

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

### Install scheb/2fa-email package

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/email.html

Installs the scheb/2fa-email package, which is required to use the email two-factor provider.

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

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

### Install bundle manually

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/installation.html

Use this command if you are not using Symfony Flex or prefer the explicit package name.

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

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

### Implement BackupCodeInterface with Annotations

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/backup_codes.html

Example of a User entity implementing BackupCodeInterface using Doctrine annotations.

```php
<?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;
        }
    }
}
```

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

### Implement BackupCodeInterface with Attributes

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/backup_codes.html

Example of a User entity implementing BackupCodeInterface using PHP attributes.

```php
<?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;
        }
    }
}
```

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

### Install symfony/mailer package

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/email.html

Installs symfony/mailer, the default mail-sending library used by the bundle. You can use another library, but then you must implement a custom mailer class.

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

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

### Install additional 2FA features

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/installation.html

Optional packages to extend the bundle with backup codes, trusted devices, or specific authentication methods like TOTP, Google Authenticator, or email.

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

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

### SchebTwoFactorBundle Configuration Options

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/configuration.html

A comprehensive YAML configuration example for the SchebTwoFactorBundle, covering services, security tokens, IP whitelisting, and code reuse settings.

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

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

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

### TOTP Additional QR Code Parameters

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

Example of adding custom parameters like an image URL to the provisioning URI contained in the QR code.

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

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

### Implement canSetTrustedDevice method in custom trusted device manager

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/trusted_device.html

Example implementation of the canSetTrustedDevice method, which always returns true to allow the trusted device feature. Used for custom conditions like network checks.

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

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

### Retrieve QR Code Content from TOTP Service

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

The first block is a placeholder '1' that appears in the source, likely indicating a step or example number. The second block retrieves the QR code content from the TOTP service using the 'scheb_two_factor.security.totp_authenticator' service and the getQRContent method, which is then used to render a QR code image.

```text
1
```

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

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

### Validate Google Authenticator codes with UserGoogleTotpCode

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/validator_constraints.html

Use the UserGoogleTotpCode constraint to validate codes from the Google Authenticator provider. Note that the example uses the UserTotpCode attribute on the property.

```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;
}
```

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

### Get QR code content with scheb_two_factor.security.google_authenticator

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/google.html

Retrieve the QR code's content from the Google Authenticator service to generate a QR code image. Render the image yourself; do not pass the content to an external service as it exposes the secret.

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

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

### JSON payload with authCode under data

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/api.html

Example JSON payload for sending the two-factor authentication code. The code is nested under the `data` object with the property `authCode`.

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

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

### Enable two_factor prepare_on_login and prepare_on_access_denied

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/api.html

Configure the firewall to prepare two-factor authentication on login and access denied events. This is required for the custom handlers to work.

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

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

### needsPreparation method signature

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/custom.html

Determines if the provider needs preparation. If false is returned, prepareAuthentication is skipped, which is useful for stateless firewalls.

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

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

### Define 2FA routes

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/installation.html

Create or update config/routes/scheb_2fa.yaml to define the login and check routes. These must be 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
```

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

### Two-factor authentication success handler (PHP) with security.yaml configuration

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/api.html

Use this success handler to return a JSON response indicating that two-factor authentication completed successfully. The handler returns a response with 'login' set to 'success' and 'two_factor_complete' set to true. Register it as a service and configure it as the 'success_handler' of the 'two_factor' authentication method in your firewall.

```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}');
   }
}
```

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

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

### Set trusted parameter name in firewall configuration

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/trusted_device.html

Configuration to change the name of the parameter passed to flag a device as trusted, using the 'trusted_parameter_name' option under two_factor firewall settings. The example shows '_trusted' as the default.

```yaml
security:
    firewalls:
        your_firewall_name:
            # ...
            two_factor:
                trusted_parameter_name: _trusted  # Name of the parameter for the trusted device option
```

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

### Implement TrustedDeviceInterface with attributes in User entity

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/trusted_device.html

User entity implementing TrustedDeviceInterface using PHP attributes, requiring a trustedVersion column and getTrustedTokenVersion method.

```php
<?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 security firewall

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/installation.html

Update config/packages/security.yaml to enable two-factor authentication for a specific firewall and set the required access control rules.

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

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

### Register Custom Backup Code Manager

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/backup_codes.html

Configure a custom service to manage backup codes if the default implementation is insufficient.

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

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

### Implement TrustedDeviceInterface with annotations in User entity

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/trusted_device.html

User entity implementing TrustedDeviceInterface with Doctrine annotations, requiring a trustedVersion column and getTrustedTokenVersion method.

```php
<?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;
    }
}
```

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

### Create CustomFormRenderer Class

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/firewall_template.html

Implement the TwoFactorFormRendererInterface to select a template based on the current firewall name retrieved from the FirewallMapInterface.

```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;
    }
}
```

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

### TOTP Configuration Options

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

Full configuration structure for the TOTP provider, including server name, issuer, leeway, and template settings.

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

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

### Enable the trusted device feature in scheb_2fa.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/trusted_device.html

Configuration for the trusted device feature, showing all available options: enabled, lifetime, extend_lifetime, cookie_name, cookie_secure, cookie_same_site, cookie_domain, and cookie_path.

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

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

### Email Authentication Configuration in scheb_2fa.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/email.html

Configuration settings for enabling email authentication, specifying custom services, and defining sender details.

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

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

### Enable TOTP Configuration

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

Add the TOTP configuration to your Symfony application's configuration file.

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

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

### Enable Google Authenticator in scheb_2fa.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/google.html

Enable Google Authenticator in the Symfony configuration file.

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

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

### Configure Login Throttling in security.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/brute_force_protection.html

Enable login throttling in the firewall settings to automatically protect both login and two-factor authentication attempts.

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

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

### Configure custom persister in scheb_2fa.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/persister.html

Register your custom persister service and reference it in the bundle configuration file.

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

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

### Configure security_tokens for custom authentication tokens in scheb_two_factor

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/installation.html

By default, the bundle listens to UsernamePasswordToken and PostAuthenticationToken. Register additional token classes under the scheb_two_factor.security_tokens option to support other login methods.

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

```

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

### Register Custom Form Renderer in Configuration

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

Register the custom form renderer as a service and update the scheb_two_factor configuration to use it.

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

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

### Enable Backup Codes in Configuration

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/backup_codes.html

Enable the backup code feature in your Symfony configuration file.

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

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

### Google Authenticator Configuration Reference

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/google.html

Configuration options for the Google Authenticator provider. Set enabled to true to activate, and optionally set server_name, issuer, digits, leeway, and template. The leeway must be less than or equal to 30 seconds.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    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
```

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

### Configure scheb_2fa for Custom Renderer

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/firewall_template.html

Update the bundle configuration to use the custom service as the form_renderer for the desired two-factor provider.

```yaml
# config/packages/scheb_2fa.yaml
scheb_two_factor:
    google:  # Or "totp" or "email", depending on the two-factor provider you're using
        enabled: true
        form_renderer: acme.custom_form_renderer
```

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

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

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/email.html

Enables email two-factor authentication 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
```

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

### Enable CSRF Protection in framework.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/csrf_protection.html

Ensure CSRF protection is enabled in the main framework configuration file.

```yaml
# config/packages/framework.yaml
framework:
    csrf_protection: ~
```

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

### Increase leeway for TOTP and Google Authenticator in scheb_2fa.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/troubleshooting.html

Configure the leeway setting in scheb_2fa.yaml to accept a time drift between server and device for TOTP and Google Authenticator. The leeway must be less than or equal to the TOTP period (or 30 seconds for Google Authenticator). Increase this value to tolerate larger time differences.

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

    # For TOTP
    totp:
        leeway: 0  # Acceptable time drift in seconds, must be less or equal than the TOTP period


    # For Google Authenticator
    google:
        leeway: 0  # Acceptable time drift in seconds, must be less or equal than 30 seconds

```

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

### Two-factor authentication failure handler (PHP) with security.yaml configuration

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/api.html

Use this failure handler to return a JSON response when two-factor authentication fails. The handler returns a response with 'error' set to '2fa_failed' and 'two_factor_complete' set to false. Register it as a service and configure it as the 'failure_handler' of the 'two_factor' authentication method in your firewall.

```php
<?php

namespace App\Security;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface;

class TwoFactorAuthenticationFailureHandler implements AuthenticationFailureHandlerInterface
{
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): Response
    {
        // Return the response to tell the client that 2fa failed. You may want to add more details
        // from the $exception.
        return new Response('{"error": "2fa_failed", "two_factor_complete": false}');
   }
}
```

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

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

### Implement TwoFactorFormRendererInterface

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

Create a class implementing TwoFactorFormRendererInterface to fully customize the rendering logic for TOTP authentication forms.

```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 access_control for 2fa routes

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/troubleshooting.html

Add this rule to the top of your security.yaml to ensure the 2fa form is accessible during the authentication process.

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

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

### Configure Two-Factor Authentication in security.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/configuration.html

This configuration defines the two-factor authentication behavior for a specific firewall, including paths, handlers, and CSRF settings.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            # ...
            two_factor:
                auth_form_path: /2fa                  # Path or route name of the two-factor form
                check_path: /2fa_check                # Path or route name of the two-factor code check
                post_only: true                       # If the check_path should accept the code only as a POST request
                default_target_path: /                # Where to redirect by default after successful authentication
                always_use_default_target_path: false # If it should always redirect to default_target_path
                auth_code_parameter_name: _auth_code  # Name of the parameter for the two-factor authentication code
                                                      # (supports symfony/property-access notation for nested values)
                trusted_parameter_name: _trusted      # Name of the parameter for the trusted device option
                                                      # (supports symfony/property-access notation for nested values)
                remember_me_sets_trusted: false       # If remember-me option should also set the trusted device cookie
                multi_factor: false                   # If ALL active two-factor methods need to be fulfilled
                                                      # (multi-factor authentication)
                success_handler: acme.custom_success_handler  # Use a custom success handler instead of the default one
                failure_handler: acme.custom_failure_handler  # Use a custom failure handler instead of the default one

                # Use a custom authentication required handler instead of the default one
                # This can be used to modify the default behavior of the bundle, which is always redirecting to the
                # two-factor authentication form, when two-factor authentication is required.
                authentication_required_handler: acme.custom_auth_reqired_handler

                # Some two-factor providers need to be "prepared", usually a code is generated and sent to the user. Per
                # default, this happens when the two-factor form is shown. But you may want to execute preparation
                # earlier in the user's journey.
                prepare_on_login: false          # If the two-factor provider should be prepared right after login
                prepare_on_access_denied: false  # The the two-factor provider should be prepared when the user has to
                                                 # to complete two-factor authentication to view a page. This would
                                                 # prepare right before redirecting to the two-factor form.

                enable_csrf: true                # If CSRF protection should be enabled on the two-factor auth form
                csrf_parameter: _csrf_token      # The default CSRF parameter name
                                                 # (supports symfony/property-access notation for nested values)
                csrf_token_id: two_factor        # The default CSRF token id, for generating the token value, it is
                                                 # advised to use a different id per firewall
                csrf_header: ~                   # Name of the header field, in which a CSRF token may be passed.
                                                 # Default null, so headers are ignored per default.

                # The id of the service used to generate the CSRF tokens. Per default the one provided by Symfony
                # is used. You can configure a different one, if you need to use a custom CSRF token manager.
                csrf_token_manager: security.csrf.token_manager

                # If you have multiple user providers registered, Symfony's security extension requires you to configure
                # a user provider. You're forced to configure this node, although it doesn't have any effect on the
                # TwoFactorBundle. So set this to any of your user providers, it doesn't matter which one.
                provider: any_user_provider
```

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

### SchebTwoFactorBundle Configuration Reference

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/configuration.html

The full configuration structure for the bundle, defined in config/packages/scheb_2fa.yaml. This includes settings for trusted devices, backup codes, and specific authentication providers.

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

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

### Enable bundle in config/bundles.php

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/installation.html

Register the bundle in your Symfony application configuration. This step is automatic if using Symfony Flex.

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

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

### Enable CSRF in security.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/csrf_protection.html

Enable CSRF protection within the two_factor security configuration of your firewall.

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

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

### Configure json_login success_handler

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/api.html

Register the custom success handler as the success_handler for the json_login authentication mechanism.

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

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

### Configure two_factor_condition in scheb_2fa.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/custom_conditions.html

Register the custom condition service and configure it in the scheb_2fa.yaml file by setting the two_factor_condition option to the service name.

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

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

### Configure multi_factor in security.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/multi_authentication.html

Set the multi_factor option in your firewall configuration to determine if all active two-factor methods must be fulfilled.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            two_factor:
                multi_factor: false  # If ALL active two-factor methods need to be fulfilled
```

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

### Custom Form Renderer Implementation

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/google.html

Implement TwoFactorFormRendererInterface to fully customize form rendering, e.g., for different firewalls. 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
    }
}
```

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

### Register custom provider in YAML

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/custom.html

Register the custom provider service in services.yaml using the scheb_two_factor.provider tag with a unique alias.

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

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

### beginAuthentication method signature

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/custom.html

This method is called after a successful login to determine if the user should be asked for two-factor authentication from this provider.

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

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

### Implement TwoFactorInterface with Annotations

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

Implement the TwoFactorInterface in your User entity using Doctrine annotations to support TOTP authentication.

```php
<?php

namespace Acme\Demo\Entity;

use Doctrine\ORM\Mapping as ORM;
use Scheb\TwoFactorBundle\Model\Totp\TotpConfiguration;
use Scheb\TwoFactorBundle\Model\Totp\TotpConfigurationInterface;
use Scheb\TwoFactorBundle\Model\Totp\TwoFactorInterface;
use Symfony\Component\Security\Core\User\UserInterface;

class User implements UserInterface, TwoFactorInterface
{
    /**
     * @ORM\Column(type="string", nullable=true)
     */
    private ?string $totpSecret;

    // [...]

    public function isTotpAuthenticationEnabled(): bool
    {
        return $this->totpSecret ? true : false;
    }

    public function getTotpAuthenticationUsername(): string
    {
        return $this->username;
    }

    public function getTotpAuthenticationConfiguration(): ?TotpConfigurationInterface
    {
        // You could persist the other configuration options in the user entity to make it individual per user.
        $period = 20;
        $digits = 6;
        return null !== $this->totpSecret ? new TotpConfiguration($this->totpSecret, TotpConfiguration::ALGORITHM_SHA1, $period, $digits) : null;
    }
}
```

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

### Set auth_code_parameter_name to _auth_code in security.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/api.html

Configure the firewall to use the default POST parameter name `_auth_code` for the two-factor authentication code. The `auth_code_parameter_name` key under `two_factor` sets the parameter name.

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

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

### Registering Custom Mailer Service

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/email.html

Update the configuration to use the custom mailer service after registration.

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

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

### Register a custom trusted device manager in scheb_2fa.yaml

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/trusted_device.html

Configuration to use a custom trusted device manager by setting 'manager' under 'trusted_device' with the service ID.

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

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

### Register custom provider in XML

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/custom.html

Register the custom provider service in XML configuration using the scheb_two_factor.provider tag with 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>
```

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

### Generate a new secret with scheb_two_factor.security.google_authenticator

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/google.html

Use the service `scheb_two_factor.security.google_authenticator` to generate a new secret for Google Authenticator. Auto-wiring of `Scheb\TwoFactorBundle\Security\TwoFactor\Provider\Google\GoogleAuthenticatorInterface` is also possible.

```php
$secret = $container->get("scheb_two_factor.security.google_authenticator")->generateSecret();
```

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

### Implement AuthenticationRequiredHandlerInterface

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/api.html

Custom handler that returns a response when two-factor authentication is required but not yet completed. Implements AuthenticationRequiredHandlerInterface.

```php
<?php

namespace App\Security;

use Scheb\TwoFactorBundle\Security\Http\Authentication\AuthenticationRequiredHandlerInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;

class TwoFactorAuthenticationRequiredHandler implements AuthenticationRequiredHandlerInterface
{
    public function onAuthenticationRequired(Request $request, TokenInterface $token): Response
    {
        // Return the response to tell the client that authentication hasn't completed yet and
        // two-factor authentication is required.
        return new Response('{"error": "access_denied", "two_factor_complete": false}');
    }
}
```

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

### Register Custom Form Renderer Service

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/google.html

Register the custom form renderer service and update the configuration to use it via the form_renderer option.

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

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

### prepareAuthentication method signature

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/custom.html

Used to perform preparation work, such as generating and sending an authentication code to the user.

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

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

### Configure access_control for logout path

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/troubleshooting.html

Ensure the logout path is accessible to all users by adding a rule to the security configuration. This rule must be placed at the top of the access_control list.

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

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

### getFormRenderer method signature

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/custom.html

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

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

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

### Implement TwoFactorConditionInterface

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/custom_conditions.html

Implement the TwoFactorConditionInterface to define custom conditions for when two-factor authentication should be performed. The shouldPerformTwoFactorAuthentication method receives an AuthenticationContextInterface and must return a boolean.

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

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

### Implementing AuthCodeMailerInterface

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/email.html

Custom mailer implementation for sending authentication codes, required for non-default email styles like HTML.

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

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

### Register CustomFormRenderer Service

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/firewall_template.html

Register the custom renderer in services.yaml, providing the twig environment, firewall map, and the mapping of firewall names to template paths.

```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' } ]
```

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

### Implement TwoFactorInterface with Attributes

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/providers/totp.html

Implement the TwoFactorInterface in your User entity using PHP 8 attributes to support TOTP authentication.

```php
<?php

namespace Acme\Demo\Entity;

use Doctrine\ORM\Mapping as ORM;
use Scheb\TwoFactorBundle\Model\Totp\TotpConfiguration;
use Scheb\TwoFactorBundle\Model\Totp\TotpConfigurationInterface;
use Scheb\TwoFactorBundle\Model\Totp\TwoFactorInterface;
use Symfony\Component\Security\Core\User\UserInterface;

class User implements UserInterface, TwoFactorInterface
{
    #[ORM\Column(type: 'string', nullable: true)]
    private ?string $totpSecret;

    // [...]

    public function isTotpAuthenticationEnabled(): bool
    {
        return $this->totpSecret ? true : false;
    }

    public function getTotpAuthenticationUsername(): string
    {
        return $this->username;
    }

    public function getTotpAuthenticationConfiguration(): ?TotpConfigurationInterface
    {
        // You could persist the other configuration options in the user entity to make it individual per user.
        return new TotpConfiguration($this->totpSecret, TotpConfiguration::ALGORITHM_SHA1, 20, 8);
    }
}
```

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

### Implement AuthenticationSuccessHandlerInterface for JSON API

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/api.html

Custom success handler for the authentication mechanism. Returns a JSON response indicating two-factor authentication is required when the token is a TwoFactorTokenInterface; otherwise should delegate to the default success handler.

```php
<?php

namespace App\Security;

use Scheb\TwoFactorBundle\Security\Authentication\Token\TwoFactorTokenInterface;
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 AuthenticationSuccessHandler implements AuthenticationSuccessHandlerInterface
{
    public function onAuthenticationSuccess(Request $request, TokenInterface $token): Response
    {
        if ($token instanceof TwoFactorTokenInterface) {
            // Return the response to tell the client two-factor authentication is required.
            return new Response('{"login": "success", "two_factor_complete": false}');
        }

        // Otherwise return the default response for successful login. You could do this by decorating
        // the original authentication success handler and calling it here.
   }
}
```

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

### Configure CSRF Header

Source: https://symfony.com/bundles/SchebTwoFactorBundle/current/csrf_protection.html

Set a custom HTTP header name for passing the CSRF token.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        your_firewall_name:
            two_factor:
                enable_csrf: true
                csrf_header: X-CSRF-Token
```