Laravel Sanctum（API token 認證）

什麼是 Sanctum

Laravel Sanctum 是為 SPA（單頁應用程式）、行動應用程式與簡潔 API 而設計的輕量認證套件。無需複雜的 OAuth 知識，即可為每位使用者發放並管理多個 API token。 Sanctum 解決兩個問題：

認證模式	機制	主要用途
API token 認證	`Authorization: Bearer <token>` header	行動應用、第三方整合
SPA 認證	Session Cookie + CSRF 保護	自家前端（Vue/React 等）

自家 SPA 呼叫 API 時使用 SPA 認證。行動應用或第三方使用 API 時使用 API token 認證。也可以只使用其中一種。

與 Passport 的分工

	Sanctum	Passport
複雜度	簡潔	完整功能 OAuth2
適用用途	自家 SPA、行動應用	對外部應用作為 OAuth provider
Token 類型	Personal Access Token	OAuth2 Access Token

若需對外部服務作為 OAuth2 provider，請選 Passport；但多數應用程式 Sanctum 就足夠。

安裝與設定

安裝

只要執行 install:api Artisan 指令即可設定 Sanctum。

php artisan install:api

此指令會自動執行以下事項：

安裝 laravel/sanctum 套件
發布 personal_access_tokens 資料表的 migration 檔
執行 migration

加入 HasApiTokens trait

在 User model 加入 HasApiTokens trait。

// app/Models/User.php

use Laravel\Sanctum\HasApiTokens;

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

如此即可使用 $user->createToken()、$user->tokens 等方法。

API Token 認證

Token 流程

發行 Token

以 createToken() 方法發行 token。從 plainTextToken 屬性取得明文 token 值。明文 token 不會保存到資料庫，因此發行後必須立即回傳給使用者。

use Illuminate\Http\Request;

Route::post('/tokens/create', function (Request $request) {
    $token = $request->user()->createToken($request->token_name);

    return ['token' => $token->plainTextToken];
})->middleware('auth');

資料庫中儲存的是以 SHA-256 雜湊後的 token。

設定 Scope（Ability）

為 token 賦予 ability（scope），可限制該 token 能執行的操作。

// 發行帶 scope 的 token
$token = $user->createToken('mobile-app', ['server:update', 'server:read']);

return $token->plainTextToken;

處理請求時，檢查 token 的 scope。

if ($request->user()->tokenCan('server:update')) {
    // 執行更新操作
}

if ($request->user()->tokenCant('server:update')) {
    abort(403);
}

以 Middleware 檢查 scope

在 bootstrap/app.php 註冊 middleware 別名：

use Laravel\Sanctum\Http\Middleware\CheckAbilities;
use Laravel\Sanctum\Http\Middleware\CheckForAnyAbility;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'abilities' => CheckAbilities::class,  // 需擁有所有 ability
        'ability'   => CheckForAnyAbility::class, // 只要擁有其中之一
    ]);
})

在路由套用 middleware。

// 只允許同時擁有 check-status 與 place-orders 的 token
Route::get('/orders', function () {
    // ...
})->middleware(['auth:sanctum', 'abilities:check-status,place-orders']);

// 允許擁有 check-status 或 place-orders 其中之一的 token
Route::get('/orders', function () {
    // ...
})->middleware(['auth:sanctum', 'ability:check-status,place-orders']);

Token 的有效期限

預設 Sanctum token 無有效期限。可透過 config/sanctum.php 的 expiration 選項設定以分鐘為單位的有效期限。

// config/sanctum.php
'expiration' => 525600, // 365 天（分鐘）

也可個別為每個 token 指定有效期限。

$token = $user->createToken(
    'token-name',
    ['*'],
    now()->addWeeks(1) // 1 週後過期
)->plainTextToken;

若有設定有效期限，請安排定期刪除過期 token 的排程。

use Illuminate\Support\Facades\Schedule;

Schedule::command('sanctum:prune-expired --hours=24')->daily();

使 Token 失效

// 刪除所有 token
$user->tokens()->delete();

// 刪除目前請求所使用的 token
$request->user()->currentAccessToken()->delete();

// 刪除特定 token
$user->tokens()->where('id', $tokenId)->delete();

SPA 認證

SPA 認證使用 session Cookie，不需要發行或管理 token。適合自家前端（Vue、React、Next.js 等）呼叫 API 的情境。

使用 SPA 認證時，SPA 與 API 需共用相同的 top-level domain（子網域可以不同）。此外，請求必須包含 Accept: application/json header 以及 Referer 或 Origin header。

啟用 Sanctum middleware

在 bootstrap/app.php 啟用 statefulApi() middleware。

->withMiddleware(function (Middleware $middleware): void {
    $middleware->statefulApi();
})

設定第一方網域

在 config/sanctum.php 的 stateful 選項設定 SPA 的網域。

// config/sanctum.php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
    Sanctum::currentApplicationUrlWithPort()
))),

設定 CORS

若從其他子網域呼叫 API，需要設定 CORS。

php artisan config:publish cors

在 config/cors.php 將 supports_credentials 設為 true。

// config/cors.php
'supports_credentials' => true,

前端的 axios 也需要設定。

// resources/js/bootstrap.js
axios.defaults.withCredentials = true;
axios.defaults.withXSRFToken = true;

Session Cookie 的網域設定也不可忘。

