Auth.js (NextAuth v5) パターン

クイックガイド: ルートの auth.ts ファイルで Auth.js を設定し、NextAuth() から { auth, handlers, signIn, signOut } をエクスポートします。統一された auth() 関数をすべての場所（サーバーコンポーネント、ルートハンドラー、ミドルウェア）で使用します。デフォルトのセッション戦略は JWT（Cookieベース）です。永続的なセッションにはデータベースアダプターを追加します。ミドルウェアまたはページごとの auth() チェックでルートを保護します。

<critical_requirements>

重要: このスキルを使用する前に

すべてのコードは CLAUDE.md のプロジェクト規約に従わなければなりません（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）

(ルートの auth.ts ファイルで Auth.js を設定し、NextAuth() から { auth, handlers, signIn, signOut } をエクスポートする必要があります)

(サーバーサイドのセッションアクセスには、統一された auth() 関数を使用する必要があります - 非推奨の getServerSession()、getSession()、または getToken() は使用しないでください)

(環境変数 AUTH_SECRET を使用する必要があります - NEXTAUTH_SECRET は v5 で非推奨です)

(プロバイダーの認証情報には AUTH_ プレフィックスの環境変数を使用する必要があります（例：AUTH_GITHUB_ID、AUTH_GITHUB_SECRET） - これらは自動検出されます)

(データベースセッションをミドルウェアと併用する場合、認証設定を auth.config.ts（Edge互換）と auth.ts（アダプター付き）に分割する必要があります)

(サーバーアクションおよび API ルート内でセッションをチェックする必要があります - ミドルウェアだけでは認可に不十分です)

</critical_requirements>

自動検出: Auth.js、NextAuth、next-auth、authjs、auth.ts、auth.config.ts、NextAuth()、signIn、signOut、auth()、handlers、SessionProvider、useSession、AUTH_SECRET、OAuth プロバイダー、資格情報プロバイダー、データベースアダプター、@auth/prisma-adapter、@auth/drizzle-adapter、authorized コールバック、jwt コールバック、session コールバック、プロキシ認証、ミドルウェア認証

使用するタイミング:

Next.js、SvelteKit、Express、または Qwik アプリに認証を追加する場合
80 以上のビルトインプロバイダーを使用した OAuth ログイン（GitHub、Google、Discord など）を実装する場合
電子メール/マジックリンク認証フローを構築する場合
JWT またはデータベースバックアップのセッション管理が必要な場合
Edge互換のミドルウェア認証が必要なプロジェクト

使用すべきでないタイミング:

カスタム認証システムをゼロから構築する場合（Auth.js は意見が強く反映されています）
すぐに使えるきめ細かい組織/チーム管理が必要な場合
Web フロントエンドがないモバイル専用アプリ
プラグインアーキテクチャを持つセルフホスト認証が必要な場合

カバーされる主要パターン:

認証設定（auth.ts、auth.config.ts）
OAuth プロバイダー（GitHub、Google、資格情報、メール）
セッション戦略（JWT vs データベース）
セッションアクセス（サーバーコンポーネント、ルートハンドラー、クライアントコンポーネント）
ミドルウェア/プロキシルート保護
データベースアダプター（Prisma、Drizzle）
コールバック（jwt、session、signIn、redirect）
ロールベースのアクセス制御
Edge互換性のための設定分割

詳細リソース:

意思決定フレームワークとアンチパターンについては、reference.md を参照してください

コアパターン:

examples/core.md - 認証設定、プロバイダー、コールバック
examples/session.md - セッション戦略、セッションアクセパターン
examples/middleware.md - ルート保護、ミドルウェア、Edge 互換性
examples/database.md - データベースアダプター、Prisma、Drizzle
examples/patterns.md - ロールベースアクセス、マジックリンク、アカウントリンク

哲学

Auth.js (v5) は認証を 単一の統一 API に統合します。auth() 関数は、サーバーサイドで使用する場合、v4 の getServerSession、getSession、withAuth、getToken を置き換えます。useSession() は引き続き正しいクライアントサイド API です。設定は API ルートではなくルートファイルに配置されます。

基本原則:

