Laravel × Next.js で「アクセストークン + リフレッシュトークン」な認証を実装した話

⚙️ この記事は AI（ChatGPT）による自動生成および編集支援のもとで作成されています。
内容はできる限り正確に記述していますが、参考情報としてご覧ください。
使用ツール：ChatGPT（OpenAI / GPT-5 モデル）

---

学習日報アプリを作る中で、Laravel（API）× Next.js（フロント） の構成で認証まわりを実装しました。

最初は「とりあえずログインできればいいでしょ」と思っていたのですが、

• クロスドメイン（localhost:8080 と localhost:3000）
• Laravel Sanctum
• アクセストークン + リフレッシュトークン
• Next.js App Router（app/api/*）での API ルート

が絡んでくると、「あれ？ /me が 401…」「トークン更新したのにフロントに反映されない…」 みたいなハマりポイントが大量発生しました。

この記事では、最終的に落ち着いた構成と、ハマりどころをまとめておきます。

---

ゴールのイメージ

やりたいことは SPA でよくある構成です。

1. ユーザーがログインフォームからメール + パスワードを送る
2. バックエンド（Laravel）が
   • 短命な access_token（例: 15分）を発行
   • 長めに生きる refresh_token を発行し、「HttpOnly Cookie」としてブラウザにセット
3. フロント（Next.js）は
   • access_token をメモリ（or Redux 等）に保持し、Authorization: Bearer ... で API を叩く
   • 401（期限切れ）が返ってきたら /refresh でトークンを再発行
4. /refresh では
   • ブラウザにある refresh_token Cookie を Laravel に送り
   • 検証 OK なら新しい access_token を返す
5. ログアウトしたら
   • Laravel 側でトークンを無効化
   • Cookie も削除

図にするとこんな感じのイメージです（雑テキスト図）：

[Browser] --(login)--> [Next.js] --(proxy)--> [Laravel API]
    ↑                                           ↓
 access_token (JS)                        DB の personal_access_tokens
 refresh_token (HttpOnly Cookie)

---

バックエンド（Laravel）側の設計

使用技術

• PHP 8.x
• Laravel
• Laravel Sanctum
• personal_access_tokens テーブルを使ったトークン管理

ルーティング

routes/api.php（実際は Route::prefix('v1') などでまとめても OK）:

<?php

use App\Http\Controllers\Api\AuthController;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')->group(function () {
    /**
     * ヘルスチェック
     */
    Route::get('/health', function () {
        return response()->json(['status' => 'ok']);
    });

    /**
     * 認証系（非認証）
     */
    Route::post('/login', [AuthController::class, 'login']);
    Route::post('/refresh', [AuthController::class, 'refresh']);

    /**
     * 認証必須
     */
    Route::middleware('auth:sanctum')->group(function () {
        Route::post('/logout', [AuthController::class, 'logout']);
        Route::get('/me', [AuthController::class, 'me']);
    });
});

ガード / Sanctum 設定

config/auth.php では API ガードを Sanctum にしておきます。

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'sanctum',
        'provider' => 'users',
    ],
],

config/sanctum.php の guard は基本的に ['web'] のままで OK。
API 側でトークン認証する時は auth('api') / auth:sanctum を使うイメージです。

---

login: アクセス / リフレッシュトークン発行

ざっくりとしたイメージコードです（Service 層を噛ませても OK）。

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\LoginRequest;
use App\Models\User;
use Illuminate\Support\Facades\Hash;

class AuthController extends Controller
{
    public function login(LoginRequest $request)
    {
        $user = User::where('email', $request->email)->first();

        if (! $user || ! Hash::check($request->password, $user->password)) {
            return response()->json([
                'status' => 'error',
                'message' => '認証に失敗しました。',
            ], 401);
        }

        // アクセストークン（短命）
        $accessToken = $user->createToken(
            name: 'access-token',
            abilities: ['access-api'],
            expiresAt: now()->addMinutes(15),
        );

        // リフレッシュトークン（長め）
        $refreshToken = $user->createToken(
            name: 'refresh-token',
            abilities: ['refresh-token'],
            expiresAt: now()->addDays(30),
        );

        // HttpOnly Cookie にリフレッシュトークンをセット
        $refreshCookie = cookie(
            name: 'refresh_token',
            value: $refreshToken->plainTextToken,
            minutes: 60 * 24 * 30,
            path: '/',
            domain: null, // 本番ではサブドメインに合わせる
            secure: false,   // 本番では true + https
            httpOnly: true,
            sameSite: 'lax',
        );

        return response()->json([
            'status' => 'success',
            'data' => [
                'member' => $user,
                'access_token' => $accessToken->plainTextToken,
            ],
        ])->cookie($refreshCookie);
    }
}

