Laravel Passport

简介
- Passport 还是 Sanctum?
安装
- 部署 Passport
- 升级 Passport
配置
授权码模式
带 PKCE 的授权码模式
- 创建客户端
- 请求令牌
设备授权模式
- 创建设备授权客户端
- 请求令牌
密码模式
隐式授权模式
客户端凭证模式
个人访问令牌
路由保护
- 通过中间件
- 传递访问令牌
令牌作用域
SPA 认证
事件
测试

简介

Laravel Passport 能在几分钟内为您的 Laravel 应用提供完整的 OAuth2 服务器实现。Passport 基于 League OAuth2 server 构建，该项目由 Andy Millington 和 Simon Hamp 维护。

[!注意]
本文档假设您已熟悉 OAuth2。如果您对 OAuth2 不了解，建议先熟悉其通用的术语和特性再继续阅读。

陈卿诺语翻译于

由 gyp719 审阅

Passport 还是 Sanctum?

在开始之前，您可能需要确定您的应用更适合使用 Laravel Passport 还是 Laravel Sanctum。如果您的应用必须支持 OAuth2，那么应该使用 Laravel Passport。

但是，如果您需要为单页应用、移动应用提供认证，或仅需发放 API 令牌，那么应该使用 Laravel Sanctum。Laravel Sanctum 不支持 OAuth2，但它提供了更简单的 API 认证开发体验。

安装

您可以通过 install:api Artisan 命令安装 Laravel Passport：

php artisan install:api --passport

该命令将发布并运行必要的数据库迁移，创建用于存储 OAuth2 客户端和访问令牌的表。同时还会创建生成安全访问令牌所需的加密密钥。

运行 install:api 命令后，将 Laravel\Passport\HasApiTokens trait 和 Laravel\Passport\Contracts\OAuthenticatable 接口添加到您的 App\Models\User 模型中。该 trait 会为模型提供一些辅助方法，用于检查已认证用户的令牌和作用域：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

最后，在应用的 config/auth.php 配置文件中，应定义一个 api 认证守卫并将 driver 选项设置为 passport。这将指示应用在认证传入的 API 请求时使用 Passport 的 TokenGuard:

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

陈卿诺语翻译于

由 gyp719 审阅

部署 Passport

首次将 Passport 部署到应用服务器时，可能需要运行 passport:keys 命令。该命令生成 Passport 生成访问令牌所需的加密密钥。生成的密钥通常不纳入版本控制：

php artisan passport:keys

如有需要，可以定义 Passport 密钥的加载路径。使用 Passport::loadKeysFrom 方法实现此功能。通常，应在应用的 App\Providers\AppServiceProvider 类的 boot 方法中调用此方法：

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::loadKeysFrom(__DIR__.'/../secrets/oauth');
}

从环境变量加载密钥

或者，您可以使用 vendor:publish Artisan 命令发布 Passport 的配置文件：

php artisan vendor:publish --tag=passport-config

发布配置文件后，可以通过环境变量定义应用的加密密钥：

PASSPORT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
<private key here>
-----END RSA PRIVATE KEY-----"

PASSPORT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
<public key here>
-----END PUBLIC KEY-----"

升级 Passport

升级到 Passport 的新主要版本时，请务必仔细查阅升级指南。

配置

令牌生命周期

默认情况下，Passport 颁发长期有效的访问令牌，有效期为一年。如需配置更长或更短的令牌生命周期，可以使用 tokensExpireIn, refreshTokensExpireIn, 和 personalAccessTokensExpireIn 方法。这些方法应在应用的 App\Providers\AppServiceProvider 类的 boot 方法中调用：

use Carbon\CarbonInterval;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::tokensExpireIn(CarbonInterval::days(15));
    Passport::refreshTokensExpireIn(CarbonInterval::days(30));
    Passport::personalAccessTokensExpireIn(CarbonInterval::months(6));
}

[!警告]
Passport 数据库表中的 expires_at 列是只读的，仅用于显示目的。颁发令牌时，Passport 将过期信息存储在签名和加密的令牌中。如需使令牌失效，应撤销令牌.

陈卿诺语翻译于

由 gyp719 审阅

覆盖默认模型（Overriding Default Models）

你可以通过定义你自己的模型并扩展相应的 Passport 模型，来自由地扩展 Passport 内部使用的模型：

use Laravel\Passport\Client as PassportClient;

class Client extends PassportClient
{
    // ...
}

在定义你的模型之后，你可以通过 Laravel\Passport\Passport 类指示 Passport 使用你的自定义模型。通常，你应该在应用程序的 App\Providers\AppServiceProvider 类的 boot 方法中告知 Passport 你的自定义模型：

use App\Models\Passport\AuthCode;
use App\Models\Passport\Client;
use App\Models\Passport\DeviceCode;
use App\Models\Passport\RefreshToken;
use App\Models\Passport\Token;

/**
 * 初始化应用程序所需的服务。
 */
public function boot(): void
{
    Passport::useTokenModel(Token::class);
    Passport::useRefreshTokenModel(RefreshToken::class);
    Passport::useAuthCodeModel(AuthCode::class);
    Passport::useClientModel(Client::class);
    Passport::useDeviceCodeModel(DeviceCode::class)
}

覆盖路由（Overriding Routes）

有时你可能希望自定义 Passport 定义的路由。为了实现这一点，你首先需要通过在应用程序的 AppServiceProvider 的 register 方法中添加 Passport::ignoreRoutes 来忽略 Passport 注册的路由：

use Laravel\Passport\Passport;

/**
 * 注册应用程序中需要的服务。
 */
public function register(): void
{
    Passport::ignoreRoutes();
}

然后，你可以将 Passport 在其路由文件中定义的路由复制到你应用程序的 routes/web.php 文件中，并根据你的需要进行修改：

