Laravel API 集成与验证第三方 JWT (RS256/JWKS)

本教程详细阐述了如何在 laravel 应用中安全地验证来自外部身份提供商的第三方 jwt，特别是针对使用 rs256 算法和 jwks 公钥的场景。通过配置 `tymondesigns/jwt-auth` 包、实现自定义认证 guard，并注册到 laravel 认证体系中，您可以高效地解析、校验 jwt 签名和标准声明，从而实现对 api 请求的认证和授权。

概述

在微服务架构或与第三方身份提供商（IdP）集成的场景中，Laravel API 经常需要验证外部签发的 JSON Web Token (JWT)。这些 JWT 通常使用非对称加密算法（如 RS256）进行签名，其公钥通过 JWKS (JSON Web Key Set) URL 提供。本教程将指导您如何利用 tymondesigns/jwt-auth 包，结合自定义认证 Guard，在 Laravel 中实现这一复杂的验证流程，确保 API 的安全访问。

前置准备

首先，确保您的 Laravel 项目已安装 tymondesigns/jwt-auth 包。如果尚未安装，请通过 Composer 进行安装：

composer require tymondesigns/jwt-auth
php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

发布配置文件后，您会在 config 目录下找到 jwt.php。

配置 JWT 公钥

外部身份提供商通常通过 JWKS (JSON Web Key Set) URL（例如 https://{domain}/.well-known/jwks.json）发布其公钥。对于 RS256 算法，您需要从 JWKS 中提取相应的 RSA 公钥，并将其保存为 PEM 格式的文件。

1. 获取公钥： 访问您的身份提供商的 JWKS URL，解析 JSON 响应。找到 alg 为 RS256 的密钥，并提取其 n (modulus) 和 e (exponent) 值，或直接获取其 x5c 字段中的 X.509 证书。将其转换为 PEM 格式的公钥文件。例如，一个 PEM 格式的公钥文件内容如下：

   -----BEGIN PUBLIC KEY-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
   -----END PUBLIC KEY-----

2. 存储公钥： 将此 PEM 文件保存到 Laravel 项目的私有存储目录，例如 storage/jwt/public.pem。

   

   花生AI

   B站推出的AI视频创作工具

   下载

3. 配置 jwt.php： 打开 config/jwt.php 文件，修改 keys 和 algo 配置项，指向您存储的公钥文件，并指定签名算法为 RS256。

   // config/jwt.php
   return [
       // ...
       'keys' => [
           'public' => 'file://' . storage_path('jwt/public.pem'),
           'private' => null, // 对于验证第三方 JWT，私钥不是必需的
           'passphrase' => null,
       ],
       'algo' => 'RS256',
       // ...
   ];

   请注意，public 键的值必须是文件路径，并以 file:// 前缀。

创建自定义认证 Guard

为了将 JWT 验证逻辑集成到 Laravel 的认证体系中，我们需要创建一个自定义 Guard。这个 Guard 将负责解析传入请求中的 JWT，验证其签名，并从令牌中提取用户信息。

在 app/Guard 目录下创建 JWTGuard.php 文件（如果 Guard 目录不存在，请创建它）：