在 Symfony 5.3 中实现 JWT 认证与 API 访问控制

<?php

namespace App\Security;

use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\DependencyInjection\ParameterBag\ContainerBagInterface;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserProviderInterface;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Firebase\JWT\JWT;
use Symfony\Component\Security\Guard\AbstractGuardAuthenticator;

class JwtAuthenticator extends AbstractGuardAuthenticator
{
    private $em;
    private $params;

    public function __construct(EntityManagerInterface $em, ContainerBagInterface $params)
    {
        $this->em = $em;
        $this->params = $params;
    }

    /**
     * 当认证失败时，此方法被调用，用于返回一个认证错误响应。
     */
    public function start(Request $request, AuthenticationException $authException = null): JsonResponse
    {
        return new JsonResponse(['message' => 'Authentication Required'], Response::HTTP_UNAUTHORIZED);
    }

    /**
     * 判断当前请求是否需要此认证器处理。
     * 如果请求头中包含 'Authorization'，则返回 true。
     */
    public function supports(Request $request): bool
    {
        return $request->headers->has('Authorization');
    }

    /**
     * 从请求中提取认证凭据（即 JWT 令牌）。
     */
    public function getCredentials(Request $request)
    {
        return $request->headers->get('Authorization');
    }

    /**
     * 根据凭据（JWT 令牌）加载用户。
     * 此方法会解码 JWT，验证其签名和有效性，并从数据库中查找对应的用户。
     * 如果令牌无效或用户不存在，则抛出 AuthenticationException。
     */
    public function getUser($credentials, UserProviderInterface $userProvider)
    {
        try {
            // 移除 "Bearer " 前缀
            $credentials = str_replace('Bearer ', '', $credentials);
            // 解码 JWT，使用配置中的密钥和算法
            $jwt = (array) JWT::decode($credentials, $this->params->get('jwt_secret'), ['HS256']);
            // 根据 JWT 中的 'sub'（通常是用户ID）从数据库中查找用户
            return $this->em->getRepository('App:ATblUsers')->find($jwt['sub']);
        } catch (\Exception $exception) {
            // 解码或查找用户失败，抛出认证异常
            throw new AuthenticationException($exception->getMessage());
        }
    }

    /**
     * 检查凭据是否有效。
     * 对于 JWT 认证，令牌的有效性通常在 getUser 方法中通过 JWT::decode 完成，
     * 因此此方法通常保持为空或简单返回 true。
     */
    public function checkCredentials($credentials, UserInterface $user): bool
    {
        // JWT 令牌的有效性已在 getUser 方法中验证
        return true;
    }

    /**
     * 认证失败时被调用。
     */
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): JsonResponse
    {
        return new JsonResponse([
            'message' => $exception->getMessage()
        ], Response::HTTP_UNAUTHORIZED);
    }

    /**
     * 认证成功时被调用。
     * 对于无状态 API，此方法通常无需执行任何操作。
     */
    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $providerKey)
    {
        // 无状态 API，认证成功后无需额外操作
        return null;
    }

    /**
     * 指示是否支持 "记住我" 功能。
     * 对于无状态 JWT 认证，通常返回 false。
     */
    public function supportsRememberMe(): bool
    {
        return false;
    }
}

security:
    # 启用新的认证器管理器
    enable_authenticator_manager: true

    # 密码哈希器配置
    password_hashers:
        Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'

    # 实体编码器配置
    encoders:
        App\Entity\ATblUsers:
            algorithm: bcrypt

    # 用户提供者配置
    # 注意：这里使用了内存用户，但 getUser 方法实际从数据库查找用户，
    # 在生产环境中应配置为实际的数据库用户提供者。
    providers:
        users_in_memory: { memory: null }

    # 防火墙配置
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false # 开发者工具和静态资源不进行安全检查

        main:
            # 使用 Guard 认证器（在 Symfony 5.3 中仍支持，但推荐使用新的 AuthenticatorInterface）
            guard:
                authenticators:
                    - App\Security\JwtAuthenticator
            lazy: true # 懒加载用户提供者
            provider: users_in_memory # 关联用户提供者

            # 标记此防火墙为无状态，不使用 session
            stateless: true

    # 访问控制规则
    # 注意：只有第一个匹配的规则会被使用
    access_control:
        # 允许所有用户（包括匿名用户）访问 /authenticate 路由，用于登录获取 JWT
        - { path: ^/authenticate, roles: PUBLIC_ACCESS }
        # 保护所有其他路由，要求用户必须完全认证（携带有效 JWT）
        - { path: ^/, roles: IS_AUTHENTICATED_FULLY }