本文详细介绍了如何在 laravel 应用中验证来自外部身份提供商的 json web token (jwt)。我们将利用 `tymondesigns/jwt-auth` 库，并通过自定义 guard 实现 jwt 的解析、rs256 签名验证（包括 jwks 公钥配置）、标准声明检查以及应用权限（scope）验证。教程将涵盖代码实现、配置步骤及关键注意事项，帮助开发者构建安全可靠的微服务认证体系。
在 Laravel 中验证第三方 JWT
在现代微服务架构中，利用外部身份提供商（IdP）进行用户认证已成为常见实践。当用户通过 IdP 认证后，客户端会获得一个访问令牌（Access Token），通常以 JWT 形式存在。为了确保 API 服务的安全性，后端微服务需要对收到的 JWT 进行严格验证。本教程将指导您如何在 Laravel 框架中实现这一过程，特别关注 RS256 签名的验证和自定义 Guard 的应用。
JWT 验证的核心步骤
验证一个第三方 JWT 通常涉及以下几个关键步骤：
- 解析 JWT：将 JWT 从 Bearer 头中提取出来，并解析其头部（Header）、载荷（Payload）和签名（Signature）部分。
- 验证签名：这是最关键的一步，确保令牌未被篡改。对于使用 RS256 算法签名的 JWT，需要使用 IdP 提供的公钥进行验证。这些公钥通常通过 JWKS (JSON Web Key Set) URL 获取。
- 验证标准声明：检查 JWT 的过期时间 (exp)、生效时间 (nbf)、签发时间 (iat)、签发者 (iss) 和受众 (aud) 等标准声明，确保令牌在有效期内且针对正确的服务。
- 验证应用权限（Scopes）：检查 JWT 载荷中包含的权限范围（scope 或 scp 声明），以确定用户是否有权访问请求的资源。
虽然 Laravel 生态中有许多用于创建 JWT 的包，但直接用于验证第三方 JWT 的集成方案可能不那么直观。我们将使用 tymondesigns/jwt-auth 包作为基础，并结合自定义 Guard 来实现上述验证逻辑。
1. 配置 JWT 公钥
对于使用 RS256 算法签名的 JWT，您需要从 IdP 的 JWKS URL 获取公钥。JWKS URL 通常是 https://{domain}/.well-known/jwks.json。从该 URL 获取到正确的公钥后，将其保存为 .pem 格式的文件，例如 storage/jwt/public.pem。
接下来，修改 config/jwt.php 配置文件，指示 tymondesigns/jwt-auth 使用该公钥进行签名验证：
// config/jwt.php
return [
// ...
'keys' => [
'public' => 'file://' . storage_path('jwt/public.pem'),
'private' => null, // 验证第三方JWT不需要私钥
'passphrase' => null,
],
'algo' => 'RS256', // 指定签名算法为RS256
// ...
];注意：在生产环境中，直接下载公钥文件并硬编码路径可能不是最佳实践。更健壮的方案是动态地从 JWKS URL 获取公钥，并根据 JWT 头部中的 kid (Key ID) 选择正确的公钥，然后进行缓存。但在本教程中，为简化示例，我们采用本地文件的方式。
2. 实现自定义 JWT Guard
Laravel 的认证系统允许您通过自定义 Guard 来扩展其功能。我们将创建一个 JWTGuard 类，负责从请求中提取 JWT、调用 tymondesigns/jwt-auth 进行验证，并根据 JWT 载荷创建用户实例。
在 app/Guard 目录下创建 JWTGuard.php 文件：
<?php
namespace App\Guard;
use App\Models\User; // 假设您有一个自定义的User模型
use Illuminate\Auth\GuardHelpers;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Http\Request;
use Tymon\JWTAuth\JWT;
class JWTGuard implements Guard
{
use GuardHelpers;
/**
* @var JWT $jwt
*/
protected JWT $jwt;
/**
* @var Request $request
*/
protected Request $request;
/**
* JWTGuard constructor.
* @param JWT $jwt
* @param Request $request
*/
public function __construct(JWT $jwt, Request $request)
{
$this->jwt = $jwt;
$this->request = $request;
}
/**
* 获取当前认证用户。
*
* @return \Illuminate\Contracts\Auth\Authenticatable|null
*/
public function user()
{
if (!is_null($this->user)) {
return $this->user;
}
// 尝试从请求中获取并验证JWT
if ($this->jwt->setRequest($this->request)->getToken() && $this->jwt->check()) {
// JWT 验证成功，从载荷中获取用户信息
$payload = $this->jwt->payload();
$id = $payload->get('sub'); // 通常 'sub' 声明包含用户唯一标识符
// 创建一个临时的用户实例。
// 如果您的用户模型需要更多数据，可以从 $payload 中提取并设置。
$this->user = new User();
$this->user->id = $id;
// 示例：从JWT载荷中设置其他用户属性
// $this->user->name = $payload->get('name');
// $this->user->email = $payload->get('email');
// 可以在此处添加权限（scopes）验证逻辑
// $scopes = $payload->get('scope', []);
// if (!in_array('your_required_scope', explode(' ', $scopes))) {
// return null; // 权限不足
// }
return $this->user;
}
return null;
}
/**
* 验证用户凭据（在本场景中不直接使用，JWT本身就是凭据）。
*
* @param array $credentials
* @return bool
*/
public function validate(array $credentials = [])
{
// 对于 JWT Guard，我们通常不通过 credentials 数组进行验证
// 而是依赖于 user() 方法中对 JWT 的验证
return false;
}
}请注意，上述 JWTGuard 中的 User 模型是一个简单的实现，它需要实现 Illuminate\Contracts\Auth\Authenticatable 接口。如果您没有对应的 Eloquent 模型，可以创建一个简单的类：
<?php
namespace App\Models;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Database\Eloquent\Model; // 如果您想利用Eloquent特性，可以继承Model
class User extends Model implements AuthenticatableContract
{
protected $guarded = []; // 允许批量赋值所有字段
/**
* 获取用户身份标识符。
*
* @return mixed
*/
public function getAuthIdentifier()
{
return $this->id;
}
/**
* 获取用户身份标识符的名称。
*
* @return string
*/
public function getAuthIdentifierName()
{
return 'id';
}
/**
* 获取用于存储用户“记住我”令牌的名称。
*
* @return string
*/
public function getRememberTokenName()
{
return ''; // 不使用记住我功能
}
/**
* 获取用户“记住我”令牌。
*
* @return string|null
*/
public function getRememberToken()
{
return null;
}
/**
* 设置用户“记住我”令牌。
*
* @param string $value
* @return void
*/
public function setRememberToken($value)
{
// 不使用记住我功能
}
/**
* 获取用户密码。
*
* @return string
*/
public function getAuthPassword()
{
return ''; // 不通过密码认证
}
}3. 注册自定义 Guard
完成 JWTGuard 的实现后，需要在 AuthServiceProvider 中注册它，并更新 config/auth.php。
在 AuthServiceProvider 中注册：
// app/Providers/AuthServiceProvider.php
namespace App\Providers;
use App\Guard\JWTGuard; // 引入自定义Guard
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Gate;
class AuthServiceProvider extends ServiceProvider
{
/**
* The policy mappings for the application.
*
* @var array
*/
protected $policies = [
// 'App\Models\Model' => 'App\Policies\ModelPolicy',
];
/**
* Register any authentication / authorization services.
*
* @return void
*/
public function boot()
{
$this->registerPolicies();
// 扩展认证系统，注册名为 'jwt-auth' 的 Guard
$this->app['auth']->extend(
'jwt-auth',
function ($app, $name, array $config) {
$guard = new JWTGuard(
$app['tymon.jwt'], // 注入 tymon/jwt-auth 的 JWT 实例
$app['request'] // 注入当前请求实例
);
// 确保在请求刷新时，Guard 也能更新其内部的请求实例
$app->refresh('request', $guard, 'setRequest');
return $guard;
}
);
}
}在 config/auth.php 中配置：
// config/auth.php
return [
'defaults' => [
'guard' => 'web', // 可以保持为 web，或根据您的应用默认需求修改
'passwords' => 'users',
],
'guards' => [
'web' => [
'driver' => 'session',
'provider' => 'users',
],
// ... 其他 guards
'jwt' => [ // 注册一个新的名为 'jwt' 的 guard
'driver' => 'jwt-auth', // 使用我们刚刚注册的 driver
'provider' => 'users', // 指定用户提供者，尽管我们使用自定义User模型，但仍需指定
],
],
'providers' => [
'users' => [
'driver' => 'eloquent',
'model' => App\Models\User::class, // 指定您的用户模型
],
// ...
],
// ...
];4. 在路由中使用 Guard
现在，您可以通过 Laravel 的认证中间件来保护路由了。
// routes/api.php 或其他路由文件
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Auth;
Route::middleware('auth:jwt')->get('/user', function () {
// 只有通过 'jwt' Guard 认证的请求才能访问此路由
return Auth::user();
});
Route::middleware('auth:jwt')->get('/protected-resource', function () {
// ... 处理受保护的资源
return response()->json(['message' => '访问受保护资源成功！']);
});当客户端向 /user 或 /protected-resource 发送请求时，必须在 Authorization 头中包含有效的 Bearer JWT。
关键注意事项与最佳实践
-
JWKS 动态获取与缓存：
- 在生产环境中，强烈建议实现一个机制来动态地从 IdP 的 JWKS URL 获取公钥。JWKS 包含一个或多个 JSON Web Key (JWK) 对象，每个对象都有一个 kid (Key ID)。
- JWT 头部也会包含一个 kid，您应该使用这个 kid 来匹配 JWKS 中相应的公钥。
- 获取到的公钥应该被缓存起来（例如使用 Laravel 的 Cache 系统），并定期刷新，以应对 IdP 的密钥轮换策略。
- 一个简单的实现可能涉及一个服务类，它负责：
- 从 JWKS URL 获取所有 JWK。
- 根据 JWT 头部中的 kid 查找匹配的 JWK。
- 将 JWK 转换为 OpenSSL 可用的 .pem 格式。
- 缓存转换后的公钥。
-
声明验证：
- tymondesigns/jwt-auth 默认会验证一些标准声明，如 exp（过期时间）、nbf（生效时间）和 iat（签发时间）。
- 您可能还需要验证 iss（签发者）和 aud（受众）声明，以确保 JWT 是由预期的 IdP 签发并针对您的服务。这些可以在 config/jwt.php 中配置。
-
Scope 验证：
- 在 JWTGuard 的 user() 方法中，您可以从 payload()->get('scope') 获取到权限范围。
- 通常，scope 声明是一个空格分隔的字符串或一个字符串数组。
- 您可以将其解析并与当前路由或资源所需的权限进行比较。如果权限不足，则返回 null，阻止用户认证。
- 对于更复杂的权限管理，可以考虑创建专门的中间件来处理 scope 验证，这样可以将认证和授权逻辑分离。
-
错误处理：
- 当 JWT 验证失败（例如签名无效、过期、缺少必要声明）时，tymondesigns/jwt-auth 会抛出异常（如 TokenExpiredException, TokenInvalidException）。
- 您应该在 app/Exceptions/Handler.php 中捕获这些异常，并返回适当的 HTTP 错误响应（例如 401 Unauthorized）。
-
用户模型：
- 本教程中的 App\Models\User 是一个简单的实现。在实际应用中，您可能需要将其与数据库中的用户记录关联起来，或者从 JWT 载荷中提取更多信息来构建一个更完整的用户对象。
- 关键是它必须实现 Illuminate\Contracts\Auth\Authenticatable 接口。
总结
通过以上步骤，您已经成功地在 Laravel 应用中搭建了一个健壮的第三方 JWT 验证机制。通过自定义 Guard，我们能够灵活地集成 tymondesigns/jwt-auth 的验证能力，并结合 JWKS 公钥配置，确保了来自外部身份提供商的访问令牌的有效性和安全性。记住，在生产环境中，动态获取和缓存 JWKS 公钥、以及全面的声明和权限验证是构建安全 API 的关键。
