Laravel 用 Passport 落地 OAuth2 授权：密码模式与客户端凭证两种拿 token 的方式

Sanctum 与 Passport 怎么选

Sanctum 适合“第一方可信客户端 + SPA/移动端”的简化令牌，Passport 才是完整的 OAuth2 服务实现：它自带授权码、密码、客户端凭证、隐式等多种模式，并签发标准 JWT 风格的 token。当你要给第三方应用、或要给机器对机器的服务调用发令牌时，Passport 更合适。这里聚焦最常用的两种：密码模式（用户亲自登录换 token）与客户端凭证模式（服务之间调用）。

安装与初始化

composer require laravel/passport
php artisan migrate
php artisan passport:install

在 App\Models\User 里引入 Laravel\Passport\HasApiTokens，并在 AuthServiceProvider 的 boot 中调用 Passport::routes()（Laravel 11 起 routes 默认已注册，老版本需手动加载）。

密码授权模式：用户登录换 token

前端把账号密码交给后端，后端用内置的 /oauth/token 端点换取 access_token。

// 客户端（如移动端）请求示例
POST /oauth/token
{
  "grant_type": "password",
  "client_id": 2,
  "client_secret": "客户端密钥",
  "username": "user@example.com",
  "password": "密码",
  "scope": ""
}

响应里拿到 access_token 后，前端在请求头带上 Authorization: Bearer {token}。保护路由时用 auth:api 中间件。

Route::middleware('auth:api')->get('/me', fn () => auth()->user());

客户端凭证模式：服务对服务调用

没有“用户”概念的定时任务、内部服务互调，用客户端凭证最干净——凭据是 client_id/client_secret，换来的 token 代表应用本身而非某个人。

POST /oauth/token
{
  "grant_type": "client_credentials",
  "client_id": 3,
  "client_secret": "服务密钥",
  "scope": "pull:metrics"
}

颁发时在 Client 上用 scopes 限定权限，token 就只能访问被授权的 scope，权限边界清晰。

工程化注意点

• token 有效期：默认 access_token 一年，生产建议用 passport:client --personal 配合短时效 + refresh_token，密钥务必走环境变量，别提交进仓库。
• scope 是契约：把“能做什么”落成 scope 字符串，比在代码里散落权限判断更可控，Passport 的 tokenCan 直接校验。
• 撤销与轮换：passport:install 可重新生成加密密钥，怀疑泄漏时吊销对应 client 比改全站令牌快得多。