Symfony API密钥认证：事件监听器中的响应处理与最佳实践

// 示例：不推荐在FilterControllerEvent中直接处理响应
class TokenSubscriber implements EventSubscriberInterface
{
    // ... 构造函数和属性省略

    public function onKernelController(FilterControllerEvent $event)
    {
        $controller = $event->getController();

        if ($controller[0] instanceof TokenAuthenticatedController) {
            $apiKey = $this->em->getRepository('AppBundle:ApiKey')->findOneBy(['enabled' => true, 'name' => 'apikey'])->getApiKey();
            $token = $event->getRequest()->headers->get('x-auth-token');
            if ($token !== $apiKey) {
                // 错误做法：在此处直接发送响应以终止请求
                // 例如：$event->setResponse(new JsonResponse(['message' => 'Unauthorized'], Response::HTTP_UNAUTHORIZED));
                // 这种方式虽然能设置响应，但并非处理认证失败的最佳实践
            }
        }
    }

    public static function getSubscribedEvents()
    {
        return [
            KernelEvents::CONTROLLER => 'onKernelController',
        ];
    }
}

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

use App\Repository\ApiKeyRepository; // 假设你有一个ApiKey实体和对应的Repository
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\User\UserProviderInterface;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;

class ApiTokenAuthenticator extends AbstractAuthenticator
{
    private $apiKeyRepository;

    public function __construct(ApiKeyRepository $apiKeyRepository)
    {
        $this->apiKeyRepository = $apiKeyRepository;
    }

    public function supports(Request $request): ?bool
    {
        // 检查请求是否包含 'X-AUTH-TOKEN' 头
        return $request->headers->has('x-auth-token');
    }

    public function authenticate(Request $request): Passport
    {
        $apiToken = $request->headers->get('x-auth-token');

        if (null === $apiToken) {
            // The token is missing, throw an AuthenticationException
            throw new AuthenticationException('No API token provided.');
        }

        // 查找数据库中与该令牌匹配的API密钥
        // 注意：这里简化处理，实际中可能需要更复杂的验证逻辑
        $apiKeyEntity = $this->apiKeyRepository->findOneBy(['apiKey' => $apiToken, 'enabled' => true]);

        if (!$apiKeyEntity) {
            throw new AuthenticationException('Invalid API token.');
        }

        // 如果API密钥有效，我们创建一个“匿名”用户或一个代表API密钥的用户
        // 这里使用一个简单的UserBadge，你可以根据需要创建更复杂的User对象
        return new SelfValidatingPassport(
            new UserBadge($apiKeyEntity->getName()) // 假设ApiKey实体有一个getName()方法
        );
    }

    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
    {
        // 认证成功，继续请求处理
        return null; // 返回null表示继续处理请求
    }

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
    {
        $data = [
            'message' => strtr($exception->getMessageKey(), $exception->getMessageData())
        ];

        return new JsonResponse($data, Response::HTTP_UNAUTHORIZED);
    }
}

# config/packages/security.yaml
security:
    # ...
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false
        api:
            pattern: ^/api # 保护所有以/api开头的路由
            stateless: true # API通常是无状态的
            provider: app_user_provider # 可以使用一个简单的用户提供者，或者如果不需要实际用户，可以忽略
            custom_authenticators:
                - App\Security\ApiTokenAuthenticator # 引用你的自定义认证器

    providers:
        # 如果你的API密钥不对应实际用户，可以定义一个简单的provider
        app_user_provider:
            id: App\Security\ApiTokenUserProvider # 假设你有一个简单的UserProvider
            # 或者使用in_memory provider如果不需要持久化用户
            # in_memory:
            #     memory_users:
            #         api_user:
            #             password: ~
            #             roles: ['ROLE_API']

    access_control:
        - { path: ^/api, roles: IS_AUTHENTICATED_FULLY } # 确保/api下的所有路由都需要完全认证