Route::group([
    'as' => 'passport.',
    'prefix' => config('passport.path', 'oauth'),
    'namespace' => '\Laravel\Passport\Http\Controllers',
], function () {
    // Passport routes...
});

授权码授权流程（Authorization Code Grant）

无与伦比翻译于

使用 OAuth2 的授权码模式是大多数开发者最熟悉的方式。在这种模式下，客户端应用会把用户重定向到你的服务器，由用户决定是否授权该客户端获取访问令牌。

要开始使用这一流程，我们需要告诉 Passport 如何渲染授权页面。

你可以通过 Laravel\Passport\Passport 类提供的方法，自定义授权页面的渲染逻辑。一般来说，你会在应用的 App\Providers\AppServiceProvider 的 boot 方法中进行配置，例如：

use Inertia\Inertia;
use Laravel\Passport\Passport;

public function boot(): void
{
    // 使用 Blade 视图
    Passport::authorizationView('auth.oauth.authorize');

    // 使用闭包自定义渲染（例如 Inertia）
    Passport::authorizationView(
        fn ($parameters) => Inertia::render('Auth/OAuth/Authorize', [
            'request' => $parameters['request'],
            'authToken' => $parameters['authToken'],
            'client' => $parameters['client'],
            'user' => $parameters['user'],
            'scopes' => $parameters['scopes'],
        ])
    );
}

Passport 会自动注册 /oauth/authorize 路由，并返回你所配置的授权页面。
你的 auth.oauth.authorize 视图需要包含两个表单：

一个发送 POST 请求到 passport.authorizations.approve，用于批准授权；
一个发送 DELETE 请求到 passport.authorizations.deny，用于拒绝授权。

这两个路由都会要求提交：state、client_id、auth_token 这几个字段。

客户端管理

如果其他开发者想让他们的应用与您的 API 通信，他们需要先在你的系统里为他们的应用创建一个“客户端”。通常，他们只需要提供应用的名称，以及在用户授权后，你的系统应将用户重定向回去的 URI。

无与伦比翻译于

第一方客户端

创建客户端最简单的方式是使用 passport:client Artisan 命令。此命令可用于创建第一方客户端或测试你的 OAuth2 功能。当你运行 passport:client 命令时，Passport 会提示你提供关于你的客户端的更多信息，并会向你提供一个客户端 ID 和 secret：

php artisan passport:client

如果你想为你的客户端允许多个重定向 URI，你可以在 passport:client 命令提示输入 URI 时，使用逗号分隔的列表来指定它们。任何包含逗号的 URI 应当进行 URI 编码：

https://third-party-app.com/callback,https://example.com/oauth/redirect

第三方客户端

由于你的应用程序的用户无法使用 passport:client 命令，你可以使用 Laravel\Passport\ClientRepository 类的 createAuthorizationCodeGrantClient 方法，为指定用户注册一个客户端：

use App\Models\User;
use Laravel\Passport\ClientRepository;

$user = User::find($userId);

// 创建一个属于给定用户的 OAuth 应用客户端…
$client = app(ClientRepository::class)->createAuthorizationCodeGrantClient(
    user: $user,
    name: 'Example App',
    redirectUris: ['https://third-party-app.com/callback'],
    confidential: false,
    enableDeviceFlow: true
);

// 获取所有属于该用户的 OAuth 应用客户端…
$clients = $user->oauthApps()->get();

createAuthorizationCodeGrantClient 方法返回一个 Laravel\Passport\Client 实例。你可以将 $client->id 显示为客户端 ID，并将 $client->plainSecret 显示为客户端 secret 给用户。

请求令牌（Requesting Tokens）

无与伦比翻译于

重定向以进行授权

一旦客户端被创建，开发者可以使用他们的客户端 ID 和密钥向你的应用请求授权码和访问令牌。首先，使用者的应用应向你的应用的 /oauth/authorize 路由发起重定向请求，如下所示：

use Illuminate\Http\Request;
use Illuminate\Support\Str;

Route::get('/redirect', function (Request $request) {
    $request->session()->put('state', $state = Str::random(40));

    $query = http_build_query([
        'client_id' => 'your-client-id',
        'redirect_uri' => 'https://third-party-app.com/callback',
        'response_type' => 'code',
        'scope' => 'user:read orders:create',
        'state' => $state,
        // 'prompt' => '', // "none", "consent", 或 "login"
    ]);

    return redirect('https://passport-app.test/oauth/authorize?'.$query);
});

prompt 参数可用于指定 Passport 应用的认证行为。

如果 prompt 值为 none，当用户尚未在 Passport 应用中认证时，Passport 将始终抛出认证错误。
如果值为 consent，即使所有权限（scopes）之前已授予给使用应用，Passport 也将始终显示授权批准界面。
如果值为 login，即使用户已有现有会话，Passport 也将始终提示用户重新登录应用。

如果未提供 prompt 值，只有当用户之前未授权使用应用访问请求的权限时，才会提示用户进行授权。

[!注意]
请记住，/oauth/authorize 路由已经由 Passport 定义。你不需要手动定义此路由。

批准请求

无与伦比翻译于

在接收授权请求时，Passport 会根据 prompt 参数的值（如果存在）自动响应，并可能向用户显示一个模板，让他们批准或拒绝该授权请求。如果用户批准请求，他们将被重定向回由使用应用指定的 redirect_uri。该 redirect_uri 必须与创建客户端时指定的 redirect URL 匹配。

有时你可能希望跳过授权提示，例如在授权第一方客户端时。你可以通过扩展 Client 模型并定义 skipsAuthorization 方法来实现这一点。如果 skipsAuthorization 返回 true，客户端将被自动批准，并且用户将立即被重定向回 redirect_uri，除非使用应用在进行授权重定向时明确设置了 prompt 参数：

