Symfony5.3认证错误自定义教程

本文深入解析了 Symfony 5.3 中自定义认证失败错误消息的方法，旨在帮助开发者在新的认证系统中实现更灵活的用户反馈。文章首先剖析了 Symfony 认证流程，明确了 `onAuthenticationFailure` 方法的角色以及 `AuthenticationUtils` 如何获取错误信息。随后，详细阐述了在认证器、用户提供者和用户检查器中抛出 `CustomUserMessageAuthenticationException` 或 `CustomUserMessageAccountStatusException` 的具体实践，并强调了 `hide_user_not_found` 配置对错误消息显示的影响。通过本文，开发者能够更好地理解 Symfony 认证机制，掌握在不同阶段定制用户友好错误消息的技巧，从而提升用户体验和安全性。

本文详细介绍了在 Symfony 5.3 中如何定制认证失败时的错误消息。通过剖析 Symfony 认证流程，解释了 onAuthenticationFailure 方法的角色及 AuthenticationUtils 如何获取错误，并提供了在认证器、用户提供者和用户检查器中抛出 CustomUserMessageAuthenticationException 或 CustomUserMessageAccountStatusException 的具体方法，同时强调了 hide_user_not_found 配置的关键作用，帮助开发者实现灵活的用户反馈。

在 Symfony 5.3 及更高版本中，新的认证系统提供了强大的灵活性，但定制认证失败时的错误消息有时会让人感到困惑。本文将深入探讨 Symfony 认证机制，并提供在不同阶段抛出自定义错误消息的正确方法。

Symfony 认证失败机制解析

理解 Symfony 认证流程中错误是如何传递和处理的，是定制错误消息的关键。

1. AuthenticatorManager 的角色 当用户提交登录表单后，请求会通过 AuthenticatorManager。在认证过程中，如果 authenticator->authenticate($request) 方法抛出 AuthenticationException（例如，凭据无效、用户未找到等），AuthenticatorManager 会捕获此异常。

2. onAuthenticationFailure() 方法的调用 捕获到 AuthenticationException 后，AuthenticatorManager 会调用当前活跃认证器（通常是您自定义的登录认证器，它继承自 AbstractLoginFormAuthenticator）的 onAuthenticationFailure($request, AuthenticationException $exception) 方法。此方法的职责是处理认证失败的情况，并返回一个响应（例如重定向回登录页）。

   核心点： onAuthenticationFailure 方法接收一个 AuthenticationException 对象作为参数，它是一个“处理者”，而不是一个“生成者”。您不应该在此方法内部抛出新的 CustomUserMessageAuthenticationException，因为这个异常会被 Symfony 的核心异常处理机制捕获，而不会被 AuthenticationUtils 所获取。

3. AuthenticationUtils::getLastAuthenticationError() 如何工作 在您的登录控制器中，您通常会使用 AuthenticationUtils 服务来获取上次的认证错误：

   $error = $authenticationUtils->getLastAuthenticationError();

   这个方法实际上是从会话（Session）中获取一个名为 Security::AUTHENTICATION_ERROR 的属性。AbstractLoginFormAuthenticator 的默认 onAuthenticationFailure 实现会执行以下操作：

   $request->getSession()->set(Security::AUTHENTICATION_ERROR, $exception);

   正是这一行代码将捕获到的 AuthenticationException 存储在会话中，以便 AuthenticationUtils 能够检索到它并在视图中显示。因此，如果您想显示自定义错误，您需要确保在认证流程的某个早期阶段抛出带有自定义消息的异常，并让 onAuthenticationFailure 将其正确存入会话。

定制错误消息的关键：CustomUserMessageAuthenticationException

Symfony 提供了 CustomUserMessageAuthenticationException 和 CustomUserMessageAccountStatusException，它们允许您在异常中嵌入用户友好的消息。当这些异常被抛出时，它们的 message 属性会被 AuthenticationUtils 提取并在 Twig 模板中显示。

hide_user_not_found 配置的影响

在定制错误消息之前，了解 hide_user_not_found 配置至关重要。 为了防止通过错误消息推断用户是否存在（用户枚举攻击），Symfony 默认会将某些认证异常（如 UsernameNotFoundException）替换为通用的 BadCredentialsException（“Bad credentials.”）。

如果您希望显示自定义的用户未找到或账户状态异常消息，您需要：

1. 将 hide_user_not_found 设置为 false：

   # config/packages/security.yaml
   security:
       # ...
       hide_user_not_found: false
       # ...

   这样，当 UserNotFoundException 被抛出时，其原始消息将不会被隐藏或替换。

2. 或使用 CustomUserMessageAccountStatusException： 即使 hide_user_not_found 为 true，CustomUserMessageAccountStatusException 也不会被隐藏或替换。这使得它成为处理账户状态（如禁用、锁定、过期）相关自定义消息的理想选择。

在不同认证阶段抛出自定义异常