フレームワークに依存しない - Next.js、SvelteKit、Express、Qwik で動作
統一 API - すべてのサーバーサイドコンテキストで単一の auth() 関数
プロバイダーエコシステム - AUTH_* 環境変数を自動検出する 80 以上のビルトイン OAuth プロバイダー
デフォルトで JWT - 暗号化された Cookie によるステートレスセッション、データベース不要
Edge 互換 - ミドルウェアは Edge ランタイムで実行（設定分割あり）（Next.js 16 プロキシは Node.js で実行）
プログレッシブな複雑化 - OAuth から始めて、データベースアダプターを追加し、コールバックをカスタマイズ

コアパターン

パターン 1: 認証設定

中央設定ファイルは、NextAuth() から必要なすべてをエクスポートします。

基本的な OAuth 設定

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [
    GitHub, // AUTH_GITHUB_ID と AUTH_GITHUB_SECRET を自動検出
    Google, // AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET を自動検出
  ],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";

export const { GET, POST } = handlers;

なぜ良いか: 単一の設定ファイルですべての認証ユーティリティをエクスポート、プロバイダーは AUTH_* 環境変数を自動検出、API ルートは最小限

環境変数

# .env.local
AUTH_SECRET="generate-with-npx-auth-secret"  # 必須
AUTH_GITHUB_ID="your-github-client-id"       # GitHub プロバイダーによって自動検出
AUTH_GITHUB_SECRET="your-github-secret"      # GitHub プロバイダーによって自動検出
AUTH_GOOGLE_ID="your-google-id"       # Google プロバイダーによって自動検出
AUTH_GOOGLE_SECRET="your-google-secret"

なぜ良いか: v5 では AUTH_ プレフィックスが標準化され、AUTH_SECRET は非推奨の NEXTAUTH_SECRET を置き換え、プロバイダーは認証情報を自動検出

パターン 2: プロバイダー

Auth.js は OAuth、電子メール/マジックリンク、および資格情報認証をサポートします。80 以上のビルトイン OAuth プロバイダーは AUTH_* 環境変数を自動検出します。

// OAuth: プロファイルマッピングをカスタマイズ
GitHub({
  profile(profile) {
    return {
      id: String(profile.id),
      name: profile.name ?? profile.login,
      role: "user",
    };
  },
});

// 資格情報: 入力を検証し、失敗した場合は null を返す
Credentials({
  async authorize(credentials) {
    const parsed = LoginSchema.safeParse(credentials);
    if (!parsed.success) return null;
    const user = await getUserByEmail(parsed.data.email);
    if (
      !user ||
      !(await verifyPassword(parsed.data.password, user.hashedPassword))
    )
      return null;
    return { id: user.id, name: user.name, email: user.email };
  },
});

重要なルール: DB ルックアップの前に入力を検証し、常にパスワードをハッシュ化し、失敗した場合は null を返します（絶対にスローしないでください - 情報漏洩につながります）。完全な実装については examples/core.md を参照してください。

パターン 3: コールバック

4 つのコールバックが認証動作をカスタマイズします。データフロー: jwt コールバック（トークンをエンリッチ） -> session コールバック（クライアントに公開）

callbacks: {
  jwt({ token, user }) {
    if (user) { token.id = user.id; token.role = user.role ?? "user"; }
    return token;
  },
  session({ session, token }) {
    session.user.id = token.id as string;
    session.user.role = token.role as string;
    return session;
  },
}

重要なルール: JWT コールバックはすべての auth() 呼び出し時に実行されます（軽量に保つこと）、user パラメーターはサインイン時にのみ存在し、OAuth トークンをクライアントに公開しないでください。signIn および redirect を含む完全なコールバック実装については examples/core.md を参照してください。

パターン 4: セッションアクセス

統一された auth() 関数は、サーバーサイドで使用する場合、v4 の getServerSession、getSession、getToken を置き換えます。useSession() はクライアントコンポーネントに残ります。

コンテキスト	セッションへのアクセス方法
サーバーコンポーネント	`const session = await auth()`
ルートハンドラー	`export const GET = auth(function GET(req) { req.auth })`
サーバーアクション	`const session = await auth()`
ミドルウェア/プロキシ	`export { auth as middleware }` または `authorized` コールバック
クライアントコンポーネント	`useSession()`（レイアウトに `SessionProvider` が必要）

重要なルール: サーバーサイドのインポートは @/auth から、クライアントサイドのインポートは next-auth/react から行います。クライアントコンポーネントで auth() を呼び出さないでください。完全な実装については examples/session.md を参照してください。