<?php

namespace App\Models\Passport;

use Illuminate\Contracts\Auth\Authenticatable;
use Laravel\Passport\Client as BaseClient;

class Client extends BaseClient
{
    /**
     * 判断客户端是否应跳过授权提示。
     *
     * @param  \Laravel\Passport\Scope[]  $scopes
     */
    public function skipsAuthorization(Authenticatable $user, array $scopes): bool
    {
        return $this->firstParty();
    }
}

将授权码转换为访问令牌

如果用户批准了授权请求，他们将被重定向回使用应用。使用应用首先应验证 state 参数是否与重定向前存储的值一致。如果 state 参数匹配，则使用应用应向你的应用发起 POST 请求，以请求访问令牌。请求应包含在用户批准授权请求时由你的应用发放的授权码：

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

Route::get('/callback', function (Request $request) {
    $state = $request->session()->pull('state');

    throw_unless(
        strlen($state) > 0 && $state === $request->state,
        InvalidArgumentException::class,
        '状态值无效。'
    );

    $response = Http::asForm()->post('https://passport-app.test/oauth/token', [
        'grant_type' => 'authorization_code',
        'client_id' => 'your-client-id',
        'client_secret' => 'your-client-secret',
        'redirect_uri' => 'https://third-party-app.com/callback',
        'code' => $request->code,
    ]);

    return $response->json();
});

无与伦比翻译于

这个 /oauth/token 路由将返回一个包含 access_token、refresh_token 和 expires_in 属性的 JSON 响应。expires_in 属性包含访问令牌过期前的秒数。

[!注意]
与 /oauth/authorize 路由一样，/oauth/token 路由已由 Passport 为你定义。无需手动定义此路由。

管理令牌

你可以使用 Laravel\Passport\HasApiTokens trait 的 tokens 方法检索用户已授权的令牌。例如，这可用于为用户提供一个仪表盘，以跟踪他们与第三方应用的连接情况：

use App\Models\User;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\Date;
use Laravel\Passport\Token;

$user = User::find($userId);

// 获取该用户的所有有效令牌...
$tokens = $user->tokens()
    ->where('revoked', false)
    ->where('expires_at', '>', Date::now())
    ->get();

// 获取该用户与第三方 OAuth 应用客户端的所有连接...
$connections = $tokens->load('client')
    ->reject(fn (Token $token) => $token->client->firstParty())
    ->groupBy('client_id')
    ->map(fn (Collection $tokens) => [
        'client' => $tokens->first()->client,
        'scopes' => $tokens->pluck('scopes')->flatten()->unique()->values()->all(),
        'tokens_count' => $tokens->count(),
    ])
    ->values();

刷新令牌

如果你的应用发放的是短期访问令牌，用户将需要通过在发放访问令牌时提供的刷新令牌来刷新他们的访问令牌：

use Illuminate\Support\Facades\Http;

$response = Http::asForm()->post('https://passport-app.test/oauth/token', [
    'grant_type' => 'refresh_token',
    'refresh_token' => 'the-refresh-token',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret', // 仅对机密客户端必需...
    'scope' => 'user:read orders:create',
]);

return $response->json();

这个 /oauth/token 路由将返回一个包含 access_token、refresh_token 和 expires_in 属性的 JSON 响应。expires_in 属性包含访问令牌过期前的秒数。

无与伦比翻译于

撤销令牌

你可以使用 Laravel\Passport\Token 模型的 revoke 方法撤销一个令牌。你也可以使用 Laravel\Passport\RefreshToken 模型的 revoke 方法撤销令牌的刷新令牌：

use Laravel\Passport\Passport;
use Laravel\Passport\Token;

$token = Passport::token()->find($tokenId);

// 撤销访问令牌...
$token->revoke();

// 撤销该令牌的刷新令牌...
$token->refreshToken?->revoke();

// 撤销该用户的所有令牌...
User::find($userId)->tokens()->each(function (Token $token) {
    $token->revoke();
    $token->refreshToken?->revoke();
});

清理令牌

当令牌被撤销或已过期时，你可能希望从数据库中清理它们。Passport 自带的 passport:purge Artisan 命令可以为你执行此操作：

# 清理已撤销和已过期的令牌、授权码和设备码...
php artisan passport:purge

# 仅清理已过期超过 6 小时的令牌...
php artisan passport:purge --hours=6

# 仅清理已撤销的令牌、授权码和设备码...
php artisan passport:purge --revoked

# 仅清理已过期的令牌、授权码和设备码...
php artisan passport:purge --expired

你还可以在应用的 routes/console.php 文件中配置计划任务，定期自动修剪令牌：

use Illuminate\Support\Facades\Schedule;

Schedule::command('passport:purge')->hourly();

使用 PKCE 的授权码模式

带有 “Proof Key for Code Exchange” (PKCE) 的授权码模式是一种安全方式，用于让单页应用或移动应用认证以访问你的 API。当你无法保证客户端密钥能够被安全存储，或者为了降低授权码被攻击者截获的风险时，应使用此授权模式。在将授权码交换为访问令牌时，一组 “code verifier” 和 “code challenge” 将替代客户端密钥。

无与伦比翻译于

创建客户端

在你的应用可以通过带 PKCE 的授权码模式发放令牌之前，你需要创建一个启用 PKCE 的客户端。你可以使用 passport:client Artisan 命令并加上 --public 选项来完成此操作：

php artisan passport:client --public

请求令牌

Code Verifier 与 Code Challenge

由于此授权模式不提供客户端密钥，开发者需要生成一组 code verifier 和 code challenge 组合，以便请求令牌。

code verifier 应为 43 到 128 个字符之间的随机字符串，包含字母、数字，以及 "-"、"."、"_"、"~" 字符，如 RFC 7636 规范所定义。

