auth0-nuxt

Auth0 Nuxt SDK

概要

Nuxt 3/4 向けのサーバーサイドセッション認証です。@auth0/auth0-vue（クライアントサイド SPA）とは異なります。

基本原則： クライアントサイドトークンではなく、サーバーサイドの暗号化Cookieセッションを使用します。

使用する場合

次の場合に使用します：

• サーバーサイドレンダリングを使用する Nuxt 3/4 アプリケーションを構築する場合（Node.js 20 LTS+）
• 暗号化Cookieを使用した安全なセッション管理が必要な場合
• サーバールートと API エンドポイントを保護する場合
• Auth0 Management API またはカスタム API にアクセスする場合

次の場合は使用しないでください：

• Nuxt 2 を使用する場合（サポート対象外です。別の Auth0 SDK を使用してください）
• サーバーのない、クライアントサイドのみの SPA を構築する場合（代わりに @auth0/auth0-vue を使用してください）
• Auth0 以外の認証プロバイダーを使用する場合
• サーバーランタイムのない静的サイト生成（SSG）のみを行う場合

避けるべき重大な誤り

誤り	解決策
@auth0/auth0-vue または @auth0/auth0-spa-js をインストールする	@auth0/auth0-nuxt を使用します
Auth0 アプリの種類を「Single Page Application」にする	「Regular Web Application」を使用します
環境変数に VITE_AUTH0_* または VUE_APP_AUTH0_* を使用する	NUXT_AUTH0_* プレフィックスを使用します
セキュリティチェックに useUser() を使用する	サーバーサイドで useAuth0(event).getSession() を使用します
Auth0 Dashboard にコールバック URL がない	http://localhost:3000/auth/callback を追加します
セッションシークレットが弱い、または設定されていない	生成します：openssl rand -hex 64
認証情報を nuxt.config.ts にハードコードする	runtimeConfig の値は空文字列のままにします。Nuxt が NUXT_AUTH0_* 環境変数から自動的に設定します

クイックセットアップ

# 1. Install
npm install @auth0/auth0-nuxt

# 2. Generate secret
openssl rand -hex 64

# 3. .env
NUXT_AUTH0_DOMAIN=your-tenant.auth0.com
NUXT_AUTH0_CLIENT_ID=your-client-id
NUXT_AUTH0_CLIENT_SECRET=your-client-secret
NUXT_AUTH0_SESSION_SECRET=<from-openssl>
NUXT_AUTH0_APP_BASE_URL=http://localhost:3000
NUXT_AUTH0_AUDIENCE=https://your-api  # optional

// 4. nuxt.config.ts
// Leave values as empty strings — Nuxt auto-fills them from NUXT_AUTH0_* env vars at runtime.
// If you prefer explicit mapping, use: domain: process.env.NUXT_AUTH0_DOMAIN || ''
export default defineNuxtConfig({
  modules: ['@auth0/auth0-nuxt'],
  runtimeConfig: {
    auth0: {
      domain: '',
      clientId: '',
      clientSecret: '',
      sessionSecret: '',
      appBaseUrl: 'http://localhost:3000',
      audience: '',  // optional
    },
  },
})

組み込みルート

SDK は次のルートを自動的にマウントします：

ルート	メソッド	用途
/auth/login	GET	ログインフローを開始します。?returnTo=/path パラメーターをサポートします
/auth/callback	GET	ログイン後の Auth0 コールバックを処理します
/auth/logout	GET	ユーザーをログアウトさせ、Auth0 のログアウトページにリダイレクトします
/auth/backchannel-logout	POST	バックチャネルログアウト用のログアウトトークンを受け取ります

カスタマイズ： モジュール設定に routes: { login, callback, logout, backchannelLogout } または mountRoutes: false を渡します。

コンポーザブル

コンポーザブル	コンテキスト	用途
useAuth0(event)	サーバーサイド	getUser()、getSession()、getAccessToken()、logout() にアクセスします
useUser()	クライアントサイド	ユーザーデータの表示専用です。セキュリティチェックには絶対に使用しないでください

// Server example
const auth0 = useAuth0(event);
const session = await auth0.getSession();

<script setup>
const user = useUser();
</script>

<template>
  <div v-if="user">Welcome {{ user.name }}</div>
<template>

ルートの保護

3 つのレイヤー： ルートミドルウェア（クライアント）、サーバーミドルウェア（SSR）、API ガード。

// middleware/auth.ts - Client navigation
export default defineNuxtRouteMiddleware((to) => {
  if (!useUser().value) return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
});

// server/middleware/auth.server.ts - SSR protection
export default defineEventHandler(async (event) => {
  const url = getRequestURL(event);
  const auth0Client = useAuth0(event);
  const session = await auth0Client.getSession();
  if (!session)  {
    return sendRedirect(event, `/auth/login?returnTo=${encodeURIComponent(url.pathname)}`);
  }
});

// server/api/protected.ts - API endpoint protection
export default defineEventHandler(async (event) => {
  const auth0Client = useAuth0(event);
  const session = await auth0Client.getSession();

  if (!session) {
    throw createError({
      statusCode: 401,
      statusMessage: 'Unauthorized'
    });
  }

  return { data: 'protected data' };
});

ロールベース、権限ベース、および高度なパターンについては： route-protection.md

セッション管理

ステートレス（デフォルト）

暗号化されたチャンク分割Cookieを使用します。設定は不要です。

ステートフル（Redis、MongoDB など）

大規模なセッションや分散システム向け：

// nuxt.config.ts
modules: [
  ['@auth0/auth0-nuxt', {
    sessionStoreFactoryPath: '~/server/utils/session-store-factory.ts'
  }]
]

セッションストアの完全な実装については、次を参照してください： session-stores.md

API 連携

API アクセストークン用の audience を設定します：

// nuxt.config.ts
runtimeConfig: {
  auth0: {
    audience: 'https://your-api-identifier',
  }
}

サーバーサイドでトークンを取得します：

// server/api/call-api.ts
export default defineEventHandler(async (event) => {
  const auth0Client = useAuth0(event);
  const { accessToken } = await auth0Client.getAccessToken();

  return await $fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${accessToken}`
    }
  });
});

セキュリティチェックリスト

• ✅ サーバーサイドでのみ検証する（useUser() を決して信頼しない）
• ✅ 本番環境では HTTPS を使用する
• ✅ 強力なセッションシークレットを使用する（openssl rand -hex 64）
• ✅ .env ファイルを絶対にコミットしない
• ✅ PII／大容量データにはステートフルセッションを使用する

トラブルシューティング

エラー	解決策
"Module not found"	@auth0/auth0-vue ではなく @auth0/auth0-nuxt をインストールします
"Missing domain/clientId/clientSecret"	NUXT_AUTH0_ プレフィックス、.env の場所、runtimeConfig を確認します
"Redirect URI mismatch"	Auth0 Dashboard のコールバックを appBaseUrl + /auth/callback と一致させます
"useAuth0 is not defined"	H3 イベントオブジェクトとともに、サーバーコンテキスト内でのみ使用します
Cookie が大きすぎる	ステートフルセッションを使用するか、スコープを減らします

追加リソース

ガイド： ルート保護のパターン • カスタムセッションストア • 一般的な例

関連スキル

• auth0-quickstart - Auth0 の基本設定
• auth0-cli - ターミナルから Auth0 リソースを管理

---

リンク： Auth0-Nuxt GitHub • Auth0 Docs • Nuxt Modules