パターン 5: サインイン / サインアウトアクション

2 つのアプローチ: サーバーアクション（推奨、プログレッシブエンハンスメント）またはクライアントサイド。

// サーバーサイド（推奨）: @/auth からインポートし、フォーム内でサーバーアクションを使用
import { signIn, signOut } from "@/auth";
// フォームアクション内: await signIn("github", { redirectTo: "/dashboard" })
// フォームアクション内: await signOut({ redirectTo: "/" })

// クライアントサイド: next-auth/react からインポートし、onClick ハンドラーを使用
import { signIn, signOut } from "next-auth/react";
// onClick: signIn("github", { callbackUrl: "/dashboard" })

重要なルール: サーバーサイドは redirectTo を使用し、クライアントサイドは callbackUrl を使用します。signIn() は内部で NEXT_REDIRECT 例外をスローします。戻り値を期待して try/catch でラップしないでください。完全な実装については examples/core.md を参照してください。

パターン 6: TypeScript 拡張

types/next-auth.d.ts で宣言マージを使用して、セッションと JWT の型を拡張します。Session、User、JWT インターフェースにカスタムフィールド（例：id、role）を宣言し、& DefaultSession["user"] を使用してデフォルトを保持します。完全な型宣言の例については examples/core.md を参照してください。

統合ガイド

Auth.js は認証レイヤーです。 本人確認、セッション管理、ルート保護を処理します。認可ロジック（ロールチェック、権限システム）は処理しません - それはアプリケーションコードです。

フレームワークサポート: Auth.js は、フレームワーク固有のパッケージ（next-auth、@auth/sveltekit、@auth/express）を介して複数の Web フレームワークで動作します。

データベースアダプター: データベースセッションの場合、Auth.js は ORM と統合するアダプターパッケージ（@auth/prisma-adapter、@auth/drizzle-adapter など）を提供します。examples/database.md を参照してください。

セッション戦略はニーズによって異なります:

JWT（デフォルト） - データベース不要、Edge で動作、ステートレス
データベース - アダプターが必要、サーバーサイドのセッションストア、即時無効化をサポート

Auth.js が処理しないもの: きめ細かい認可/RBAC、レート制限、または認証以外のデータベースクエリ - これらはアプリケーションレベルの関心事です。

<red_flags>

レッドフラグ

getServerSession(authOptions) の使用 -- v5 で非推奨。auth.ts から auth() を使用してください
NEXTAUTH_SECRET または NEXTAUTH_URL の使用 -- 非推奨。AUTH_SECRET を使用してください（URL は自動検出されます）
レート制限なしの資格情報プロバイダー -- ブルートフォース攻撃に対して脆弱
セッションコールバックを介した OAuth トークンのクライアントへの公開 -- accessToken/refreshToken はサーバーサイドのみに保持
唯一の認可としてのミドルウェア/プロキシ -- レンダリング前に実行されますが、サーバーアクション/API ルートでのルートごとのチェックを置き換えるわけではありません
ミドルウェアでのデータベースアダプターのインポート -- データベース ORM は Edge ランタイムでは実行できません（Next.js 14/15）。設定を auth.config.ts + auth.ts に分割してください
signIn() を try/catch でラップする -- 内部で NEXT_REDIRECT 例外をスローします（これは意図的です）
JWT コールバックが呼び出しごとにデータベースにクエリを実行する -- すべての auth() 呼び出しで実行されます。軽量に保ってください

完全なアンチパターンリスト、注意点、移行テーブルについては reference.md を参照してください。

</red_flags>

<critical_reminders>

重要な注意点

すべてのコードは CLAUDE.md のプロジェクト規約に従わなければなりません

(ルートの auth.ts ファイルで Auth.js を設定し、NextAuth() から { auth, handlers, signIn, signOut } をエクスポートする必要があります)

(環境変数 AUTH_SECRET を使用する必要があります - NEXTAUTH_SECRET は v5 で非推奨です)

(サーバーアクションおよび API ルート内でセッションをチェックする必要があります - ミドルウェアだけでは認可に不十分です)

これらのルールに従わないと、認証の失敗、非推奨パターンの公開、またはセキュリティの脆弱性が発生します。

</critical_reminders>

Auth.js (NextAuth v5) 認証パターン