code challenge 应为使用 URL 和文件名安全字符的 Base64 编码字符串。末尾的 '=' 字符应移除，并且不应有换行符、空白或其他额外字符。

$encoded = base64_encode(hash('sha256', $codeVerifier, true));

$codeChallenge = strtr(rtrim($encoded, '='), '+/', '-_');

重定向以进行授权

一旦客户端被创建，你可以使用客户端 ID 以及生成的 code verifier 和 code challenge 向你的应用请求授权码和访问令牌。首先，使用应用应向你的应用的 /oauth/authorize 路由发起重定向请求：

use Illuminate\Http\Request;
use Illuminate\Support\Str;

Route::get('/redirect', function (Request $request) {
    $request->session()->put('state', $state = Str::random(40));

    $request->session()->put(
        'code_verifier', $codeVerifier = Str::random(128)
    );

    $codeChallenge = strtr(rtrim(
        base64_encode(hash('sha256', $codeVerifier, true))
    , '='), '+/', '-_');

    $query = http_build_query([
        'client_id' => 'your-client-id',
        'redirect_uri' => 'https://third-party-app.com/callback',
        'response_type' => 'code',
        'scope' => 'user:read orders:create',
        'state' => $state,
        'code_challenge' => $codeChallenge,
        'code_challenge_method' => 'S256',
        // 'prompt' => '', // "none", "consent", or "login"
    ]);

    return redirect('https://passport-app.test/oauth/authorize?'.$query);
});

无与伦比翻译于

将授权码转换为访问令牌

如果用户批准了授权请求，他们将被重定向回使用该授权的应用程序。和标准的授权码授权模式一样，消费端应当将 state 参数与重定向前存储的值进行验证。

如果 state 参数匹配，消费端应当向你的应用程序发起一个 POST 请求以请求访问令牌。该请求应当包含当用户批准授权请求时你的应用程序颁发的授权码，以及最初生成的 code verifier：

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

Route::get('/callback', function (Request $request) {
    $state = $request->session()->pull('state');

    $codeVerifier = $request->session()->pull('code_verifier');

    throw_unless(
        strlen($state) > 0 && $state === $request->state,
        InvalidArgumentException::class
    );

    $response = Http::asForm()->post('https://passport-app.test/oauth/token', [
        'grant_type' => 'authorization_code',
        'client_id' => 'your-client-id',
        'redirect_uri' => 'https://third-party-app.com/callback',
        'code_verifier' => $codeVerifier,
        'code' => $request->code,
    ]);

    return $response->json();
});

设备授权许可（Device Authorization Grant）

OAuth2 设备授权许可允许无浏览器或输入受限的设备（例如电视和游戏主机）通过交换 “device code” 来获取访问令牌。当使用设备流程时，设备客户端会指示用户使用另一台设备（如电脑或智能手机）连接到你的服务器，在那里输入提供的 “user code”，并批准或拒绝访问请求。

为了开始，我们需要指示 Passport 如何返回我们的 “user code” 和 “authorization” 视图。

无与伦比翻译于

授权视图的所有渲染逻辑都可以通过 Laravel\Passport\Passport 类提供的相应方法进行自定义。通常，你应该在应用程序的 App\Providers\AppServiceProvider 类的 boot 方法中调用这些方法。

use Inertia\Inertia;
use Laravel\Passport\Passport;

/**
 * 启动应用程序所需的各项服务。
 */
public function boot(): void
{
    // 通过提供视图名称...
    Passport::deviceUserCodeView('auth.oauth.device.user-code');
    Passport::deviceAuthorizationView('auth.oauth.device.authorize');

    // 通过提供闭包...
    Passport::deviceUserCodeView(
        fn ($parameters) => Inertia::render('Auth/OAuth/Device/UserCode')
    );

    Passport::deviceAuthorizationView(
        fn ($parameters) => Inertia::render('Auth/OAuth/Device/Authorize', [
            'request' => $parameters['request'],
            'authToken' => $parameters['authToken'],
            'client' => $parameters['client'],
            'user' => $parameters['user'],
            'scopes' => $parameters['scopes'],
        ])
    );

    // ...
}

Passport 会自动定义返回这些视图的路由。你的 auth.oauth.device.user-code 模板应包含一个表单，该表单向 passport.device.authorizations.authorize 路由发起 GET 请求。passport.device.authorizations.authorize 路由需要一个 user_code 查询参数。

你的 auth.oauth.device.authorize 模板应包含一个表单，用于向 passport.device.authorizations.approve 路由发起 POST 请求以批准授权，以及一个表单用于向 passport.device.authorizations.deny 路由发起 DELETE 请求以拒绝授权。passport.device.authorizations.approve 和 passport.device.authorizations.deny 路由需要 state、client_id 和 auth_token 字段。

创建设备授权许可客户端

在你的应用程序能够通过设备授权许可颁发令牌之前，你需要创建一个启用设备流程的客户端。你可以使用带有 --device 选项的 passport:client Artisan 命令来完成此操作。此命令将创建一个第一方的、启用设备流程的客户端，并向你提供客户端 ID 和密钥：

php artisan passport:client --device

无与伦比翻译于

此外，你可以在 ClientRepository 类上使用 createDeviceAuthorizationGrantClient 方法，为指定用户注册一个第三方客户端：

use App\Models\User;
use Laravel\Passport\ClientRepository;

$user = User::find($userId);

$client = app(ClientRepository::class)->createDeviceAuthorizationGrantClient(
    user: $user,
    name: 'Example Device',
    confidential: false,
);

请求令牌

请求设备代码（Device Code）

一旦客户端被创建，开发者可以使用其客户端 ID 从你的应用程序请求设备代码。首先，消费设备应向你的应用程序的 /oauth/device/code 路由发送一个 POST 请求，以请求设备代码：

