Laravel Passport

• 簡介
  • Passport 或 Sanctum？
• 安裝
  • 部署 Passport
  • 升級 Passport
• 設定
  • 令牌生命週期
  • 覆寫預設模型
  • 覆寫路由
• 授權碼授權
  • 管理客戶端
  • 請求令牌
  • 管理令牌
  • 重新整理令牌
  • 撤銷令牌
  • 清除令牌
• 使用 PKCE 的授權碼授權
  • 建立客戶端
  • 請求令牌
• 裝置授權授權
  • 建立裝置碼授權客戶端
  • 請求令牌
• 密碼授權
  • 建立密碼授權客戶端
  • 請求令牌
  • 請求所有範圍
  • 自訂使用者提供者
  • 自訂使用者名稱欄位
  • 自訂密碼驗證
• 隱式授權
• 客戶端憑證授權
• 個人存取令牌
  • 建立個人存取客戶端
  • 自訂使用者提供者
  • 管理個人存取令牌
• 保護路由
  • 透過中介層
  • 傳遞存取令牌
• 令牌範圍
  • 定義範圍
  • 預設範圍
  • 將範圍分配給令牌
  • 檢查範圍
• SPA 認證
• 事件
• 測試

簡介

Laravel Passport 為您的 Laravel 應用程式提供完整的 OAuth2 伺服器實作，只需幾分鐘即可完成。Passport 基於由 Andy Millington 和 Simon Hamp 維護的 League OAuth2 server 建構。

[!NOTE] 本文件假設您已熟悉 OAuth2。如果您對 OAuth2 一無所悉，請先熟悉 OAuth2 的一般術語和功能，再繼續閱讀。

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',
    ],
],

部署 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));
}

[!WARNING] Passport 資料庫表格上的 expires_at 欄位是唯讀的，僅供顯示用途。發行令牌時，Passport 會將過期資訊儲存在已簽署和加密的令牌中。如果需要使令牌失效，應撤銷它。

覆寫預設模型

您可以自由擴展 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;
use Laravel\Passport\Passport;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::useTokenModel(Token::class);
    Passport::useRefreshTokenModel(RefreshToken::class);
    Passport::useAuthCodeModel(AuthCode::class);
    Passport::useClientModel(Client::class);
    Passport::useDeviceCodeModel(DeviceCode::class);
}

覆寫路由

有時候您可能希望自訂 Passport 定義的路由。要實現此目的，首先需要透過在您應用程式的 AppServiceProvider 的 register 方法中加入 Passport::ignoreRoutes 來忽略 Passport 註冊的路由：

use Laravel\Passport\Passport;

/**
 * Register any application services.
 */
public function register(): void
{
    Passport::ignoreRoutes();
}

然後，您可以將其路由檔案中定義的路由複製到您應用程式的 routes/web.php 檔案中，並根據您的需求進行修改：

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

授權碼授權

透過授權碼使用 OAuth2 是大多數開發者熟悉 OAuth2 的方式。使用授權碼時，客戶端應用程式會將使用者重新導向到您的伺服器，使用者將在那裡核准或拒絕向客戶端發行存取令牌的請求。

要開始，我們需要指示 Passport 如何返回我們的「授權」視圖。

所有授權視圖的渲染邏輯都可以使用 Laravel\Passport\Passport 類別提供的適當方法來自訂。通常，應從您應用程式的 App\Providers\AppServiceProvider 類別的 boot 方法中呼叫此方法：

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    // By providing a view name...
    Passport::authorizationView('auth.oauth.authorize');

    // By providing a closure...
    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 範本應包含一個向 passport.authorizations.approve 路由發出 POST 請求以核准授權的表單，以及一個向 passport.authorizations.deny 路由發出 DELETE 請求以拒絕授權的表單。passport.authorizations.approve 和 passport.authorizations.deny 路由需要 state、client_id 和 auth_token 欄位。

管理客戶端

需要與您應用程式的 API 互動的應用程式開發者，需要透過建立「客戶端」來向您的應用程式註冊他們的應用程式。通常，這包括提供他們應用程式的名稱和一個 URI，該 URI 在使用者核准授權請求後可用於重新導向。

第一方客戶端

建立客戶端最簡單的方法是使用 passport:client Artisan 命令。此命令可用於建立第一方客戶端或測試您的 OAuth2 功能。執行 passport:client 命令時，Passport 將提示您提供有關客戶端的更多資訊，並為您提供客戶端 ID 和密鑰：

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);

