如何为LaravelPassportJWTToken添加自定义Claims，提升授权灵活性？

告别“信息孤岛”：Laravel Passport JWT Token 的痛点

想象一下，你正在开发一个多租户 SaaS 平台，或者一个拥有复杂权限体系的应用。用户通过 Laravel Passport 成功认证后，获得了一个 JWT Token。当这个 Token 被发送到 API 端点时，你可能需要知道：

• 这个用户属于哪个租户？
• 他拥有哪些具体的权限？
• 他是否是管理员？

如果这些信息没有包含在 JWT Token 中，那么在每个需要这些信息的 API 请求中，你都不得不：

1. 从 Token 中解析出用户 ID。
2. 使用用户 ID 去数据库查询用户的详细信息、角色和权限。
3. 根据查询结果进行授权判断。

这种模式在请求量大时，会显著增加数据库的压力和 API 的响应时间。更糟糕的是，它使得授权逻辑分散且重复，降低了代码的可维护性。我们真正需要的是一个“自给自足”的 JWT Token，它能携带所有必要的授权上下文，让 API 端点能够快速、高效地做出决策。

引入救星：corbosman/laravel-passport-claims

幸运的是，PHP 社区的强大之处就在于总有优秀的解决方案出现。corbosman/laravel-passport-claims 这个 Composer 包就是专为解决 Laravel Passport JWT Token 信息不足问题而生。它提供了一种优雅的方式，允许你将自定义数据（Claims）注入到 Passport 生成的 JWT Token 中。

这个包的核心思想是利用管道（Pipeline）机制，在 Token 生成的过程中，让你有机会插入自定义逻辑来添加 Claims。这就像 Laravel 的中间件一样，Token 会依次经过你定义的多个处理类，每个类都可以向 Token 添加额外的信息。

快速上手：安装与配置

首先，使用 Composer 安装这个包。它目前支持 Laravel 9 和 10：

<code class="bash">composer require corbosman/laravel-passport-claims</code>

安装完成后，你需要发布其配置文件，以便定义你希望添加到 Token 中的 Claims：

<code class="bash">php artisan vendor:publish --provider="CorBosman\Passport\ServiceProvider"</code>

这会在 config 目录下生成一个 passport-claims.php 文件。

添加自定义 Claims：让 Token 携带你的数据

现在，是时候创建你的自定义 Claim 类了。这个包提供了一个 Artisan 命令来帮助你快速生成：

<code class="bash">php artisan claim:generate Claims/UserRoleClaim</code>

这会在 app/Claims 目录下创建一个 UserRoleClaim.php 文件（如果你没有 Claims 目录，它会自动创建）。打开这个文件，你会看到类似这样的结构：

<pre class="brush:php;toolbar:false;"><?php

namespace App\Claims;

use CorBosman\Passport\AccessToken;
use Closure;

class UserRoleClaim
{
    public function handle(AccessToken $token, Closure $next)
    {
        // 在这里添加你的自定义 Claims
        $token->addClaim('my-custom-key', 'my-custom-value');

        return $next($token);
    }
}

handle 方法接收一个 AccessToken 实例，它继承自 Laravel\Passport\Bridge\AccessToken，因此你可以访问到 Token 的各种信息，比如用户 ID ($token->getUserIdentifier())。这使得你可以根据用户 ID 查询数据库，并将用户的角色、权限等信息添加到 Token 中。

例如，我们来添加用户的邮箱和角色：

通义灵码

阿里云出品的一款基于通义大模型的智能编码辅助工具，提供代码智能生成、研发智能问答能力

31

查看详情

<pre class="brush:php;toolbar:false;"><?php

namespace App\Claims;

use App\Models\User; // 假设你的用户模型在 App\Models\User
use CorBosman\Passport\AccessToken;
use Closure;

class UserInfoClaim
{
    public function handle(AccessToken $token, Closure $next)
    {
        $user = User::find($token->getUserIdentifier());

        if ($user) {
            $token->addClaim('email', $user->email);
            $token->addClaim('roles', $user->roles()->pluck('name')->toArray()); // 假设用户有 roles 关联
            $token->addClaim('tenant_id', $user->tenant_id); // 如果是多租户应用
        }

        return $next($token);
    }
}