use Illuminate\Support\Facades\Http;

$response = Http::asForm()->post('https://passport-app.test/oauth/device/code', [
    'client_id' => 'your-client-id',
    'scope' => 'user:read orders:create',
]);

return $response->json();

这将返回一个包含 device_code、user_code、verification_uri、interval 和 expires_in 属性的 JSON 响应。expires_in 属性包含距离设备代码过期的秒数。interval 属性包含消费设备在轮询 /oauth/token 路由时，为避免速率限制错误应等待的秒数。

[!注意]
请记住，/oauth/device/code 路由已经由 Passport 定义，你不需要手动定义此路由。

显示验证 URI 和用户代码

一旦获得设备代码请求，消费设备应指示用户使用另一台设备访问提供的 verification_uri，并输入 user_code 以批准授权请求。

无与伦比翻译于

轮询令牌请求（Polling Token Request）

由于用户将使用一台独立的设备来授予（或拒绝）访问权限，消费设备应当轮询你的应用程序的 /oauth/token 路由，以确定用户何时对请求作出了响应。消费设备在请求设备代码时，应使用 JSON 响应中提供的最小轮询 interval，以避免速率限制错误：

use Illuminate\Support\Facades.Http;
use Illuminate\Support\Sleep;

$interval = 5;

do {
    Sleep::for($interval)->seconds();

    $response = Http::asForm()->post('https://passport-app.test/oauth/token', [
        'grant_type' => 'urn:ietf:params:oauth:grant-type:device_code',
        'client_id' => 'your-client-id',
        'client_secret' => 'your-client-secret', // 仅对保密客户端（confidential clients）需要...
        'device_code' => 'the-device-code',
    ]);

    if ($response->json('error') === 'slow_down') {
        $interval += 5;
    }
} while (in_array($response->json('error'), ['authorization_pending', 'slow_down']));

return $response->json();

如果用户已批准授权请求，这将返回一个包含 access_token、refresh_token 和 expires_in 属性的 JSON 响应。expires_in 属性包含距离访问令牌过期的秒数。

密码授权（Password Grant）

[!警告]
我们不再推荐使用密码授权令牌。相反，你应当选择 OAuth2 Server 当前推荐的授予类型。

OAuth2 密码授权允许你的其他第一方客户端（例如移动应用）使用电子邮件地址 / 用户名和密码来获取访问令牌。这使你能够安全地向你的第一方客户端签发访问令牌，而无需让用户经历完整的 OAuth2 授权码重定向流程。

无与伦比翻译于

要启用密码授权（password grant），请在你应用程序的 App\Providers\AppServiceProvider 类的 boot 方法中调用 enablePasswordGrant 方法：

/**
 * 初始化应用程序服务。
 */
public function boot(): void
{
    Passport::enablePasswordGrant();
}

创建密码授权客户端

在你的应用程序能够通过密码授权颁发令牌之前，你需要创建一个密码授权客户端。你可以使用带有 --password 选项的 passport:client Artisan 命令来完成此操作。

php artisan passport:client --password

请求令牌

一旦你启用了授权方式并创建了密码授权客户端，你可以向 /oauth/token 路由发起一个 POST 请求，通过提供用户的电子邮件地址和密码来请求访问令牌。请记住，此路由已经由 Passport 注册，因此无需手动定义它。如果请求成功，你将从服务器返回的 JSON 响应中收到一个 access_token 和 refresh_token：

use Illuminate\Support\Facades.Http;

$response = Http::asForm()->post('https://passport-app.test/oauth/token', [
    'grant_type' => 'password',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret', // 仅对保密客户端（confidential clients）需要...
    'username' => 'taylor@laravel.com',
    'password' => 'my-password',
    'scope' => 'user:read orders:create',
]);

return $response->json();

[!注意]
请记住，访问令牌默认是长时效的。但是，如果需要，你可以自由地 配置你的访问令牌的最大生命周期。

请求所有作用域（Scopes）

当使用密码授权或客户端凭据授权（client credentials grant）时，你可能希望为令牌授权你的应用程序所支持的所有作用域。你可以通过请求 * 作用域来实现这一点。如果你请求了 * 作用域，那么令牌实例上的 can 方法将始终返回 true。此作用域只能分配给使用 password 或 client_credentials 授权方式签发的令牌：

use Illuminate\Support\Facades\Http;

$response = Http::asForm()->post('https://passport-app.test/oauth/token', [
    'grant_type' => 'password',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret', // Required for confidential clients only...
    'username' => 'taylor@laravel.com',
    'password' => 'my-password',
    'scope' => '*',
]);

无与伦比翻译于

自定义用户提供者

如果你的应用程序使用了多个认证用户提供者，你可以在通过 artisan passport:client --password 命令创建客户端时，提供 --provider 选项来指定密码授权客户端所使用的用户提供者。所给的提供者名称应当与应用程序的 config/auth.php 配置文件中定义的有效提供者相匹配。然后，你可以使用中间件来保护你的路由，以确保只有来自该守卫所指定提供者的用户才被授权。

自定义用户名字段

在使用密码授权进行认证时，Passport 会使用你的可认证模型的 email 属性作为“用户名”。然而，你可以通过在模型上定义一个 findForPassport 方法来自定义此行为：

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens, Notifiable;

    /**
     * 查找给定用户名的用户实例。
     */
    public function findForPassport(string $username): User
    {
        return $this->where('username', $username)->first();
    }
}

自定义密码验证

