laravel-auth

Laravel 13 の認証・認可エコシステムを網羅しています。Sanctum （API トークン、SPA 認証）、Passport（OAuth2 サーバー）、Fortify（カスタム UI に対応したヘッドレス認証）、Socialite（ソーシャルログイン）、スターターキット、ポリシーとゲート、 メール認証、パスワードリセット、セッション管理、CSRF / PreventRequestForgery、暗号化、ハッシュ化を扱います。認証の FuseCore モジュラープロジェクト統合パターン（User モジュール、ポリシーによるモジュール間認可）も含みます。

Laravel の認証と認可

エージェントのワークフロー（必須）

実装を始める前に、必ず 3 つのエージェントを並行して起動してください。それぞれ name を指定して Agent を 1 回呼び出します。

1. fuse-ai-pilot:explore-codebase - 既存の認証設定、ガード、ポリシーを確認します
2. fuse-ai-pilot:research-expert - Context7 を使用して最新の Laravel 13 認証ドキュメントを確認します
3. mcp__context7__query-docs - 特定のパターン（Sanctum、Passport など）を照会します

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

Laravel は、認証と認可の包括的なエコシステムを提供します。ニーズに応じて選択してください。

パッケージ	最適な用途	複雑さ
スターターキット	新規プロジェクト、迅速なセットアップ	低
Sanctum	API トークン、SPA 認証	低
Fortify	カスタム UI、ヘッドレスバックエンド	中
Passport	OAuth2 サーバー、サードパーティーアクセス	高
Socialite	ソーシャルログイン（Google、GitHub）	低

---

重要なルール

1. モデルの認可にはポリシーを使用する - インラインの if チェックは使用しません
2. パスワードは必ずハッシュ化する - Hash::make() または 'hashed' キャストを使用します
3. ログイン後にセッションを再生成する - セッション固定攻撃を防ぎます
4. 本番環境では HTTPS を使用する - セキュア Cookie に必須です
5. トークンの権限を定義する - 最小権限の原則に従います

---

アーキテクチャ

app/
├── Http/
│   ├── Controllers/
│   │   └── Auth/              ← Auth controllers (if manual)
│   └── Middleware/
│       └── Authenticate.php   ← Redirects unauthenticated
├── Models/
│   └── User.php               ← HasApiTokens trait (Sanctum)
├── Policies/                  ← Authorization policies
│   └── PostPolicy.php
├── Providers/
│   └── AppServiceProvider.php ← Gate definitions
└── Actions/
    └── Fortify/               ← Fortify actions (if used)
        ├── CreateNewUser.php
        └── ResetUserPassword.php

config/
├── auth.php                   ← Guards & providers
├── sanctum.php                ← API token config
└── fortify.php                ← Fortify features

---

FuseCore との統合

FuseCore プロジェクトで作業する場合、認証はモジュール構造に従います。

FuseCore/
├── Core/                      # Infrastructure (priority 0)
│   └── App/Contracts/
│       └── AuthServiceInterface.php  ← Auth contract
│
├── User/                      # Auth module (existing)
│   ├── App/
│   │   ├── Models/User.php    ← HasApiTokens trait
│   │   ├── Http/
│   │   │   ├── Controllers/
│   │   │   │   ├── AuthController.php
│   │   │   │   └── TokenController.php
│   │   │   ├── Requests/
│   │   │   │   ├── LoginRequest.php
│   │   │   │   └── RegisterRequest.php
│   │   │   └── Resources/UserResource.php
│   │   ├── Policies/UserPolicy.php
│   │   └── Services/AuthService.php
│   ├── Config/
│   │   └── sanctum.php        ← Sanctum config (module-level)
│   ├── Database/Migrations/
│   ├── Routes/api.php         ← Auth routes
│   └── module.json            # dependencies: []
│
└── {YourModule}/              # Depends on User module
    ├── App/Policies/          ← Module-specific policies
    └── module.json            # dependencies: ["User"]

FuseCore 認証チェックリスト

• 認証コードは /FuseCore/User/ モジュールに配置する
• ポリシーはモジュールの /App/Policies/ に配置する
• 認証ルートは /FuseCore/User/Routes/api.php に配置する
• Sanctum の設定は /FuseCore/User/Config/sanctum.php に配置する
• 他のモジュールの module.json に "User" 依存関係を宣言する
• モジュールのルートで auth:sanctum ミドルウェアを使用する

モジュール間認可

// In FuseCore/{Module}/Routes/api.php
Route::middleware(['api', 'auth:sanctum'])->group(function () {
    Route::apiResource('posts', PostController::class);
});

