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_sessionCookie がセットされ、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 を切り分けると原因に早く辿り着ける
「どちらが優れているか」ではなく「クライアントの信頼境界がどこにあるか」で選ぶと、判断がぶれなくなります。