添加完 Claim 类后，别忘了在 config/passport-claims.php 文件的 claims 数组中注册它：

<pre class="brush:php;toolbar:false;"><?php

return [
    'claims' => [
        App\Claims\UserInfoClaim::class,
        // 如果有其他 Claims，也在这里添加
    ]
];

现在，每当 Laravel Passport 生成一个新的 JWT Token 时，你的 UserInfoClaim 类就会被执行，并将用户的邮箱、角色和租户 ID 注入到 Token 中。

利用 Claims 进行授权：中间件的魔力

仅仅将 Claims 添加到 Token 中还不够，我们还需要利用它们进行授权。corbosman/laravel-passport-claims 提供了一个方便的路由中间件 claim，让你可以在路由级别检查 Token 中是否存在某个 Claim，甚至检查 Claim 的值是否符合预期。

首先，在 app/Http/Kernel.php 中注册这个中间件：

<pre class="brush:php;toolbar:false;">protected $routeMiddleware = [
    'claim' => \CorBosman\Passport\Http\Middleware\CheckForClaim::class,
];

然后，你就可以在路由中使用它了：

<pre class="brush:php;toolbar:false;">use Illuminate\Support\Facades\Route;

// 检查 Token 中是否存在 'roles' Claim
Route::middleware(['auth:api', 'claim:roles'])->get('/admin/dashboard', function () {
    return '只有拥有角色的用户才能访问管理后台';
});

// 检查 'roles' Claim 中是否包含 'admin'
Route::middleware(['auth:api', 'claim:roles,admin'])->get('/super-admin/settings', function () {
    return '只有管理员才能访问此设置';
});

// 检查 'tenant_id' Claim 是否为 1 或 2
Route::middleware(['auth:api', 'claim:tenant_id,1|2'])->get('/tenant-specific-data', function () {
    return '只有租户1或租户2的用户才能访问此数据';
});

通过这种方式，你的 API 端点可以非常高效地进行授权判断，无需额外的数据库查询，极大地提升了性能和安全性。

格式化器（Formatters）：解决兼容性问题

有时，你可能会遇到 JWT Token 中日期字段格式不兼容的问题（例如，某些库将时间戳存储为浮点数）。corbosman/laravel-passport-claims 也允许你配置自定义的格式化器来修改现有 Claims。

例如，如果你需要将浮点数时间戳转换回整数，可以在 config/passport-claims.php 中添加：

<pre class="brush:php;toolbar:false;">return [
    'claims' => [
        // ... 你的 Claims 类
    ],
    'formatters' => [
        \Lcobucci\JWT\Encoding\UnifyAudience::class,
        \Lcobucci\JWT\Encoding\UnixTimestampDates::class, // 将浮点数时间戳转换为整数
    ]
];

这确保了你的 JWT Token 在与其他 JWT 库交互时具有更好的兼容性。

总结与展望：让你的 API 飞起来！

通过 corbosman/laravel-passport-claims，我们成功地解决了 Laravel Passport JWT Token 无法携带自定义授权信息的问题。它的优势显而易见：

• 性能提升： 大幅减少了每次请求所需的数据库查询，降低了服务器负载，提高了 API 响应速度。
• 授权灵活性： 可以将任何自定义数据（角色、权限、租户ID、用户偏好等）嵌入 Token，实现更细粒度的授权控制。
• 代码整洁： 将授权上下文与认证过程解耦，使 API 端点的授权逻辑更加简洁明了。
• 微服务友好： 在微服务架构中，Token 携带的丰富信息可以减少服务间通信，提升整体效率。

现在，你的 Laravel API 不再需要为获取用户权限而反复查询数据库，只需解析 Token 即可快速做出授权决策。这不仅让你的代码更加优雅高效，也为构建高性能、高可用的 API 打下了坚实基础。如果你正在使用 Laravel Passport，并且渴望更强大的 JWT Token 功能，那么 corbosman/laravel-passport-claims 绝对值得你一试！

以上就是如何为LaravelPassportJWTToken添加自定义Claims，提升授权灵活性？的详细内容，更多请关注php中文网其它相关文章！