// Creating an OAuth app client that belongs to the given user...
$client = app(ClientRepository::class)->createAuthorizationCodeGrantClient(
    user: $user,
    name: 'Example App',
    redirectUris: ['https://third-party-app.com/callback'],
    confidential: false,
    enableDeviceFlow: true
);

// Retrieving all the OAuth app clients that belong to the user...
$clients = $user->oauthApps()->get();

createAuthorizationCodeGrantClient 方法返回 Laravel\Passport\Client 的實例。您可以將 $client->id 顯示為客戶端 ID，將 $client->plainSecret 顯示為客戶端密鑰給使用者。

請求令牌

重新導向以進行授權

建立客戶端後，開發者可以使用其客戶端 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", or "login"
    ]);

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

prompt 參數可用於指定 Passport 應用程式的認證行為。

如果 prompt 值為 none，Passport 將在使用者尚未透過 Passport 應用程式認證時擲出認證錯誤。如果值為 consent，Passport 將始終顯示授權核准畫面，即使先前已將所有範圍授予消費應用程式。當值為 login 時，Passport 應用程式將始終提示使用者重新登入應用程式，即使他們已有現有會話。

如果未提供 prompt 值，將僅在使用者先前未為請求的範圍授權存取消費應用程式時，才會提示使用者進行授權。

[!NOTE] 請記住，/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
{
    /**
     * Determine if the client should skip the authorization prompt.
     *
     * @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,
        'Invalid state value.'
    );

    $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 屬性包含存取令牌過期前的秒數。

[!NOTE] 與 /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);

// Retrieving all of the valid tokens for the user...
$tokens = $user->tokens()
    ->where('revoked', false)
    ->where('expires_at', '>', Date::now())
    ->get();

// Retrieving all the user's connections to third-party OAuth app clients...
$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', // Required for confidential clients only...
    '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);

// Revoke an access token...
$token->revoke();

// Revoke the token's refresh token...
$token->refreshToken?->revoke();

// Revoke all of the user's tokens...
User::find($userId)->tokens()->each(function (Token $token) {
    $token->revoke();
    $token->refreshToken?->revoke();
});

清除令牌

當令牌已被撤銷或過期時，您可能希望從資料庫中清除它們。Passport 附含的 passport:purge Artisan 命令可以為您完成此操作：

# Purge revoked and expired tokens, auth codes, and device codes...
php artisan passport:purge

# Only purge tokens expired for more than 6 hours...
php artisan passport:purge --hours=6

# Only purge revoked tokens, auth codes, and device codes...
php artisan passport:purge --revoked

# Only purge expired tokens, auth codes, and device codes...
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 的客戶端。您可以使用帶有 --public 選項的 passport:client Artisan 命令來完成此操作：

php artisan passport:client --public

請求令牌

Code Verifier 和 Code Challenge

由於此授權類型不提供客戶端密鑰，開發者需要產生 code verifier 和 code challenge 的組合來請求令牌。

code verifier 應為 43 到 128 個字元的隨機字串，包含字母、數字以及 "-"、"."、"_"、"~" 字元，如 RFC 7636 規範中所定義。

code challenge 應為 Base64 編碼的字串，使用 URL 和檔案名稱安全的字元。尾部的 '=' 字元應被移除，且不應存在換行、空格或其他額外字元。

$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();
});

裝置授權授權

OAuth2 裝置授權授權允許無瀏覽器或輸入受限的裝置（例如電視和遊戲機）透過交換「裝置碼」來獲得存取令牌。使用裝置流程時，裝置客戶端將指示使用者使用次要裝置（例如電腦或智慧型手機）連接到您的伺服器，他們將在那裡輸入提供的「使用者碼」並核准或拒絕存取請求。

要開始，我們需要指示 Passport 如何返回我們的「使用者碼」和「授權」視圖。

所有授權視圖的渲染邏輯都可以使用 Laravel\Passport\Passport 類別提供的適當方法來自訂。通常，應從您應用程式的 App\Providers\AppServiceProvider 類別的 boot 方法中呼叫此方法。

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    // By providing a view name...
    Passport::deviceUserCodeView('auth.oauth.device.user-code');
    Passport::deviceAuthorizationView('auth.oauth.device.authorize');

    // By providing a closure...
    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,
);

請求令牌

請求裝置碼

建立客戶端後，開發者可以使用其客戶端 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 路由時應等待的秒數，以避免速率限制錯誤。

[!NOTE] 請記住，/oauth/device/code 路由已由 Passport 定義。您不需要手動定義此路由。

顯示驗證 URI 和使用者碼

取得裝置碼請求後，消費裝置應指示使用者使用另一個裝置訪問提供的 verification_uri 並輸入 user_code 以核准授權請求。

輪詢令牌請求

由於使用者將使用單獨的裝置來授予（或拒絕）存取權限，消費裝置應輪詢您應用程式的 /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', // Required for confidential clients only...
        '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 屬性包含存取令牌過期前的秒數。

密碼授權

[!WARNING] 我們不再建議使用密碼授權令牌。相反，您應選擇目前被 OAuth2 Server 推薦的授權類型。

OAuth2 密碼授權允許您的其他第一方客戶端（例如行動應用程式）使用電子郵件地址/使用者名稱和密碼來獲得存取令牌。這使您能夠安全地向第一方客戶端發行存取令牌，無需要求使用者完成整個 OAuth2 授權碼重新導向流程。

要啟用密碼授權，請在您應用程式的 App\Providers\AppServiceProvider 類別的 boot 方法中呼叫 enablePasswordGrant 方法：

/**
 * Bootstrap any application services.
 */
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', // Required for confidential clients only...
    'username' => '[email protected]',
    'password' => 'my-password',
    'scope' => 'user:read orders:create',
]);