ポイントは、

• access_token → JSON で返す（JSから見える）
• refresh_token → HttpOnly Cookie に入れる（JS から見えない）

に分けているところです。

---

refresh: Cookie からリフレッシュトークンを取り出して検証

refresh では、ブラウザから送られてきた Cookie を元に、トークンを検証して新しい access_token を返します。

use Illuminate\Http\Request;

class AuthController extends Controller
{
    public function refresh(Request $request)
    {
        $refreshTokenPlain = $request->cookie('refresh_token');

        if (! $refreshTokenPlain) {
            return response()->json([
                'status' => 'error',
                'message' => 'リフレッシュトークンがありません。',
            ], 401);
        }

        // plainTextToken から token レコードを探すロジック（例）
        // 実際には hash 化されている token カラムとの照合が必要
        $token = app(TokenRepository::class)->findRefreshToken($refreshTokenPlain);

        if (! $token || ! $token->isRefreshTokenValid()) {
            return response()->json([
                'status' => 'error',
                'message' => 'リフレッシュトークンが無効です。',
            ], 401);
        }

        $user = $token->tokenable;

        // アクセストークンを再発行（必要ならリフレッシュトークンもローテーション）
        $newAccessToken = $user->createToken(
            name: 'access-token',
            abilities: ['access-api'],
            expiresAt: now()->addMinutes(15),
        );

        return response()->json([
            'status' => 'success',
            'data' => [
                'member' => $user,
                'access_token' => $newAccessToken->plainTextToken,
            ],
        ]);
    }
}

※ TokenRepository::findRefreshToken() や isRefreshTokenValid() は、
personal_access_tokens の実装に合わせてよしなに作るイメージです。

---

logout: トークン無効化 & Cookie 削除

use Illuminate\Http\Request;

class AuthController extends Controller
{
    public function logout(Request $request)
    {
        /** @var \App\Models\User $user */
        $user = $request->user();

        // 現在のアクセストークンを無効化
        $user->currentAccessToken()?->delete();

        // リフレッシュトークンもまとめて無効化（用途に応じて）
        $user->tokens()->where('name', 'refresh-token')->delete();

        // Cookie 削除
        $forgetCookie = cookie()->forget('refresh_token');

        return response()->json([
            'status' => 'success',
            'message' => 'ログアウトしました。',
        ])->cookie($forgetCookie);
    }
}

---

フロントエンド（Next.js）側の構成

やりたいこと

• 認証付き API を叩くときは毎回 Authorization: Bearer ${accessToken} をつける
• 初期表示時（ページリロード時）は /me を叩いてログイン状態を確認
  • 401 が返ったら /refresh → /me の順番で叩き直す
• リフレッシュトークンは Cookie にあるので、Next.js の API ルートを経由して Laravel に渡す

---

Axios クライアント（例）

lib/api/client.ts のような場所にまとめておきます。

// lib/api/client.ts
import axios from "axios";

const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL ?? "http://localhost:8080/api/v1",
  withCredentials: true, // Cookie を送る
});

export function setAccessToken(token: string | null) {
  if (token) {
    apiClient.defaults.headers.common["Authorization"] = `Bearer ${token}`;
  } else {
    delete apiClient.defaults.headers.common["Authorization"];
  }
}

export const apiGet = apiClient.get;
export const apiPost = apiClient.post;
// ... 必要に応じて export

ログイン成功時に setAccessToken(access_token) を呼んでおけば、
以降のリクエストに自動で Authorization が付くようになります。

---

Next.js の /api/refresh ルートで Cookie を Laravel に中継

ここが一番ハマりどころでした。

• フロント（ブラウザ）から直接 http://localhost:8080/api/v1/refresh を叩くと CORS と Cookie でごちゃごちゃしやすい
• なので **Next.js 側に /api/refresh を作り、「サーバーサイドから Laravel を叩く」**ようにしました

app/api/refresh/route.ts:

// app/api/refresh/route.ts
import { NextResponse } from "next/server";
import { cookies } from "next/headers";

export async function POST() {
  try {
    const cookieStore = cookies();

    // Laravel に送るために "name=value; name2=value2" 形式の Cookie 文字列にする
    const cookieHeader = cookieStore
      .getAll()
      .map((c) => `${c.name}=${c.value}`)
      .join("; ");

    const backendResponse = await fetch("http://localhost:8080/api/v1/refresh", {
      method: "POST",
      headers: {
        Cookie: cookieHeader,
      },
      credentials: "include",
    });

    const data = await backendResponse.json();

    return NextResponse.json(data, {
      status: backendResponse.status,
    });
  } catch (error) {
    console.error("Refresh API error:", error);
    return NextResponse.json(
      {
        status: "error",
        message: "refresh failed",
      },
      { status: 500 },
    );
  }
}

