auth0-nextjs

Auth0 Next.js 統合

@auth0/nextjs-auth0 を使用して、Next.js アプリケーションに認証を追加します。App Router と Pages Router の両方をサポートしています。

---

前提条件

• Next.js 13 以降のアプリケーション（App Router または Pages Router）
• Auth0 アカウントと設定済みのアプリケーション
• Auth0 がまだ設定されていない場合は、先に auth0-quickstart スキルを使用してください

使用しないケース

• クライアントサイドのみの React アプリ - Vite/CRA の SPA には auth0-react を使用してください
• React Native のモバイルアプリ - iOS/Android には auth0-react-native を使用してください
• Next.js 以外のフレームワーク - 各フレームワーク専用の SDK（Express、Vue、Angular など）を使用してください
• ステートレス API のみ - セッション管理が不要な場合は、JWT 検証ミドルウェアを使用してください

---

クイックスタートのワークフロー

1. SDK をインストールする

npm install @auth0/nextjs-auth0

2. 環境を設定する

Auth0 CLI を使った自動セットアップについては、完全なスクリプトが記載されたセットアップガイドを参照してください。

手動でセットアップする場合：

.env.local を作成します。

AUTH0_SECRET=<generate-a-32-character-secret>
APP_BASE_URL=http://localhost:3000
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

シークレットを生成します：openssl rand -hex 32

重要： .env.local を .gitignore に追加してください

3. Auth0 クライアントとミドルウェアを作成する

まずプロジェクトの構成を確認します： プロジェクトで src/ ディレクトリを使用しているか確認してください（つまり、src/app/ または src/pages/ が存在するかどうかです）。これによってファイルの配置場所が決まります。

• src/ がある場合： src/lib/auth0.ts、src/middleware.ts（または Next.js 16 の場合は src/proxy.ts）
• src/ がない場合： lib/auth0.ts、middleware.ts（または Next.js 16 の場合は proxy.ts）

lib/auth0.ts を作成します（src/ の規約を使用する場合は src/lib/auth0.ts）。

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  secret: process.env.AUTH0_SECRET!,
  appBaseUrl: process.env.APP_BASE_URL!,
});

ミドルウェアの設定（Next.js 15 と 16 の場合）：

Next.js 15 - middleware.ts を作成します（プロジェクトのルート、または src/ を使用する場合は src/middleware.ts）。

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Next.js 16 - 次の 2 つの方法があります。

方法 1： middleware.ts を使用します（Next.js 15 と同じで、src/ の配置規則も同じです）。

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

方法 2： proxy.ts を使用します（プロジェクトのルート、または src/ を使用する場合は src/proxy.ts）。

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function proxy(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

これにより、次のエンドポイントが自動的に作成されます。

• /auth/login - ログイン
• /auth/logout - ログアウト
• /auth/callback - OAuth コールバック
• /auth/profile - ユーザープロフィール

4. ユーザーコンテキストを追加する（任意）

注： v4 では、<Auth0Provider> でラップする必要はありません。サーバー側のレンダリング時に初期ユーザーを useUser() に渡す場合のみ必要です。

App Router - 任意で app/layout.tsx のアプリをラップします。

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import { auth0 } from '@/lib/auth0';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await auth0.getSession();

  return (
    <html>
      <body>
        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
      </body>
    </html>
  );
}

Pages Router - 任意で pages/_app.tsx のアプリをラップします。

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Auth0Provider user={pageProps.user}>
      <Component {...pageProps} />
    </Auth0Provider>
  );
}

5. 認証 UI を追加する

クライアントコンポーネント（どちらのルーターでも動作します）。

'use client'; // Only needed for App Router

import { useUser } from '@auth0/nextjs-auth0/client';

export default function Profile() {
  const { user, isLoading } = useUser();

  if (isLoading) return <div>Loading...</div>;

  if (user) {
    return (
      <div>
        <img src={user.picture} alt={user.name} />
        <h2>Welcome, {user.name}!</h2>
        <a href="/auth/logout">Logout</a>
      </div>
    );
  }

  return <a href="/auth/login">Login</a>;
}