return $response->json();

[!NOTE] 請記住，存取令牌預設為長期有效。但是，如有需要，您可以自由配置最大存取令牌生命週期。

請求所有範圍

使用密碼授權或客戶端憑證授權時，您可能希望為您的應用程式支援的所有範圍授權令牌。您可以透過請求 * 範圍來完成此操作。如果您請求 * 範圍，則令牌實例上的 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' => '[email protected]',
    '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\Bridge\Client;
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

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

    /**
     * Find the user instance for the given username.
     */
    public function findForPassport(string $username, Client $client): 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;

    /**
     * Validate the password of the user for the Passport password grant.
     */
    public function validateForPassportPasswordGrant(string $password): bool
    {
        return Hash::check($password, $this->password);
    }
}

隱式授權

[!WARNING] 我們不再建議使用隱式授權令牌。相反，您應選擇目前被 OAuth2 Server 推薦的授權類型。

隱式授權類似於授權碼授權；然而，令牌是在不交換授權碼的情況下返回給客戶端的。此授權最常用於無法安全儲存客戶端憑證的 JavaScript 或行動應用程式。要啟用授權，請在您應用程式的 App\Providers\AppServiceProvider 類別的 boot 方法中呼叫 enableImplicitGrant 方法：

/**
 * Bootstrap any application services.
 */
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);
});

[!NOTE] 請記住，/oauth/authorize 路由已由 Passport 定義。您不需要手動定義此路由。

客戶端憑證授權

客戶端憑證授權適用於機器對機器的認證。例如，您可能在執行維護任務的排程工作中使用此授權。

在您的應用程式可以透過客戶端憑證授權發行令牌之前，您需要建立一個客戶端憑證授權客戶端。您可以使用 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) {
    // Access token is valid and the client is resource owner...
})->middleware(EnsureClientIsResourceOwner::class);

要將路由的存取限制為特定範圍，您可以向 using 方法提供所需範圍的列表：

Route::get('/orders', function (Request $request) {
    // Access token is valid, the client is resource owner, and has both "servers:read" and "servers:create" scopes...
})->middleware(EnsureClientIsResourceOwner::using('servers:read', 'servers:create'));

[!WARNING] 底層 OAuth2 伺服器將客戶端憑證令牌的 sub 聲明設為客戶端的標識符。預設情況下，Passport 使用 UUID 作為客戶端，因此不會與使用者的整數主鍵衝突。但是，如果您已將 Passport::$clientUuids 設為 false，客戶端憑證令牌可能會無意中解析出 ID 與客戶端 ID 相符的使用者。在這種情況下，使用此中介層無法保證傳入的令牌是客戶端憑證令牌。

檢索令牌

要使用此授權類型檢索令牌，請向 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'];

個人存取令牌

有時候，您的使用者可能希望在不經過典型的授權碼重新導向流程的情況下，自行發行存取令牌。允許使用者透過您應用程式的 UI 自行發行令牌，對於允許使用者試用您的 API 或作為發行存取令牌的更簡單方法可能很有用。

