auth0-fastify

Auth0 Fastify 統合

@auth0/auth0-fastify を使用して、Fastify の Web アプリケーションに認証を追加します。

---

前提条件

• Fastify アプリケーション（v5.x 以降）
• Node.js 20 LTS 以降
• Auth0 アカウントとアプリケーションの設定
• Auth0 をまだ設定していない場合は、まず auth0-quickstart スキルを使用してください

使用しない場合

• シングルページアプリケーション - クライアントサイド認証には auth0-react、auth0-vue、または auth0-angular を使用してください
• Next.js アプリケーション - クライアントとサーバーの両方に対応する auth0-nextjs スキルを使用してください
• モバイルアプリケーション - React Native/Expo には auth0-react-native を使用してください
• ステートレス API - セッションなしで JWT を検証する場合は、代わりに @auth0/auth0-fastify-api を使用してください
• マイクロサービス - サービス間認証には JWT 検証を使用してください

---

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

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

npm install @auth0/auth0-fastify fastify @fastify/view ejs dotenv

2. 環境を設定する

.env を作成します。

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
SESSION_SECRET=<openssl-rand-hex-64>
APP_BASE_URL=http://localhost:3000

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

3. 認証プラグインを設定する

Fastify サーバー（server.js）を作成します。

import 'dotenv/config';
import Fastify from 'fastify';
import fastifyAuth0 from '@auth0/auth0-fastify';
import fastifyView from '@fastify/view';
import ejs from 'ejs';

const fastify = Fastify({ logger: true });

// Register view engine
await fastify.register(fastifyView, {
  engine: { ejs },
  root: './views',
});

// Configure Auth0 plugin
await fastify.register(fastifyAuth0, {
  domain: process.env.AUTH0_DOMAIN,
  clientId: process.env.AUTH0_CLIENT_ID,
  clientSecret: process.env.AUTH0_CLIENT_SECRET,
  appBaseUrl: process.env.APP_BASE_URL,
  sessionSecret: process.env.SESSION_SECRET,
});

fastify.listen({ port: 3000 });

これにより、以下が自動的に作成されます。

• /auth/login - ログインエンドポイント
• /auth/logout - ログアウトエンドポイント
• /auth/callback - OAuth コールバック

4. ルートを追加する

// Public route
fastify.get('/', async (request, reply) => {
  const session = await fastify.auth0Client.getSession({ request, reply });
  return reply.view('views/home.ejs', {
    isAuthenticated: !!session,
  });
});

// Protected route
fastify.get('/profile', {
  preHandler: async (request, reply) => {
    const session = await fastify.auth0Client.getSession({ request, reply });
    if (!session) {
      return reply.redirect('/auth/login');
    }
  }
}, async (request, reply) => {
  const user = await fastify.auth0Client.getUser({ request, reply });
  return reply.view('views/profile.ejs', { user });
});

5. 認証をテストする

サーバーを起動します。

node server.js

http://localhost:3000 にアクセスして、ログインフローをテストしてください。

---

よくある間違い

間違い	修正方法
Auth0 Dashboard にコールバック URL を追加していない	/auth/callback パスを Allowed Callback URLs に追加します（例：http://localhost:3000/auth/callback）
SESSION_SECRET がない、または弱い	openssl rand -hex 64 で安全な 64 文字のシークレットを生成し、.env に保存します
Auth0 でアプリを SPA タイプとして作成している	サーバーサイド認証には Regular Web Application タイプが必要です
セッションシークレットをコード内に公開している	必ず環境変数を使用し、シークレットをハードコードしないでください
本番環境の appBaseUrl が正しくない	APP_BASE_URL を本番ドメインに合わせて更新します
fastify.register を await していない	Fastify v4 以降では、プラグインの登録を await する必要があります

---

関連スキル

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

---

クイックリファレンス

プラグインのオプション：

• domain - Auth0 テナントのドメイン（必須）
• clientId - Auth0 クライアント ID（必須）
• clientSecret - Auth0 クライアントシークレット（必須）
• appBaseUrl - アプリケーション URL（必須）
• sessionSecret - セッション暗号化シークレット（必須、最小 64 文字）
• audience - API オーディエンス（任意、API 呼び出し用）

クライアントメソッド：

• fastify.auth0Client.getSession({ request, reply }) - ユーザーセッションを取得
• fastify.auth0Client.getUser({ request, reply }) - ユーザープロフィールを取得
• fastify.auth0Client.getAccessToken({ request, reply }) - アクセストークンを取得
• fastify.auth0Client.logout(options, { request, reply }) - ユーザーをログアウト

よくあるユースケース：

• 保護されたルート → preHandler を使用してセッションを確認します（ステップ 4 を参照）
• 認証状態を確認 → !!session
• ユーザー情報を取得 → getUser({ request, reply })
• API を呼び出す → getAccessToken({ request, reply })

---

参考資料

• Auth0 Fastify のドキュメント
• SDK の GitHub リポジトリ