// In FuseCore/{Module}/App/Http/Controllers/PostController.php
public function update(UpdatePostRequest $request, Post $post)
{
    $this->authorize('update', $post);  // Uses PostPolicy
    // ...
}

→ モジュールのパターン全体については、fusecore skill を参照してください。

---

選択ガイド

認証方式

Need auth scaffolding? → Starter Kit
├── Yes → Use React/Vue/Livewire starter kit
└── No → Building custom frontend?
    ├── Yes → Use Fortify (headless)
    └── No → API only?
        ├── Yes → Sanctum (tokens)
        └── No → Session-based

トークンの種類

Third-party apps need access? → Passport (OAuth2)
├── No → Mobile app?
│   ├── Yes → Sanctum API tokens
│   └── No → SPA on same domain?
│       ├── Yes → Sanctum SPA auth (cookies)
│       └── No → Sanctum API tokens

---

主な概念

概念	説明	参照先
ガード	ユーザーの認証方法（セッション、トークン）を定義します	authentication.md
プロバイダー	ユーザーの取得元（データベース）を定義します	authentication.md
ゲート	単純なチェックに使うクロージャーベースの認可です	authorization.md
ポリシー	モデルに関連付けられたクラスベースの認可です	authorization.md
権限	トークンの権限（Sanctum／Passport のスコープ）です	sanctum.md

---

リファレンスガイド

概念（理由とアーキテクチャ）

トピック	リファレンス	参照するタイミング
認証	authentication.md	ガード、プロバイダー、ログインフロー
認可	authorization.md	ゲートとポリシー、アクセス制御
Sanctum	sanctum.md	API トークン、SPA 認証
Passport	passport.md	OAuth2 サーバー、サードパーティーアクセス
Fortify	fortify.md	ヘッドレス認証、2FA
Socialite	socialite.md	ソーシャルログインプロバイダー
スターターキット	starter-kits.md	認証のスキャフォールディング
メール認証	verification.md	MustVerifyEmail、verified ミドルウェア
パスワードリセット	passwords.md	パスワードを忘れた場合のフロー
セッション	session.md	セッションドライバー、フラッシュデータ
CSRF	csrf.md	フォーム保護、AJAX トークン
暗号化	encryption.md	データの暗号化（パスワードを除く）
ハッシュ化	hashing.md	パスワードのハッシュ化

テンプレート（完全なコード）

テンプレート	使用する場面
LoginController.php.md	手動で認証コントローラーを作成する場合
GatesAndPolicies.php.md	ゲートとポリシーの例
PostPolicy.php.md	before フィルターを含む完全なポリシークラス
sanctum-setup.md	Sanctum の設定とテスト
PassportSetup.php.md	OAuth2 サーバーのセットアップ
FortifySetup.php.md	Fortify の設定と 2FA
SocialiteController.php.md	ソーシャルログインとテスト
PasswordResetController.php.md	パスワードリセットのフロー

---

ベストプラクティス

DO

• 新しいプロジェクトではスターターキットを使用する
• すべてのモデルにポリシーを定義する
• トークンの有効期限を設定する
• ログイン試行をレート制限する
• 機密性の高い操作には verified ミドルウェアを使用する
• 期限切れのトークンを定期的に削除する

DON'T

• 平文のパスワードを保存しない
• ログイン時のセッション再生成を省略しない
• Sanctum で十分な場合に Passport を使用しない
• 期限切れのトークンの削除を忘れない
• 本番環境で HTTPS を無視しない
• 認可ロジックをコントローラーに記述しない

---

Laravel 13 に関する注意事項

PreventRequestForgery（旧 VerifyCsrfToken）

Laravel 13 では VerifyCsrfToken の名前が PreventRequestForgery に変更されます。このミドルウェアは、Sec-Fetch-Site ヘッダーを使ったオリジンチェックを追加し、ステートフルルートでのクロスオリジン CSRF 攻撃をブロックします。オリジンチェックに失敗した場合は、CSRF トークンを使用します。

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->preventRequestForgery(except: ['stripe/*', 'webhook/*']);
    // $middleware->preventRequestForgery(originOnly: true);    // no token fallback
    // $middleware->preventRequestForgery(allowSameSite: true); // accept same-site
})

• すべての VerifyCsrfToken::class の参照を PreventRequestForgery::class に移行します（VerifyCsrfToken／ValidateCsrfToken は非推奨のエイリアスとして引き続き使用できます）
• 除外：preventRequestForgery(except: [...])
• ステートレス API（Sanctum トークン）には影響しません