Laravel Sanctumのトークン認証とCookie認証を使い分ける

概要

Laravel Sanctum は「API トークン認証」と「SPA 認証(Cookie ベースのセッション認証)」という、性格の異なる 2 つの認証方式を 1 つのパッケージで提供しています。公式でも別物として説明されていますが、実装を始めると「どちらを使うべきか」「両方使えるのか」で迷いやすいところです。

この記事では、2 方式がそれぞれ何を解決するものなのか、内部で何が違うのか、どう使い分けるべきかを整理します。

環境

  • PHP 8.2 / Laravel 11 系
  • Laravel Sanctum 4 系

Laravel 11 からミドルウェア登録が bootstrap/app.php に移っているなど、バージョン差があるので手元の構成に読み替えてください。

2 つの認証方式の違い

トークン認証(API Token Authentication)

personal_access_tokens テーブルに保存したトークンを Authorization: Bearer <token> ヘッダーで送る方式です。ステートレスで、セッション・Cookie・CSRF の概念が登場しません。

  • 対象: サードパーティ連携、モバイルアプリ、外部システム、CLI、別ドメインのクライアント
  • 信頼境界: トークンを持っている者を認証する。同一オリジンを前提にしない
  • 失効: トークン単位で削除・失効できる。スコープ(能力)も付与できる

SPA 認証(Cookie ベースのセッション認証)

同一トップレベルドメインで動く自社フロントエンド向けです。実体は Laravel の通常のセッション認証で、Sanctum は「SPA からの XHR をセッションで認証してよいか」を判定する薄い層として働きます。

  • 対象: 自社の SPA(ファーストパーティ)
  • 信頼境界: 同一サイト・同一トップレベルドメイン。Cookie と CSRF 保護に依存する
  • 失効: セッションの破棄で即座にログアウトできる

トークン認証は「誰が持っているか」で認証するステートレス方式、SPA 認証は「ブラウザのセッション」で認証するステートフル方式。この違いがすべての判断の起点になります。

使い分けの判断基準

観点 トークン認証 SPA 認証(Cookie)
クライアント モバイル・外部連携・CLI 自社 SPA(同一ドメイン)
状態 ステートレス ステートフル
CSRF 対策 不要 必要
トークン保管 クライアント保持 HttpOnly Cookie
失効 レコード削除 セッション破棄
能力(abilities) 有効 無効(常に全能力)

おおまかな指針は次の通りです。

  • ブラウザ上で動く自社 SPA → SPA 認証(Cookie)。トークンを JS が保持しない分、XSS でトークンを抜かれるリスクを下げられる
  • モバイルアプリ・外部システム・別ドメイン → トークン認証。Cookie / CSRF の制約を受けず、失効管理もしやすい
  • 両方のクライアントがある → 併用する。auth:sanctum ガードは、Cookie セッションがあればセッション認証を、なければ Bearer トークンを見る順で解決する

実装例

トークン認証

$token = $user->createToken('mobile-app', ['posts:read', 'posts:write']);

return response()->json(['token' => $token->plainTextToken]);
// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn (Request $r) => $r->user());
    Route::post('/posts', [PostController::class, 'store'])
        ->middleware('abilities:posts:write');
});

失効は該当レコードを削除するだけです。

$request->user()->currentAccessToken()->delete(); // 今のトークン
$request->user()->tokens()->delete();             // 全トークン

SPA 認証

// config/sanctum.php
'stateful' => explode(',', env(
    'SANCTUM_STATEFUL_DOMAINS',
    'localhost,localhost:3000,127.0.0.1,app.example.com'
)),
# .env(値は環境に合わせる)
SESSION_DOMAIN=.example.com
SANCTUM_STATEFUL_DOMAINS=app.example.com
import axios from "axios";

const api = axios.create({
  baseURL: "https://api.example.com",
  withCredentials: true,
});

async function login(email: string, password: string) {
  // 先に CSRF Cookie を取得する
  await api.get("/sanctum/csrf-cookie");
  await api.post("/login", { email, password });
}

ルートは同じガードで守れます。Bearer トークンが無く Cookie セッションがあれば、Sanctum はセッション認証として解決します。

Route::middleware('auth:sanctum')->get('/user', fn (Request $r) => $r->user());

確認方法

  • トークン認証: ログイン API でトークンを取得し、Authorization: Bearer <token> を付けて 200 が返るか確認する。削除後に 401 になることも確認する
  • SPA 認証: DevTools で /sanctum/csrf-cookie 呼び出し後に XSRF-TOKEN / laravel_session Cookie がセットされ、POST 時に X-XSRF-TOKEN が乗っているかを見る。419 なら CSRF、401 なら stateful ドメインを疑う
  • 併用: 同一ルートに Bearer でも Cookie でも 200 が返ることを両経路で確認する

注意点

  • SPA 認証は同一トップレベルドメインが前提。クロスサイト構成ならトークン認証の方が素直です
  • トークンを localStorage に置くと XSS リスクがあります。SPA でトークンを採用するなら保管場所の設計を慎重に
  • personal_access_tokens は sanctum:prune-expired の定期実行で期限切れトークンを掃除します
  • abilities はトークン認証でのみ有効です

まとめ

  • Sanctum の 2 方式は「ステートレスなトークン」と「ステートフルな Cookie セッション」の別物
  • 自社 SPA(同一ドメイン)なら Cookie 認証、モバイル・外部連携・別ドメインならトークン認証が基本
  • 両方のクライアントがあれば auth:sanctum 一本で併用できる
  • つまずきの大半は SPA 認証の CSRF・Cookie ドメイン設定。401 と 419 を切り分けると原因に早く辿り着ける

「どちらが優れているか」ではなく「クライアントの信頼境界がどこにあるか」で選ぶと、判断がぶれなくなります。

\ 最新情報をチェック /

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。