ポイント：

• cookies() で ブラウザの Cookie をサーバー側で取得している
• それを手動で Cookie ヘッダーに詰めて Laravel に渡している
• Laravel 側はいつも通り request()->cookie('refresh_token') で参照できる

---

認証初期化フロー（/me → /refresh → /me）

React 側では、useEffect でこんな流れにしました（あくまでイメージコードです）。

// hooks/useAuthInitializer.ts
"use client";

import { useEffect, useState } from "react";
import { apiGet } from "@/lib/api/client";
import { setAccessToken } from "@/lib/api/client";

type Member = {
  uuid: string;
  name: string;
  email: string;
  // ...他のフィールド
};

export function useAuthInitializer() {
  const [member, setMember] = useState<Member | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const init = async () => {
      try {
        // ① まず /me を叩いてみる
        const meRes = await apiGet("/me");
        const meData = meRes.data.data.member as Member;

        setMember(meData);
      } catch (err: any) {
        // ② /me が 401 なら /refresh → /me の順で再トライ
        if (err?.response?.status === 401) {
          try {
            const refreshRes = await fetch("/api/refresh", {
              method: "POST",
            });

            const refreshJson = await refreshRes.json();

            if (refreshRes.ok && refreshJson?.data?.access_token) {
              const newAccessToken = refreshJson.data.access_token as string;
              const newMember = refreshJson.data.member as Member;

              setAccessToken(newAccessToken);
              setMember(newMember);
            } else {
              // refresh もダメなら未ログイン扱い
              setMember(null);
            }
          } catch (refreshError) {
            console.error("refresh error", refreshError);
            setMember(null);
          }
        } else {
          console.error("me error", err);
          setMember(null);
        }
      } finally {
        setLoading(false);
      }
    };

    void init();
  }, []);

  return { member, loading };
}

• 初回レンダリング時に useAuthInitializer() を呼び出す
• ログイン済みなら /me が通る → member がセットされる
• トークン期限切れなら /refresh で再発行 → setAccessToken で Axios にセット

---

ありがちなハマりポイント

1. Sanctum の guard と auth.php のガード設定

• sanctum.php の guard を ['web'] にしたままでも、API 側で auth('api') を使えば OK
• ただし auth.php で api ガードに driver => sanctum を設定しておくこと

'api' => [
    'driver' => 'sanctum',
    'provider' => 'users',
],

これを忘れると、

• login は動くのに…
• auth:sanctum ミドルウェアを通した /me が 401 になる

みたいな地獄に落ちます。

---

2. トークン更新後にフロントが古いトークンを使い続ける問題

refresh のレスポンスに access_token が含まれているのに、

• それを setAccessToken() で Axios に反映していない
• または Redux / Context の状態を更新し忘れている

と、永遠に古いトークンで /me を叩き続けて 401 無限ループになります。

---

3. Cookie は JS から直接触らない（リフレッシュトークン）

リフレッシュトークンは HttpOnly Cookie に入れているので、document.cookie からは触れません。
これはセキュリティ的にはメリット（XSS から守れる）ですが、実装では注意が必要です。

そのため、この記事では

• ブラウザ → Next.js /api/refresh（サーバーコンポーネント側） → Laravel /refresh

という流れを作り、「フロントから直接 Cookie を読む必要がない」構成にしています。

---

まとめ

学習日報アプリの認証を作る中で、

• Laravel Sanctum でのトークン発行（アクセス / リフレッシュ）
• リフレッシュトークンを HttpOnly Cookie に入れる
• Next.js の API ルートで Cookie を中継しつつ /refresh を叩く
• 初期化フローで /me → /refresh → /me を組む

という構成に落ち着きました。

最初は「とりあえずログインできればいいや」と思っていましたが、

• トークンの寿命設計
• セキュリティ（Cookie・XSS 対策）
• クロスドメインな構成（localhost:3000 × localhost:8080）
• Next.js App Router のサーバーコンポーネント文化

が入り混じると、それなりに考えるポイントが多かったです。

同じように Laravel × Next.js で認証を組んでいる人 の参考になれば嬉しいです 🙌
「ここもっと詳しく」「Service 層 / Repository 層のコードも見たい」などあれば、続編を書こうと思います。