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; // 注意：Guard 认证器在 Symfony 5.4+ 中已被弃用，推荐使用 AuthenticatorInterface

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

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

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

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

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

    /**
     * 根据凭据（JWT）加载用户。
     * 解码 JWT，提取用户ID（'sub'），并通过实体管理器从数据库中查找用户。
     * 任何解码或查找失败都应抛出 AuthenticationException。
     */
    public function getUser($credentials, UserProviderInterface $userProvider)
    {
        try {
            $credentials = str_replace('Bearer ', '', $credentials);
            // 从容器参数中获取 JWT 密钥
            $jwtSecret = $this->params->get('jwt_secret');
            $jwt = (array) JWT::decode($credentials, new \Firebase\JWT\Key($jwtSecret, 'HS256')); // Firebase/JWT v6+ 语法
            return $this->em->getRepository('App:ATblUsers')->find($jwt['sub']);
        } catch (\Exception $exception) {
            throw new AuthenticationException($exception->getMessage());
        }
    }

    /**
     * 验证凭据。对于无状态 JWT，通常不需要额外的凭据检查，因为 JWT 本身已经包含了认证信息。
     * 但如果你需要额外的验证（例如检查用户状态），可以在此实现。
     */
    public function checkCredentials($credentials, UserInterface $user)
    {
        // 对于 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)
    {
        return null; // 返回 null 继续请求，不中断流程
    }

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

# config/packages/security.yaml
security:
    enable_authenticator_manager: true # 启用新的认证器管理器

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

    # 编码器配置（如果你的用户实体需要）
    encoders:
        App\Entity\ATblUsers:
            algorithm: bcrypt

    # 用户提供者配置，这里使用内存提供者作为示例，但 JwtAuthenticator 会从数据库加载用户
    providers:
        users_in_memory: { memory: null } # 实际用户通过 JwtAuthenticator::getUser 从数据库加载

    # 防火墙配置
    firewalls:
        dev: # 开发环境防火墙，通常不启用安全
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false

        main: # 主防火墙，处理大部分请求
            stateless: true # 声明此防火墙是无状态的，不使用会话
            guard: # 使用 Guard 认证器
                authenticators:
                    - App\Security\JwtAuthenticator # 注册自定义的 JWT 认证器
            lazy: true # 延迟加载用户提供者
            provider: users_in_memory # 这里的 provider 只是占位，实际用户由 JwtAuthenticator::getUser 加载

    # 关键缺失：访问控制 (access_control)
    # 定义哪些 URL 模式需要何种角色或认证状态才能访问
    access_control:
        # - { path: ^/admin, roles: ROLE_ADMIN }
        # - { path: ^/profile, roles: ROLE_USER }

# config/packages/security.yaml (修正后的 access_control 部分)
security:
    # ... (其他配置保持不变) ...

    firewalls:
        # ... (防火墙配置保持不变) ...

    # 访问控制：定义哪些 URL 需要认证
    access_control:
        # 允许所有用户访问 /authenticate 路径（例如登录或获取令牌的端点）
        - { path: ^/authenticate, roles: PUBLIC_ACCESS }
        # 强制所有其他路径都需要完全认证的用户才能访问
        - { path: ^/, roles: IS_AUTHENTICATED_FULLY }

# config/packages/security.yaml
security:
    enable_authenticator_manager: true

    password_hashers:
        Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'

    encoders:
        App\Entity\ATblUsers:
            algorithm: bcrypt

    providers:
        users_in_memory: { memory: null }

    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false

        main:
            guard:
                authenticators:
                    - App\Security\JwtAuthenticator
            lazy: true
            provider: users_in_memory
            stateless: true

    access_control:
        - { path: ^/authenticate, roles: PUBLIC_ACCESS }
        - { path: ^/, roles: IS_AUTHENTICATED_FULLY }