本教程详细介绍了如何在Symfony 5.3中正确配置JWT认证，以确保API路由受到保护。通过集成自定义JWT认证器和精确设置security.yaml中的access_control规则，文章演示了如何强制用户提供有效的Bearer Token才能访问受限资源，从而实现无状态API的安全访问控制。
在构建无状态api时，json web token (jwt) 是一种广泛使用的认证机制。symfony 框架提供了强大的安全组件，允许开发者集成自定义认证逻辑。然而，仅仅实现了jwt的生成和解析是不够的，关键在于如何强制框架对受保护的api路由执行认证检查。本教程将深入探讨如何在symfony 5.3中正确配置jwt认证，特别是解决api路由未受保护的问题。
核心认证组件：JwtAuthenticator
JwtAuthenticator 是 Symfony 安全组件与自定义 JWT 逻辑之间的桥梁。它负责拦截请求、提取凭据、验证令牌并加载用户。
<?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;
}
}
登录后复制
注意： 上述 JwtAuthenticator 继承自 AbstractGuardAuthenticator。在 Symfony 5.4 及更高版本中，Guard 认证器已被弃用，推荐使用 AuthenticatorInterface。对于 Symfony 5.3，AbstractGuardAuthenticator 仍然是可用的。此外，Firebase/JWT/JWT::decode 在 v6.0.0 版本后需要传入 Firebase/JWT/Key 对象作为密钥。
安全配置核心：security.yaml
security.yaml 是 Symfony 安全组件的配置文件，它定义了防火墙、认证器、用户提供者和访问控制规则。
# 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 }
登录后复制
问题所在：access_control 的缺失或不当配置
在原始配置中，尽管 JwtAuthenticator 已经定义并注册，但 access_control 部分被注释或未正确配置。这意味着 Symfony 的安全组件并不知道哪些路径需要强制执行认证。即使 JwtAuthenticator 能够识别并验证令牌，如果 access_control 没有明确要求认证，请求仍然可以无阻碍地通过。
access_control 规则是按顺序匹配的，第一个匹配的规则将被应用。
关键修复：正确配置 access_control
为了确保 API 路由受到保护，需要明确指定哪些路径可以公开访问（例如登录路由），哪些路径需要完全认证。
# config/packages/security.yaml (修正后的 access_control 部分)
security:
# ... (其他配置保持不变) ...
firewalls:
# ... (防火墙配置保持不变) ...
# 访问控制：定义哪些 URL 需要认证
access_control:
# 允许所有用户访问 /authenticate 路径（例如登录或获取令牌的端点）
- { path: ^/authenticate, roles: PUBLIC_ACCESS }
# 强制所有其他路径都需要完全认证的用户才能访问
- { path: ^/, roles: IS_AUTHENTICATED_FULLY }
登录后复制
解释：
- – { path: ^/authenticate, roles: PUBLIC_ACCESS }：这条规则允许任何用户（包括未认证的用户）访问以 /authenticate 开头的路径。这是获取 JWT 令牌的登录端点所必需的。
- – { path: ^/, roles: IS_AUTHENTICATED_FULLY }：这条规则是关键。它捕获了所有以 / 开头的路径（即除了 ^/authenticate 之外的所有路径），并要求访问这些路径的用户必须是“完全认证”的。IS_AUTHENTICATED_FULLY 意味着用户已通过认证过程并提供了有效的凭据（在此场景下是有效的 JWT）。
通过这样的配置，当一个请求到达除 /authenticate 之外的任何路径时，Symfony 的安全组件会检查用户是否已完全认证。如果用户未认证或提供的 JWT 无效，JwtAuthenticator 的 start 或 onAuthenticationFailure 方法将被触发，返回一个未授权的响应。
完整配置示例
以下是修正后的 security.yaml 完整示例：
# 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 }
登录后复制
注意事项与最佳实践
- JWT 密钥管理： 将 JWT 密钥（jwt_secret）存储在环境变量中，而不是直接硬编码在配置文件或代码中，以提高安全性。例如，在 .env 文件中定义 JWT_SECRET=your_super_secret_key，并在 services.yaml 中将其注入到 ContainerBagInterface。
- 用户提供者： 尽管 security.yaml 中配置了 users_in_memory，但实际用户加载逻辑是在 JwtAuthenticator::getUser 方法中通过 EntityManagerInterface 从数据库加载的。确保 App/Entity/ATblUsers 实体及其仓库配置正确。
- 错误处理： JwtAuthenticator 中的 try-catch 块对于捕获 JWT 解码过程中的异常至关重要，例如令牌过期、签名无效等。
- Guard 认证器弃用： 考虑到 Symfony 的未来版本，如果项目允许，可以考虑将 JwtAuthenticator 升级到 AuthenticatorInterface。
- 令牌生成： 确保你的 AuthController（或其他生成 JWT 的控制器）在用户成功登录后，使用相同的密钥和算法正确生成 JWT，并将其返回给客户端。
总结
在 Symfony 5.3 中实现 JWT 认证并保护 API 路由，关键在于三个核心部分：
- 自定义 JwtAuthenticator： 负责令牌的提取、解析和用户加载。
- security.yaml 中的防火墙配置： 启用 stateless 模式并注册 JwtAuthenticator。
- 精确的 access_control 规则： 明确指定哪些路径需要认证，哪些可以公开访问。
通过正确配置 access_control，Symfony 的安全组件才能强制执行认证策略，从而有效保护你的 API 资源。
以上就是Symfony 5.3 中 JWT 认证与 API 访问控制的实现指南的详细内容，更多请关注php中文网其它相关文章！