[!NOTE] 如果您的應用程式主要使用 Passport 發行個人存取令牌，請考慮使用 Laravel Sanctum，這是 Laravel 用於發行 API 存取令牌的輕量級第一方庫。

建立個人存取客戶端

在您的應用程式可以發行個人存取令牌之前，您需要建立一個個人存取客戶端。您可以透過執行帶有 --personal 選項的 passport:client Artisan 命令來完成此操作。如果您已執行過 passport:install 命令，則無需執行此命令：

php artisan passport:client --personal

自訂使用者提供者

如果您的應用程式使用多個認證使用者提供者，您可以透過在透過 artisan passport:client --personal 命令建立客戶端時提供 --provider 選項來指定個人存取授權客戶端使用哪個使用者提供者。給定的提供者名稱應與您應用程式的 config/auth.php 設定檔案中定義的有效提供者相符。然後您可以使用中介層保護您的路由，以確保只有來自守衛指定提供者的使用者被授權。

管理個人存取令牌

建立個人存取客戶端後，您可以使用 App\Models\User 模型實例上的 createToken 方法為給定使用者發行令牌。createToken 方法接受令牌名稱作為其第一個參數，以及可選的範圍陣列作為其第二個參數：

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

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

// Creating a token without scopes...
$token = $user->createToken('My Token')->accessToken;

// Creating a token with scopes...
$token = $user->createToken('My Token', ['user:read', 'orders:create'])->accessToken;

// Creating a token with all scopes...
$token = $user->createToken('My Token', ['*'])->accessToken;

// Retrieving all the valid personal access tokens that belong to the user...
$tokens = $user->tokens()
    ->with('client')
    ->where('revoked', false)
    ->where('expires_at', '>', Date::now())
    ->get()
    ->filter(fn (Token $token) => $token->client->hasGrantType('personal_access'));

保護路由

透過中介層

Passport 包含一個認證守衛，將在傳入的請求上驗證存取令牌。一旦您已配置 api 守衛使用 passport 驅動程式，您只需在任何需要有效存取令牌的路由上指定 auth:api 中介層：

Route::get('/user', function () {
    // Only API authenticated users may access this route...
})->middleware('auth:api');

[!WARNING] 如果您使用的是客戶端憑證授權，應使用 Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner 中介層來保護您的路由，而不是 auth:api 中介層。

多個認證守衛

如果您的應用程式認證不同類型的使用者（可能使用完全不同的 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');

[!NOTE] 有關使用多個使用者提供者與 Passport 的更多資訊，請參閱個人存取令牌文件和密碼授權文件。

傳遞存取令牌

呼叫受 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();

令牌範圍

範圍允許您的 API 客戶端在請求授權以存取帳戶時請求特定的權限集。例如，如果您正在建立電子商務應用程式，並非所有 API 消費者都需要下訂單的能力。相反，您可以允許消費者僅請求授權以存取訂單出貨狀態。換句話說，範圍允許您應用程式的使用者限制第三方應用程式可以代表他們執行的操作。

定義範圍

您可以使用您應用程式的 App\Providers\AppServiceProvider 類別的 boot 方法中的 Passport::tokensCan 方法來定義 API 的範圍。tokensCan 方法接受範圍名稱和範圍描述的陣列。範圍描述可以是您希望的任何內容，並將顯示在授權核准畫面上的使用者：