在使用密码授权进行认证时，Passport 会使用你模型的 password 属性来验证所给密码。如果你的模型没有 password 属性，或者你希望自定义密码验证逻辑，你可以在模型上定义一个 validateForPassportPasswordGrant 方法：

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Illuminate\Support\Facades\Hash;
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens, Notifiable;

    /**
     * 为 Passport 密码授权验证用户的密码。
     */
    public function validateForPassportPasswordGrant(string $password): bool
    {
        return Hash::check($password, $this->password);
    }
}

无与伦比翻译于

隐式授权（Implicit Grant）

[!警告]
我们不再推荐使用隐式授权令牌。相反，你应该选择 OAuth2 Server 当前推荐的授权类型。

隐式授权与授权码授权类似；然而，该令牌会直接返回给客户端，而无需交换授权码。此授权最常用于无法安全存储客户端凭据的 JavaScript 或移动应用程序。要启用该授权，请在应用程序的 App\Providers\AppServiceProvider 类的 boot 方法中调用 enableImplicitGrant 方法：

/**
 * 在应用启动时进行服务的初始化配置。
 */
public function boot(): void
{
    Passport::enableImplicitGrant();
}

在你的应用程序能够通过隐式授权发放令牌之前，你需要创建一个隐式授权客户端。你可以使用带有 --implicit 选项的 passport:client Artisan 命令来完成此操作。

php artisan passport:client --implicit

一旦授权已启用并创建了隐式客户端，开发者就可以使用其客户端 ID 从你的应用程序请求访问令牌。消费端应用程序应当这样向你的应用程序的 /oauth/authorize 路由发起一个重定向请求：

use Illuminate\Http\Request;

Route::get('/redirect', function (Request $request) {
    $request->session()->put('state', $state = Str::random(40));

    $query = http_build_query([
        'client_id' => 'your-client-id',
        'redirect_uri' => 'https://third-party-app.com/callback',
        'response_type' => 'token',
        'scope' => 'user:read orders:create',
        'state' => $state,
        // 'prompt' => '', // "none", "consent", or "login"
    ]);

    return redirect('https://passport-app.test/oauth/authorize?'.$query);
});

[!注意]
请记住，/oauth/authorize 路由已经由 Passport 定义。你无需手动定义此路由。

无与伦比翻译于

客户端凭据授权（Client Credentials Grant）

客户端凭据授权适用于机器对机器的认证。例如，你可以在一个计划任务中使用这种授权，该任务通过 API 执行维护操作。

在你的应用程序能够通过客户端凭据授权发放令牌之前，你需要创建一个客户端凭据授权客户端。你可以使用 passport:client Artisan 命令的 --client 选项来完成此操作：

php artisan passport:client --client

接下来，将 Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner 中间件分配给一个路由：

use Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner;

Route::get('/orders', function (Request $request) {
    // 访问令牌有效，并且该客户端是资源所有者……
})->middleware(EnsureClientIsResourceOwner::class);

要将路由访问限制为特定的作用域（scopes），你可以向 using 方法提供所需作用域的列表：

Route::get('/orders', function (Request $request) {
     // 访问令牌有效，客户端是资源所有者，并且拥有 “servers:read” 和 “servers:create” 这两个作用域……
})->middleware(EnsureClientIsResourceOwner::using('servers:read', 'servers:create');

获取令牌（Retrieving Tokens）

要使用此授权类型获取一个令牌，向 oauth/token 端点发起一个请求：

use Illuminate\Support\Facades\Http;

$response = Http::asForm()->post('https://passport-app.test/oauth/token', [
    'grant_type' => 'client_credentials',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'scope' => 'servers:read servers:create',
]);

return $response->json()['access_token'];

个人访问令牌（Personal Access Tokens）

有时，你的用户可能希望在不经过典型的授权码重定向流程的情况下给自己发放访问令牌。允许用户通过你的应用程序的 UI 自行发放令牌，对于让用户尝试你的 API 非常有用，或者可以作为一种更简单的方式来发放访问令牌。

[!笔记]
如果你的应用程序主要使用 Passport 来发放个人访问令牌，考虑使用 Laravel Sanctum，Laravel 的轻量级一方库，用于发放 API 访问令牌。

无与伦比翻译于

创建个人访问客户端（Creating a Personal Access Client）

在你的应用程序能够发放个人访问令牌之前，你需要创建一个个人访问客户端。你可以通过执行带有 --personal 选项的 passport:client Artisan 命令来完成此操作。如果你已经运行过 passport:install 命令，则不需要再次运行此命令：

php artisan passport:client --personal

自定义用户提供者（Customizing the User Provider）

如果你的应用程序使用了多个认证用户提供者，你可以在通过 artisan passport:client --personal 命令创建客户端时，通过提供 --provider 选项来指定个人访问授权客户端所使用的用户提供者。所给的提供者名称应当与应用程序的 config/auth.php 配置文件中定义的有效提供者相匹配。然后，你可以使用中间件保护你的路由，以确保只有来自该守卫所指定提供者的用户被授权。

管理个人访问令牌（Managing Personal Access Tokens）

创建个人访问客户端之后，你可以使用 App\Models\User 模型实例上的 createToken 方法为指定用户发放令牌。createToken 方法接收令牌名称作为其第一个参数，并将一个可选的作用域（scopes）数组作为第二个参数：

use App\Models\User;
use Illuminate\Support\Facades\Date;
use Laravel\Passport\Token;

$user = User::find($userId);

// 创建一个无作用域的令牌...
$token = $user->createToken('My Token')->accessToken;

// 创建一个带作用域的令牌...
$token = $user->createToken('My Token', ['user:read', 'orders:create'])->accessToken;

// 创建一个包含所有作用域的令牌...
$token = $user->createToken('My Token', ['*'])->accessToken;

// 获取属于该用户的所有有效个人访问令牌...
$tokens = $user->tokens()
    ->with('client')
    ->where('revoked', false)
    ->where('expires_at', '>', Date::now())
    ->get()
    ->filter(fn (Token $token) => $token->client->hasGrantType('personal_access'));

无与伦比翻译于

保护路由（Protecting Routes）

通过中间件（Via Middleware）

Passport 包含一个认证守卫，它将验证传入请求中的访问令牌。一旦你将 api 守卫配置为使用 passport 驱动，你只需要在任何应当要求有效访问令牌的路由上指定 auth:api 中间件即可：

Route::get('/user', function () {
    // 只有通过 API 认证的用户才能访问此路由...
})->middleware('auth:api');

[!警告]
如果你使用的是客户端凭据授权，你应该使用 Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner 中间件来保护你的路由，而不是使用 auth:api 中间件。

多个认证守卫（Multiple Authentication Guards）

如果你的应用程序对不同类型的用户进行认证，并且这些用户可能使用完全不同的 Eloquent 模型，那么你可能需要在应用程序中为每种用户提供者类型定义一个守卫配置。这允许你保护针对特定用户提供者的请求。例如，给定 config/auth.php 配置文件中的以下守卫配置：

'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],

    'api-customers' => [
        'driver' => 'passport',
        'provider' => 'customers',
    ],
],

