Symfony5.3JWT认证与API控制教程

各位小伙伴们，大家好呀！看看今天我又给各位带来了什么文章？本文标题是《Symfony 5.3 实现 JWT 认证与 API 控制》，很明显是关于文章的文章哈哈哈，其中内容主要会涉及到等等，如果能帮到你，觉得很不错的话，欢迎各位多多点评和分享！

本教程详细阐述了如何在 Symfony 5.3 应用中实现基于 JWT 的 API 访问控制。文章首先介绍了 JWT 认证器的核心实现，包括令牌的获取、验证和用户加载逻辑。随后，重点讲解了如何在 security.yaml 中配置防火墙和 access_control 规则，以确保受保护的 API 路由仅允许携带有效 JWT 令牌的请求访问。通过示例代码和关键注意事项，帮助开发者构建安全的无状态 API。

1. 理解 Symfony 中的 JWT 认证流程

在 Symfony 中实现 JWT（JSON Web Token）认证，核心在于创建一个自定义的认证器（Authenticator）并将其配置到安全防火墙中。JWT 认证通常用于无状态 API，即服务器不维护会话状态，每次请求都通过 JWT 令牌进行认证。

一个典型的 JWT 认证流程包括以下步骤：

1. 用户登录：用户提供凭据（如用户名和密码）进行登录。
2. 生成 JWT：如果凭据有效，服务器生成一个 JWT 令牌并返回给客户端。
3. 携带 JWT 访问：客户端将 JWT 令牌存储起来，并在后续的每个受保护请求中，通过 Authorization 请求头（通常是 Bearer 方案）将令牌发送到服务器。
4. 验证 JWT：服务器接收到请求后，通过认证器解析并验证 JWT 令牌的有效性（包括签名、过期时间等）。
5. 授权访问：如果令牌有效，服务器根据令牌中的用户信息（如用户ID、角色）授予或拒绝访问特定资源。

2. 构建 JWT 认证器 (JwtAuthenticator)

JwtAuthenticator 是 Symfony 安全组件与 JWT 令牌交互的核心。它继承自 AbstractGuardAuthenticator，并实现了多个关键方法来处理认证流程。

<?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;
    }
}

关键点说明：

• __construct: 注入 EntityManagerInterface 用于数据库操作（查找用户）和 ContainerBagInterface 用于获取 jwt_secret 配置。
• start: 当请求需要认证但没有提供凭据时，此方法返回一个 401 Unauthorized 响应。
• supports: 检查请求头中是否存在 Authorization 字段，决定是否由当前认证器处理该请求。
• getCredentials: 从 Authorization 请求头中提取完整的 JWT 字符串。
• getUser: 这是 JWT 认证的核心。它首先移除 Bearer 前缀，然后使用 Firebase\JWT\JWT::decode 解码并验证 JWT 令牌。解码成功后，从令牌的 sub 字段（通常代表用户ID）中获取用户标识，并通过 EntityManager 从数据库中加载用户实体。任何解码或查找失败都会抛出 AuthenticationException。
• checkCredentials: 对于 JWT 认证，令牌的有效性（签名、过期时间等）通常在 getUser 方法中通过 JWT::decode 完成。因此，此方法通常返回 true 即可。
• onAuthenticationFailure / onAuthenticationSuccess: 分别处理认证失败和成功后的逻辑。对于无状态 API，成功后通常无需特殊处理，失败则返回错误信息。
• supportsRememberMe: 无状态 API 不支持“记住我”功能，因此返回 false。

3. 配置 Symfony 安全 (security.yaml)

security.yaml 文件是 Symfony 安全配置的核心，它定义了防火墙、认证器、用户提供者和访问控制规则。正确配置 access_control 是确保 API 路由受保护的关键。

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 }

关键配置说明：

• enable_authenticator_manager: true: 启用 Symfony 5.1+ 引入的新认证器管理器。尽管示例中仍使用了 guard 关键字，但它会通过兼容层与新管理器协同工作。
• firewalls.main: 定义了名为 main 的防火墙，用于保护主要应用路由。
  • guard.authenticators: - App\Security\JwtAuthenticator: 将我们自定义的 JwtAuthenticator 注册到 main 防火墙中。当请求进入此防火墙时，Symfony 会尝试使用这个认证器进行认证。
  • stateless: true: 非常重要。这告诉 Symfony 此防火墙是无状态的，它不会创建或使用会话（session）。这对于基于 JWT 的 API 是必需的，因为 JWT 本身就包含了认证信息。
• access_control: 这是解决问题的核心！ 它定义了哪些路径需要哪些角色才能访问。
  • - { path: ^/authenticate, roles: PUBLIC_ACCESS }: 这条规则允许任何人（包括未认证的用户）访问 /authenticate 路径。通常，这个路径是用于用户登录并获取 JWT 令牌的。PUBLIC_ACCESS 角色意味着不需要任何认证。
  • - { path: ^/, roles: IS_AUTHENTICATED_FULLY }: 这条规则保护了所有其他路径（^/ 匹配所有路径）。它要求访问这些路径的用户必须是“完全认证”的。这意味着用户必须通过了认证器（即提供了有效的 JWT 令牌），并且其身份已被验证。如果请求没有携带有效的 JWT，JwtAuthenticator 将会触发认证失败，并根据 start 或 onAuthenticationFailure 方法返回 401 Unauthorized 响应。

4. 总结与注意事项

通过以上配置，您的 Symfony 5.3 API 将能够正确地强制执行 JWT 认证。当一个请求到达受保护的路由时：

1. Symfony 的安全组件会检查 access_control 规则。
2. 如果路径匹配 ^/ 且需要 IS_AUTHENTICATED_FULLY 角色，它会尝试通过配置的认证器（JwtAuthenticator）进行认证。
3. JwtAuthenticator 会检查 Authorization 头，提取并验证 JWT 令牌。
4. 如果令牌有效且用户存在，请求将被允许继续处理；否则，将返回 401 Unauthorized 响应。

重要注意事项：

• JWT 密钥管理: jwt_secret 是 JWT 签名的关键，务必妥善保管，通常存储在环境变量或 Symfony 的参数文件中（如 services.yaml 或 config/packages/framework.yaml 中定义）。
• 用户提供者: 示例中的 providers: users_in_memory 仅用于演示。在生产环境中，您应该配置一个实际的用户提供者，如 entity 提供者，以便从数据库加载用户。JwtAuthenticator 中的 getUser 方法已经从数据库查找用户，这与 users_in_memory 存在一定程度的不匹配，但它能正常工作。
• 错误处理: JwtAuthenticator 中的 onAuthenticationFailure 和 start 方法提供了统一的认证失败响应。您可以根据需要自定义这些响应。
• Guard 认证器: 尽管 Symfony 5.3 仍然支持 Guard 认证器，但 Symfony 推荐使用新的 AuthenticatorInterface。对于新项目，可以考虑使用 make:authenticator 命令生成基于新接口的认证器。然而，对于现有基于 Guard 的项目，上述配置仍然有效。
• JWT 库: Firebase\JWT\JWT 是一个常用的 PHP JWT 库。确保您的项目中已通过 Composer 安装了它。

通过遵循这些步骤和注意事项，您可以在 Symfony 5.3 应用中构建一个健壮且安全的基于 JWT 的无状态 API。

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