/**
 * 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',
    ]);
}

預設範圍

如果客戶端未請求任何特定範圍，您可以配置 Passport 伺服器使用 defaultScopes 方法將預設範圍附加到令牌。通常，應從您應用程式的 App\Providers\AppServiceProvider 類別的 boot 方法中呼叫此方法：

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',
]);

將範圍分配給令牌

請求授權碼時

使用授權碼授權請求存取令牌時，消費者應將其所需的範圍指定為 scope 查詢字串參數。scope 參數應為空格分隔的範圍列表：

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);
});

發行個人存取令牌時

如果您使用 App\Models\User 模型的 createToken 方法發行個人存取令牌，您可以將所需範圍的陣列作為第二個參數傳遞給該方法：

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

檢查範圍

Passport 包含兩個中介層，可用於驗證傳入的請求是否已使用被授予給定範圍的令牌進行認證。

檢查所有範圍

Laravel\Passport\Http\Middleware\CheckToken 中介層可分配給路由，以驗證傳入請求的存取令牌具有所有列出的範圍：

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')]);

檢查任何範圍

Laravel\Passport\Http\Middleware\CheckTokenForAnyScope 中介層可分配給路由，以驗證傳入請求的存取令牌具有至少一個列出的範圍：

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')]);

範圍屬性

如果您的應用程式使用控制器中介層屬性，您可以使用 Laravel\Passport\Attributes\AuthorizeToken 屬性作為 Passport 範圍中介層的便捷捷徑：

<?php

namespace App\Http\Controllers;

use Laravel\Passport\Attributes\AuthorizeToken;

#[AuthorizeToken('orders:read')]
#[AuthorizeToken('orders:create', only: ['store'])]
class OrderController
{
    #[AuthorizeToken(['orders:read', 'orders:create'], anyScope: true)]
    public function index()
    {
        // Access token has either "orders:read" or "orders:create" scope...
    }

    public function store()
    {
        // Access token has both "orders:read" and "orders:create" scopes...
    }
}

預設情況下，AuthorizeToken 屬性需要所有給定的範圍。如果您傳遞 anyScope: true，則當令牌具有至少一個給定範圍時，請求即被授權。

在令牌實例上檢查範圍

一旦存取令牌認證請求進入您的應用程式，您仍然可以使用已認證的 App\Models\User 實例上的 tokenCan 方法來檢查令牌是否具有給定範圍：

use Illuminate\Http\Request;

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

其他範圍方法

scopeIds 方法將返回所有已定義 ID / 名稱的陣列：

use Laravel\Passport\Passport;

Passport::scopeIds();

scopes 方法將返回所有已定義範圍的陣列，作為 Laravel\Passport\Scope 的實例：

Passport::scopes();

scopesFor 方法將返回與給定 ID / 名稱匹配的 Laravel\Passport\Scope 實例陣列：

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

您可以使用 hasScope 方法來判斷是否已定義給定範圍：

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

SPA 認證

建構 API 時，能夠從您的 JavaScript 應用程式消費您自己的 API 可能非常有用。這種 API 開發方法允許您自己的應用程式消費您與世界共享的同一個 API。相同的 API 可由您的 Web 應用程式、行動應用程式、第三方應用程式以及您可能在各種套件管理器上發佈的任何 SDK 消費。

通常，如果您希望從 JavaScript 應用程式消費您的 API，您需要手動將存取令牌傳送到應用程式，並在每個請求中將其傳遞給您的應用程式。然而，Passport 包含一個可以為您處理此問題的中介層。您只需將 CreateFreshApiToken 中介層附加到您應用程式的 bootstrap/app.php 檔案中的 web 中介層群組：

use Laravel\Passport\Http\Middleware\CreateFreshApiToken;

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

[!WARNING] 您應確保 CreateFreshApiToken 中介層是中介層堆疊中列出的最後一個中介層。

此中介層將在您的外發回應上附加一個 laravel_token cookie。此 cookie 包含一個加密的 JWT，Passport 將使用它來認證來自 JavaScript 應用程式的 API 請求。JWT 的生命週期等於您的 session.lifetime 設定值。現在，由於瀏覽器將自動在所有後續請求中發送 cookie，您可以無需明確傳遞存取令牌即可對應用程式的 API 發出請求：

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

自訂 Cookie 名稱

如有需要，您可以使用 Passport::cookie 方法自訂 laravel_token cookie 的名稱。通常，應從您應用程式的 App\Providers\AppServiceProvider 類別的 boot 方法中呼叫此方法：

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

CSRF 保護

使用此認證方法時，您需要確保請求中包含有效的 CSRF 令牌標頭。骨架應用程式和所有入門套件中附含的預設 JavaScript 腳手架包含一個 Axios 實例，該實例將自動使用加密的 XSRF-TOKEN cookie 值在同源請求上傳送 X-XSRF-TOKEN 標頭。

[!NOTE] 如果您選擇傳送 X-CSRF-TOKEN 標頭而不是 X-XSRF-TOKEN，則需要使用 csrf_token() 提供的未加密令牌。

事件

Passport 在發行存取令牌和重新整理令牌時會觸發事件。您可以監聽這些事件來修剪或撤銷資料庫中的其他存取令牌：

測試

Passport 的 actingAs 方法可用於指定目前認證的使用者及其範圍。傳遞給 actingAs 方法的第一個參數是使用者實例，第二個是應授予使用者令牌的範圍陣列：

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 的 actingAsClient 方法可用於指定目前認證的客戶端及其範圍。傳遞給 actingAsClient 方法的第一個參數是客戶端實例，第二個是應授予客戶端令牌的範圍陣列：

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);
}