下面的路由将使用 api-customers 守卫（该守卫使用 customers 用户提供者）来认证传入的请求：

Route::get('/customer', function () {
    // ...
})->middleware('auth:api-customers');

[!注意]
关于在 Passport 中使用多个用户提供者的更多信息，请查阅个人访问令牌文档和密码授权文档。

传递访问令牌（Passing the Access Token）

当调用由 Passport 保护的路由时，你的应用程序的 API 使用者应当在请求的 Authorization 头中，将他们的访问令牌作为 Bearer 令牌进行指定。例如，当使用 Http Facade 时：

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => "Bearer $accessToken",
])->get('https://passport-app.test/api/user');

return $response->json();

无与伦比翻译于

Token Scopes

Scopes allow your API clients to request a specific set of permissions when requesting authorization to access an account. For example, if you are building an e-commerce application, not all API consumers will need the ability to place orders. Instead, you may allow the consumers to only request authorization to access order shipment statuses. In other words, scopes allow your application's users to limit the actions a third-party application can perform on their behalf.

Defining Scopes

You may define your API's scopes using the Passport::tokensCan method in the boot method of your application's App\Providers\AppServiceProvider class. The tokensCan method accepts an array of scope names and scope descriptions. The scope description may be anything you wish and will be displayed to users on the authorization approval screen:

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::tokensCan([
        'user:read' => 'Retrieve the user info',
        'orders:create' => 'Place orders',
        'orders:read:status' => 'Check order status',
    ]);
}

Default Scope

If a client does not request any specific scopes, you may configure your Passport server to attach default scopes to the token using the defaultScopes method. Typically, you should call this method from the boot method of your application's App\Providers\AppServiceProvider class:

use Laravel\Passport\Passport;

Passport::tokensCan([
    'user:read' => 'Retrieve the user info',
    'orders:create' => 'Place orders',
    'orders:read:status' => 'Check order status',
]);

Passport::defaultScopes([
    'user:read',
    'orders:create',
]);

Assigning Scopes to Tokens

When Requesting Authorization Codes

When requesting an access token using the authorization code grant, consumers should specify their desired scopes as the scope query string parameter. The scope parameter should be a space-delimited list of scopes:

Route::get('/redirect', function () {
    $query = http_build_query([
        'client_id' => 'your-client-id',
        'redirect_uri' => 'https://third-party-app.com/callback',
        'response_type' => 'code',
        'scope' => 'user:read orders:create',
    ]);

    return redirect('https://passport-app.test/oauth/authorize?'.$query);
});

When Issuing Personal Access Tokens

If you are issuing personal access tokens using the App\Models\User model's createToken method, you may pass the array of desired scopes as the second argument to the method:

$token = $user->createToken('My Token', ['orders:create'])->accessToken;

Checking Scopes

Passport includes two middleware that may be used to verify that an incoming request is authenticated with a token that has been granted a given scope.

Check For All Scopes

The Laravel\Passport\Http\Middleware\CheckToken middleware may be assigned to a route to verify that the incoming request's access token has all the listed scopes:

use Laravel\Passport\Http\Middleware\CheckToken;

Route::get('/orders', function () {
    // Access token has both "orders:read" and "orders:create" scopes...
})->middleware(['auth:api', CheckToken::using('orders:read', 'orders:create');

Check for Any Scopes

The Laravel\Passport\Http\Middleware\CheckTokenForAnyScope middleware may be assigned to a route to verify that the incoming request's access token has at least one of the listed scopes:

use Laravel\Passport\Http\Middleware\CheckTokenForAnyScope;

Route::get('/orders', function () {
    // Access token has either "orders:read" or "orders:create" scope...
})->middleware(['auth:api', CheckTokenForAnyScope::using('orders:read', 'orders:create');

Checking Scopes on a Token Instance

Once an access token authenticated request has entered your application, you may still check if the token has a given scope using the tokenCan method on the authenticated App\Models\User instance:

use Illuminate\Http\Request;

Route::get('/orders', function (Request $request) {
    if ($request->user()->tokenCan('orders:create')) {
        // ...
    }
});

Additional Scope Methods

The scopeIds method will return an array of all defined IDs / names:

use Laravel\Passport\Passport;

Passport::scopeIds();

The scopes method will return an array of all defined scopes as instances of Laravel\Passport\Scope:

Passport::scopes();

The scopesFor method will return an array of Laravel\Passport\Scope instances matching the given IDs / names:

Passport::scopesFor(['user:read', 'orders:create']);

You may determine if a given scope has been defined using the hasScope method:

Passport::hasScope('orders:create');

SPA Authentication

When building an API, it can be extremely useful to be able to consume your own API from your JavaScript application. This approach to API development allows your own application to consume the same API that you are sharing with the world. The same API may be consumed by your web application, mobile applications, third-party applications, and any SDKs that you may publish on various package managers.

Typically, if you want to consume your API from your JavaScript application, you would need to manually send an access token to the application and pass it with each request to your application. However, Passport includes a middleware that can handle this for you. All you need to do is append the CreateFreshApiToken middleware to the web middleware group in your application's bootstrap/app.php file:

use Laravel\Passport\Http\Middleware\CreateFreshApiToken;

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        CreateFreshApiToken::class,
    ]);
})