正确的做法是在认证流程的早期阶段，即在认证器、用户提供者或用户检查器中，根据业务逻辑抛出 CustomUserMessageAuthenticationException 或 CustomUserMessageAccountStatusException。

重要提示： 您应该创建自己的认证器类，并使其继承自 AbstractLoginFormAuthenticator，而不是直接修改 Symfony 核心库中的 AbstractLoginFormAuthenticator。

1. 在自定义认证器中

您的自定义认证器是处理用户凭据和认证逻辑的核心。在 authenticate() 方法中，您可以根据各种条件抛出自定义异常。

// src/Security/LoginFormAuthenticator.php
namespace App\Security;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Core\Security;
use Symfony\Component\Security\Http\Authenticator\AbstractLoginFormAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\CsrfTokenBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\RememberMeBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\PasswordCredentials;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Util\TargetPathTrait;

class LoginFormAuthenticator extends AbstractLoginFormAuthenticator
{
    use TargetPathTrait;

    private UrlGeneratorInterface $urlGenerator;

    public function __construct(UrlGeneratorInterface $urlGenerator)
    {
        $this->urlGenerator = $urlGenerator;
    }

    protected function getLoginUrl(Request $request): string
    {
        return $this->urlGenerator->generate('app_login');
    }

    public function authenticate(Request $request): Passport
    {
        $email = $request->request->get('email', '');
        $password = $request->request->get('password', '');
        $csrfToken = $request->request->get('_csrf_token');

        // 将用户名存储到会话，以便在登录失败后预填充表单
        $request->getSession()->set(Security::LAST_USERNAME, $email);

        // 示例：自定义错误，如果邮箱为空
        if (empty($email)) {
            throw new CustomUserMessageAuthenticationException('邮箱地址不能为空。');
        }

        // UserBadge 会尝试通过用户提供者加载用户。
        // 如果用户提供者抛出 UserNotFoundException 且 hide_user_not_found 为 false，
        // 则该消息会直接显示。
        // 如果 hide_user_not_found 为 true，则会转换为 BadCredentialsException。
        // 如果您想在此处强制自定义用户未找到消息，可以捕获 UserNotFoundException 并重新抛出。
        $userBadge = new UserBadge($email);

        return new Passport(
            $userBadge,
            new PasswordCredentials($password),
            [
                new CsrfTokenBadge('authenticate', $csrfToken),
                new RememberMeBadge(), // 根据您的需求添加
            ]
        );
    }

    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
    {
        if ($targetPath = $this->getTargetPath($request->getSession(), $firewallName)) {
            return new RedirectResponse($targetPath);
        }

        // 例如，重定向到主页
        return new RedirectResponse($this->urlGenerator->generate('homepage'));
    }

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): Response
    {
        if ($request->hasSession()) {
            // 这一行至关重要：它将 AuthenticationException 存储到会话中
            // 这样 AuthenticationUtils 才能获取到它。
            $request->getSession()->set(Security::AUTHENTICATION_ERROR, $exception);
        }

        $url = $this->getLoginUrl($request);

        return new RedirectResponse($url);
    }
}

2. 在用户提供者 (User Provider) 中

用户提供者负责根据标识符（如邮箱或用户名）加载用户。当用户不存在时，您可以在这里抛出 UserNotFoundException。如果 hide_user_not_found 为 false，则 UserNotFoundException 的消息会直接显示。

// src/Security/UserRepository.php (如果您的 User 实体在 App\Entity\User)
namespace App\Security;

use App\Entity\User;
use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;
use Symfony\Component\Security\Core\Exception\UserNotFoundException;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\PasswordUpgraderInterface;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserProviderInterface;

/**
 * @extends ServiceEntityRepository<User>
 * @implements UserProviderInterface<User>
 */
class UserRepository extends ServiceEntityRepository implements UserProviderInterface, PasswordUpgraderInterface
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, User::class);
    }

    public function loadUserByIdentifier(string $identifier): UserInterface
    {
        // 假设 $identifier 是邮箱
        $user = $this->findOneBy(['email' => $identifier]);

        if (!$user) {
            // 抛出 UserNotFoundException。
            // 如果 security.yaml 中的 hide_user_not_found 为 false，
            // 此消息将显示在登录表单上。
            throw new UserNotFoundException(sprintf('邮箱 "%s" 未注册。', $identifier));
        }

        return $user;
    }

    // ... 其他必要方法，如 refreshUser, supportsClass, upgradePassword
}

3. 在用户检查器 (User Checker) 中

用户检查器允许您在认证前 (checkPreAuth) 和认证后 (checkPostAuth) 对用户对象执行额外的检查，例如检查用户是否已禁用、已锁定或密码是否过期。这非常适合抛出 CustomUserMessageAccountStatusException。

// src/Security/UserChecker.php
namespace App\Security;

use App\Entity\User; // 您的用户实体
use Symfony\Component\Security\Core\User\UserInterface;

今天关于《Symfony5.3认证错误自定义教程》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！