// config/session.php
'domain' => '.example.com', // 開頭加上點

來自 SPA 的認證流程

取得 CSRF cookie

在登入前呼叫 /sanctum/csrf-cookie 端點初始化 CSRF 保護。

await axios.get('/sanctum/csrf-cookie');

送出登入請求

向 /login 端點送出 POST 請求。

await axios.post('/login', {
    email: '[email protected]',
    password: 'password',
});

送出已認證的請求

登入後的請求會自動以 session Cookie 認證。

const response = await axios.get('/api/user');
console.log(response.data); // 已認證使用者資訊

保護已認證的路由

將 auth:sanctum middleware 套用於路由，未認證的請求會收到 401 Unauthorized。API token 認證與 SPA 認證都可由這一個 middleware 處理。

use Illuminate\Http\Request;

// 保護單一路由
Route::get('/user', function (Request $request) {
    return $request->user();
})->middleware('auth:sanctum');

// 保護路由群組
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/profile', [ProfileController::class, 'show']);
    Route::put('/profile', [ProfileController::class, 'update']);
    Route::get('/posts', [PostController::class, 'index']);
});

實用範例：登入 API 與 token 回傳

以下是為行動應用實作 API token 認證的範例。

建立登入端點

// routes/api.php

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

Route::post('/sanctum/token', function (Request $request) {
    $request->validate([
        'email'       => ['required', 'email'],
        'password'    => ['required'],
        'device_name' => ['required', 'string'],
    ]);

    $user = User::where('email', $request->email)->first();

    if (! $user || ! Hash::check($request->password, $user->password)) {
        throw ValidationException::withMessages([
            'email' => ['所提供的認證資訊不正確。'],
        ]);
    }

    return response()->json([
        'token' => $user->createToken($request->device_name)->plainTextToken,
    ]);
});

建立已認證路由

// routes/api.php

Route::middleware('auth:sanctum')->group(function () {
    // 回傳目前使用者資訊
    Route::get('/user', function (Request $request) {
        return $request->user();
    });

    // 使目前 token 失效並登出
    Route::post('/logout', function (Request $request) {
        $request->user()->currentAccessToken()->delete();

        return response()->json(['message' => '已登出。']);
    });

    // 從所有裝置登出
    Route::post('/logout/all', function (Request $request) {
        $request->user()->tokens()->delete();

        return response()->json(['message' => '已從所有裝置登出。']);
    });
});

從用戶端送出請求

// 登入
const { data } = await axios.post('/api/sanctum/token', {
    email: '[email protected]',
    password: 'password',
    device_name: 'My iPhone',
});

const token = data.token;

// 已認證的請求
const response = await axios.get('/api/user', {
    headers: {
        Authorization: `Bearer ${token}`,
    },
});

測試

在 Sanctum 的測試中，使用 Sanctum::actingAs() 認證使用者並指定授予的 ability。

Pest
PHPUnit

use App\Models\User;
use Laravel\Sanctum\Sanctum;

test('可以取得任務清單', function () {
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );

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

    $response->assertOk();
});

test('以具備所有 ability 的 token 可存取', function () {
    Sanctum::actingAs(
        User::factory()->create(),
        ['*']
    );

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

    $response->assertOk();
});

use App\Models\User;
use Laravel\Sanctum\Sanctum;

public function test_task_list_can_be_retrieved(): void
{
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );

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

    $response->assertOk();
}

總結

安裝步驟確認

# 安裝 Sanctum 並執行 migration
php artisan install:api

在 User model 加入 HasApiTokens trait：

use Laravel\Sanctum\HasApiTokens;

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

常用 API 總覽

// 發行 token
$token = $user->createToken('token-name')->plainTextToken;

// 發行帶 scope 的 token
$token = $user->createToken('token-name', ['read', 'write'])->plainTextToken;

// 確認 scope
$user->tokenCan('read');   // true/false
$user->tokenCant('write'); // true/false

// 使 token 失效
$user->tokens()->delete();                        // 所有 token
$request->user()->currentAccessToken()->delete(); // 目前 token
$user->tokens()->where('id', $id)->delete();      // 特定 token

API token 認證 vs SPA 認證選擇

API token 認證：行動應用、第三方、CLI 工具等從沒有 session 的用戶端使用時。
SPA 認證：自家 Vue/React/Next.js 前端等，從相同網域（或子網域）上的 SPA 使用時。更安全且無需管理 token。

​什麼是 Sanctum

​與 Passport 的分工

​安裝與設定

​安裝

​加入 HasApiTokens trait

​API Token 認證

​Token 流程

​發行 Token

​設定 Scope（Ability）

​以 Middleware 檢查 scope

​Token 的有效期限

​使 Token 失效

​SPA 認證

​啟用 Sanctum middleware

​設定第一方網域

​設定 CORS

​來自 SPA 的認證流程

​保護已認證的路由

​實用範例：登入 API 與 token 回傳

​測試

​總結

什麼是 Sanctum

與 Passport 的分工

安裝與設定

安裝

加入 HasApiTokens trait

API Token 認證

Token 流程

發行 Token

設定 Scope（Ability）

以 Middleware 檢查 scope

Token 的有效期限

使 Token 失效

SPA 認證

啟用 Sanctum middleware

設定第一方網域

設定 CORS

來自 SPA 的認證流程

保護已認證的路由

實用範例：登入 API 與 token 回傳

測試

總結