[!WARNING]
You should ensure that the CreateFreshApiToken middleware is the last middleware listed in your middleware stack.

This middleware will attach a laravel_token cookie to your outgoing responses. This cookie contains an encrypted JWT that Passport will use to authenticate API requests from your JavaScript application. The JWT has a lifetime equal to your session.lifetime configuration value. Now, since the browser will automatically send the cookie with all subsequent requests, you may make requests to your application's API without explicitly passing an access token:

axios.get('/api/user')
    .then(response => {
        console.log(response.data);
    });

Customizing the Cookie Name

If needed, you can customize the laravel_token cookie's name using the Passport::cookie method. Typically, this method should be called from the boot method of your application's App\Providers\AppServiceProvider class:

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::cookie('custom_name');
}

CSRF Protection

When using this method of authentication, you will need to ensure a valid CSRF token header is included in your requests. The default Laravel JavaScript scaffolding included with the skeleton application and all starter kits includes an Axios instance, which will automatically use the encrypted XSRF-TOKEN cookie value to send an X-XSRF-TOKEN header on same-origin requests.

[!NOTE]
If you choose to send the X-CSRF-TOKEN header instead of X-XSRF-TOKEN, you will need to use the unencrypted token provided by csrf_token().

Events

Passport raises events when issuing access tokens and refresh tokens. You may listen for these events to prune or revoke other access tokens in your database:

| Event Name | | --- | | `Laravel\Passport\Events\AccessTokenCreated` | | `Laravel\Passport\Events\AccessTokenRevoked` | | `Laravel\Passport\Events\RefreshTokenCreated` |

Testing

Passport's actingAs method may be used to specify the currently authenticated user as well as its scopes. The first argument given to the actingAs method is the user instance and the second is an array of scopes that should be granted to the user's token:

use App\Models\User;
use Laravel\Passport\Passport;

test('orders can be created', function () {
    Passport::actingAs(
        User::factory()->create(),
        ['orders:create']
    );

    $response = $this->post('/api/orders');

    $response->assertStatus(201);
});

use App\Models\User;
use Laravel\Passport\Passport;

public function test_orders_can_be_created(): void
{
    Passport::actingAs(
        User::factory()->create(),
        ['orders:create']
    );

    $response = $this->post('/api/orders');

    $response->assertStatus(201);
}

Passport's actingAsClient method may be used to specify the currently authenticated client as well as its scopes. The first argument given to the actingAsClient method is the client instance and the second is an array of scopes that should be granted to the client's token:

use Laravel\Passport\Client;
use Laravel\Passport\Passport;

test('servers can be retrieved', function () {
    Passport::actingAsClient(
        Client::factory()->create(),
        ['servers:read']
    );

    $response = $this->get('/api/servers');

    $response->assertStatus(200);
});

use Laravel\Passport\Client;
use Laravel\Passport\Passport;

public function test_servers_can_be_retrieved(): void
{
    Passport::actingAsClient(
        Client::factory()->create(),
        ['servers:read']
    );

    $response = $this->get('/api/servers');

    $response->assertStatus(200);
}

Passport 12.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel Passport

简介

Passport 还是 Sanctum?

安装

部署 Passport

从环境变量加载密钥

升级 Passport

配置

令牌生命周期

覆盖默认模型（Overriding Default Models）

覆盖路由（Overriding Routes）

授权码授权流程（Authorization Code Grant）

客户端管理

第一方客户端

第三方客户端

请求令牌（Requesting Tokens）

重定向以进行授权

批准请求

将授权码转换为访问令牌

管理令牌

刷新令牌

撤销令牌

清理令牌

使用 PKCE 的授权码模式

创建客户端

请求令牌

Code Verifier 与 Code Challenge

重定向以进行授权

将授权码转换为访问令牌

设备授权许可（Device Authorization Grant）

创建设备授权许可客户端

请求令牌

请求设备代码（Device Code）

显示验证 URI 和用户代码

轮询令牌请求（Polling Token Request）

密码授权（Password Grant）

创建密码授权客户端

请求令牌

请求所有作用域（Scopes）

自定义用户提供者

自定义用户名字段

自定义密码验证

隐式授权（Implicit Grant）

客户端凭据授权（Client Credentials Grant）

获取令牌（Retrieving Tokens）

个人访问令牌（Personal Access Tokens）

创建个人访问客户端（Creating a Personal Access Client）

自定义用户提供者（Customizing the User Provider）

管理个人访问令牌（Managing Personal Access Tokens）

保护路由（Protecting Routes）

通过中间件（Via Middleware）

多个认证守卫（Multiple Authentication Guards）

传递访问令牌（Passing the Access Token）

Token Scopes

Defining Scopes

Default Scope

Assigning Scopes to Tokens

When Requesting Authorization Codes

When Issuing Personal Access Tokens

Checking Scopes

Check For All Scopes

Check for Any Scopes

Checking Scopes on a Token Instance

Additional Scope Methods

SPA Authentication

Customizing the Cookie Name

CSRF Protection

Events

Testing

推荐文章：

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

请登录

Passport

12.x

12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1