6. 認証をテストする

開発サーバーを起動します。

npm run dev

http://localhost:3000 にアクセスし、ログインフローをテストします。

---

詳細ドキュメント

• セットアップガイド - 自動セットアップスクリプト、環境設定、Auth0 CLI の使用方法
• 統合ガイド - サーバー側の認証、保護されたルート、API ルート、ミドルウェア
• API リファレンス - SDK API の全容、フック、ヘルパー、セッション管理

よくある間違い

間違い	修正方法
v3 の環境変数を使用している	v4 では APP_BASE_URL と AUTH0_DOMAIN を使用します（AUTH0_BASE_URL や AUTH0_ISSUER_BASE_URL ではありません）
Auth0 ダッシュボードにコールバック URL を追加し忘れている	Allowed Callback URLs に /auth/callback を追加します（例：http://localhost:3000/auth/callback）
ミドルウェアの設定がない	v4 では、認証ルートをマウントするためにミドルウェアが必要です。middleware.ts（Next.js 15+16）または proxy.ts（Next.js 16 のみ）を作成し、auth0.middleware() を設定します
ルートパスが間違っている	v4 では /api/auth/login ではなく /auth/login を使用します。ルートから /api プレフィックスがなくなります
AUTH0_SECRET がない、または安全性が低い	openssl rand -hex 32 で安全なシークレットを生成し、.env.local に保存します
.env.local ではなく .env を使用している	Next.js ではローカルのシークレットに .env.local が必要です。また、.env.local は .gitignore に含める必要があります
Auth0 でアプリを SPA タイプとして作成している	Next.js では Regular Web Application タイプである必要があります
削除された v3 ヘルパーを使用している	v4 では withPageAuthRequired と withApiAuthRequired が削除されています。代わりに getSession() を使用します
Server Component で useUser を使用している	useUser はクライアント専用です。Server Component では auth0.getSession() を使用します
AUTH0_DOMAIN に https:// が含まれている	v4 の AUTH0_DOMAIN にはドメインのみを指定します（例：example.auth0.com）。スキームは含めません

---

関連スキル

• auth0-quickstart - Auth0 の基本設定
• auth0-migration - 別の認証プロバイダーから移行
• auth0-mfa - 多要素認証を追加
• auth0-cli - ターミナルから Auth0 リソースを管理

---

クイックリファレンス

V4 のセットアップ：

• src/ 規約を確認します：src/app/ または src/pages/ があるかを確認し、存在する場合はすべてのファイルを src/ 内に配置します
• Auth0Client インスタンスを含む lib/auth0.ts（または src/lib/auth0.ts）を作成します
• ミドルウェア設定を作成します（必須）：
  • Next.js 15：middleware() 関数を含む middleware.ts（または src/middleware.ts）
  • Next.js 16：middleware() を含む middleware.ts、または proxy() 関数を含む proxy.ts（同じ src/ のルール）
• 任意：SSR ユーザー用に <Auth0Provider> でラップします

クライアント側のフック：

• useUser() - クライアントコンポーネントでユーザーを取得
• user - ユーザープロフィールオブジェクト
• isLoading - 読み込み状態

サーバー側のメソッド：

• auth0.getSession() - Server Component／API ルート／ミドルウェアでセッションを取得
• auth0.getAccessToken() - API 呼び出し用のアクセストークンを取得

よくあるユースケース：

• ログイン／ログアウトリンク → /auth/login と /auth/logout のパスを使用します（ステップ 5 を参照）
• 保護されたページ（App Router）→ 統合ガイド
• 保護されたページ（Pages Router）→ 統合ガイド
• 認証付き API ルート → 統合ガイド
• ミドルウェアによる保護 → 統合ガイド

---

参考資料

• Auth0 Next.js SDK ドキュメント
• Auth0 Next.js クイックスタート
• SDK GitHub リポジトリ