Laravel Passport多组织用户的Token作用域处理方案问询

嘿，这个需求我在做SaaS类项目的时候刚好碰到过！Laravel Passport默认的作用域系统是全局维度的，没法直接区分同一个作用域（比如place-orders）对应的不同组织，不过我们可以通过几种自定义方案来实现这个需求，下面是我实际验证过的思路：

1. 结构化作用域命名（最快捷的落地方案） #

这是不需要额外依赖的原生改造方案，核心就是把组织标识嵌入到作用域名称里：

• 把原来的place-orders拆成place-orders:org_{organization_id}的格式，比如place-orders:org_456就代表仅能对ID为456的组织执行下单操作。
• 授权流程改造：在Passport的授权页面，不要直接展示“place-orders”这个笼统的权限，而是根据当前用户拥有的组织列表，生成对应的细分选项——比如“为组织A授权下单权限”、“为组织B授权下单权限”，让用户勾选具体要授权的组织权限。
• 作用域验证：在接口层，我们需要解析Token中的作用域，提取出对应的组织ID，再和当前请求携带的组织标识（比如请求头X-Organization-ID）做匹配。可以写一个自定义中间件来封装这个逻辑：

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Auth\AuthenticationException;

class CheckOrganizationScope
{
    public function handle($request, Closure $next, $scope)
    {
        $user = $request->user();
        $currentOrgId = $request->header('X-Organization-ID');
        
        if (!$currentOrgId) {
            throw new AuthenticationException('请指定操作的组织ID');
        }

        $requiredScope = "{$scope}:org_{$currentOrgId}";
        if (!$user->tokenCan($requiredScope)) {
            throw new AuthenticationException("您没有对组织{$currentOrgId}执行该操作的权限");
        }

        return $next($request);
    }
}

之后在路由中就可以这样使用：

Route::post('/orders', [OrderController::class, 'store'])
    ->middleware('auth:api')
    ->middleware('check.organization.scope:place-orders');

2. 扩展Passport的作用域模型（更优雅的架构方案） #

如果觉得结构化命名不够优雅，想要更清晰的数据库关联，可以扩展Passport的Scope模型，让作用域和组织直接绑定：

• 先生成一个迁移文件，给oauth_scopes表添加organization_id字段（允许为null，这样还能保留全局作用域的能力）：

Schema::table('oauth_scopes', function (Blueprint $table) {
    $table->unsignedBigInteger('organization_id')->nullable();
    $table->foreign('organization_id')->references('id')->on('organizations')->onDelete('cascade');
});

• 重写Passport的Scope模型，添加和组织的关联：

<?php

namespace App\Models;

use Laravel\Passport\Scope as PassportScope;

class Scope extends PassportScope
{
    public function organization()
    {
        return $this->belongsTo(Organization::class);
    }
}

• 修改Passport配置，让它使用我们自定义的Scope模型：在config/passport.php中添加一行：

'scope_model' => App\Models\Scope::class,

• 授权流程改造：在授权页面，根据用户的组织列表，展示每个组织对应的专属作用域选项，用户勾选后，授权逻辑只发放对应组织关联的作用域Token。
• 验证逻辑：同样需要自定义中间件，验证当前请求的组织ID和Token中作用域绑定的组织ID是否一致。

3. 第三方扩展库（快速落地的备选方案） #

如果不想自己写太多自定义逻辑，可以看看社区的一些扩展，比如laravel/passport-multiauth（虽然它主要是解决多用户类型的问题，但可以结合改造实现组织维度的权限），不过说实话，上面两种自定义方案已经足够灵活，大部分项目不需要额外依赖第三方库。

几个额外的注意点 #

• Token可读性：不管用哪种方案，要确保Token中的作用域信息清晰，方便后续排查权限问题。
• 用户体验：授权页面一定要明确展示每个权限对应的组织，避免用户误授权。
• 性能优化：如果组织和作用域的关联比较稳定，可以缓存权限验证逻辑，提升接口响应速度。

内容的提问来源于stack exchange，提问作者pablorsk