Fastifyアプリケーションにログイン機能を追加

AI を使って Auth0 を統合

Claude Code、Cursor、GitHub Copilot などの AI コーディングアシスタントを使っている場合は、agent skills を使って、数分で Auth0 の認証を自動的に追加できます。インストール:

npx skills add auth0/agent-skills --skill auth0

次に、AI アシスタントにこう依頼します:

Add Auth0 authentication to my Fastify app

AI アシスタントが、Auth0 アプリケーションの作成、資格情報の取得、@auth0/auth0-fastify のインストール、プラグインの設定、必要なルートやビューの作成まで自動的に行います。agent skills の完全なドキュメント →

前提条件: 始める前に、以下がインストールされていることを確認してください。

Node.js 20 LTS 以降
npm 10 以上、または yarn 1.22 以上、または pnpm 8 以上

インストールを確認するには: node --version && npm --versionFastify のバージョン互換性: このクイックスタートは Fastify 5.x 以降に対応しています。

はじめる

このクイックスタートでは、FastifyアプリケーションにAuth0の認証を追加する方法を紹介します。Auth0 Fastify SDKを使って、ログイン、ログアウト、ユーザープロファイルの機能を備えた安全なWebアプリケーションを構築します。

新しいプロジェクトを作成する

Fastifyアプリケーション用の新しいディレクトリを作成し、Node.jsプロジェクトを初期化します。

mkdir auth0-fastify && cd auth0-fastify

プロジェクトを初期化する

npm init -y

プロジェクト構成を作成する

touch server.js .env

Auth0 Fastify SDKをインストールする

必要な依存関係をインストールする

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

サーバーサイドレンダリングには、ejs と @fastify/view を使用しています。Fastify がサポートしている任意のテンプレートエンジンを使用できます。

package.json を更新して、start スクリプトを追加します:

package.json

{
  "name": "auth0-fastify",
  "version": "1.0.0",
  "type": "module",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  },
  "dependencies": {
    "@auth0/auth0-fastify": "^1.2.0",
    "@fastify/view": "^10.0.0",
    "dotenv": "^16.3.1",
    "ejs": "^3.1.9",
    "fastify": "^5.0.0"
  }
}

Auth0 Appを設定する

次に、Auth0 テナントで新しいアプリケーションを作成し、環境変数をプロジェクトに追加します。Auth0 アプリの設定方法は 3 つあります。Quick Setup ツール (推奨) を使う方法、CLI コマンドを実行する方法、または Auth0 Dashboard から手動で設定する方法です。

Quick Setup（推奨）
CLI
Auth0 Dashboard

Auth0 App を作成し、適切な設定値があらかじめ入力された .env ファイルをコピーします。

プロジェクトのルートディレクトリで次のコマンドを実行し、Auth0 アプリを作成して .env ファイルを生成します。

# Auth0 CLI をインストールします（まだインストールしていない場合）
brew tap auth0/auth0-cli && brew install auth0

# Auth0 アプリを設定し、.env ファイルを生成します
auth0 qs setup --app --type regular --framework fastify --name "My Fastify App" --port 3000

# Auth0 CLI をインストールします（まだインストールしていない場合）
scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0

# Auth0 アプリを設定し、.env ファイルを生成します
auth0 qs setup --app --type regular --framework fastify --name "My Fastify App" --port 3000

このコマンドでは次の処理が行われます。

認証済みかどうかを確認します (必要に応じて login を求められます)
http://localhost:3000 用に設定された Auth0 の Regular Web Application を作成します
AUTH0_DOMAIN、AUTH0_CLIENT_ID、AUTH0_CLIENT_SECRET、SESSION_SECRET、APP_BASE_URL を含む .env ファイルを生成します

Auth0 Dashboard に移動します
アプリケーション → Create Application に移動します
アプリケーション名を入力します (例: “My Fastify App”)
従来型Webアプリケーション を選択し、Create をクリックします
設定タブで、以下を設定します。

設定	値
Allowed Callback URLs	`http://localhost:3000/auth/callback`
Allowed Logout URLs	`http://localhost:3000`

下にスクロールして Save Changes をクリックします
Basic Information セクションから Domain、Client ID、Client Secret の値をコピーします

以下の値を使って .env ファイルを作成します。

.env

AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
AUTH0_CLIENT_ID=YOUR_CLIENT_ID
AUTH0_CLIENT_SECRET=YOUR_CLIENT_SECRET
SESSION_SECRET=use-a-long-random-string-at-least-64-characters
APP_BASE_URL=http://localhost:3000

YOUR_AUTH0_DOMAIN は Auth0 テナントのドメイン (例: dev-abc123.us.auth0.com) に、YOUR_CLIENT_ID はアプリケーションの Client ID に、YOUR_CLIENT_SECRET は dashboard のアプリケーションの Client Secret に置き換えてください。

セッション暗号化用の安全な secret を生成します。

openssl rand -hex 64

出力をコピーし、.env ファイルの SESSION_SECRET の値として使用します。

.env ファイルが存在することを確認します: cat .env (Mac/Linux) または type .env (Windows)

Auth0プラグインを設定する

Fastify サーバーを作成し、Auth0プラグインを登録します。

server.js

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

const fastify = Fastify({ logger: true });
const port = process.env.PORT || 3000;

// ビューエンジンを登録する
await fastify.register(fastifyView, {
  engine: { ejs },
  root: './views',
});

// Auth0プラグインを登録する
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 }, (err) => {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }
  fastify.log.info(`Server running at http://localhost:${port}`);
});

この設定でできること:

HTML テンプレートをレンダリングするためのビューエンジンを登録します
資格情報を使用して Auth0 プラグインを設定します
/auth/login、/auth/logout、/auth/callback のルートを自動的に作成します
暗号化された Cookie を使ったセッション管理を行います

ビューテンプレートを作成

views ディレクトリを作成し、テンプレートファイルを追加します：

Mac/Linux

mkdir views && touch views/home.ejs views/profile.ejs

Windows

New-Item -ItemType Directory -Path views
New-Item -ItemType File -Path views/home.ejs
New-Item -ItemType File -Path views/profile.ejs

ホームページのテンプレートを作成します：

views/home.ejs

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Auth0 Fastify Quickstart</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      margin: 0;
      padding: 2rem;
      min-height: 100vh;
      display: flex;
      justify-content: center;
      align-items: center;
    }
    .container {
      background: white;
      border-radius: 20px;
      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
      padding: 3rem;
      max-width: 500px;
      width: 100%;
      text-align: center;
    }
    h1 {
      color: #2d3748;
      font-size: 2.5rem;
      margin-bottom: 1rem;
    }
    .status {
      padding: 1rem;
      border-radius: 10px;
      margin: 1.5rem 0;
      font-size: 1.1rem;
    }
    .logged-in {
      background: #d4edda;
      color: #155724;
    }
    .logged-out {
      background: #f8d7da;
      color: #721c24;
    }
    .button {
      display: inline-block;
      padding: 1rem 2rem;
      margin: 0.5rem;
      border-radius: 10px;
      text-decoration: none;
      font-weight: 600;
      transition: all 0.3s;
    }
    .button-primary {
      background: #667eea;
      color: white;
    }
    .button-primary:hover {
      background: #5568d3;
      transform: translateY(-2px);
    }
    .button-secondary {
      background: #e53e3e;
      color: white;
    }
    .button-secondary:hover {
      background: #c53030;
      transform: translateY(-2px);
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>🚀 Auth0 Fastify</h1>
    <div class="status <%= isAuthenticated ? 'logged-in' : 'logged-out' %>">
      <%= isAuthenticated ? '✓ You are logged in' : '✗ You are logged out' %>
    </div>
    <div>
      <% if (isAuthenticated) { %>
        <a href="/profile" class="button button-primary">View Profile</a>
        <a href="/auth/logout" class="button button-secondary">Logout</a>
      <% } else { %>
        <a href="/auth/login" class="button button-primary">Login</a>
      <% } %>
    </div>
  </div>
</body>
</html>

プロファイルページのテンプレートを作成します：

views/profile.ejs

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Profile - Auth0 Fastify</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      margin: 0;
      padding: 2rem;
      min-height: 100vh;
    }
    .container {
      background: white;
      border-radius: 20px;
      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
      padding: 3rem;
      max-width: 700px;
      margin: 0 auto;
    }
    h1 {
      color: #2d3748;
      margin-bottom: 2rem;
    }
    .profile-card {
      display: flex;
      align-items: center;
      gap: 2rem;
      padding: 2rem;
      background: #f7fafc;
      border-radius: 15px;
      margin-bottom: 2rem;
    }
    .profile-picture {
      width: 100px;
      height: 100px;
      border-radius: 50%;
      object-fit: cover;
      border: 3px solid #667eea;
    }
    .profile-info h2 {
      margin: 0 0 0.5rem 0;
      color: #2d3748;
    }
    .profile-info p {
      margin: 0;
      color: #718096;
    }
    .user-data {
      background: #f7fafc;
      padding: 1.5rem;
      border-radius: 10px;
      overflow-x: auto;
    }
    pre {
      margin: 0;
      white-space: pre-wrap;
      word-wrap: break-word;
    }
    .button {
      display: inline-block;
      padding: 0.75rem 1.5rem;
      margin-right: 1rem;
      border-radius: 10px;
      text-decoration: none;
      font-weight: 600;
      transition: all 0.3s;
    }
    .button-primary {
      background: #667eea;
      color: white;
    }
    .button-primary:hover {
      background: #5568d3;
    }
    .button-secondary {
      background: #e53e3e;
      color: white;
    }
    .button-secondary:hover {
      background: #c53030;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>User Profile</h1>
    <div class="profile-card">
      <img src="<%= user.picture || 'https://via.placeholder.com/100' %>" alt="Profile" class="profile-picture">
      <div class="profile-info">
        <h2><%= user.name || user.nickname || 'User' %></h2>
        <p><strong>Email:</strong> <%= user.email || 'N/A' %></p>
      </div>
    </div>
    <h3>Full User Object</h3>
    <div class="user-data">
      <pre><%= JSON.stringify(user, null, 2) %></pre>
    </div>
    <div style="margin-top: 2rem;">
      <a href="/" class="button button-primary">← Back to Home</a>
      <a href="/auth/logout" class="button button-secondary">Logout</a>
    </div>
  </div>
</body>
</html>

ルートを作成

server.js ファイルにルートを追加します:

server.js

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

const fastify = Fastify({ logger: true });
const port = process.env.PORT || 3000;

// ビューエンジンを登録する
await fastify.register(fastifyView, {
  engine: { ejs },
  root: './views',
});

// Auth0プラグインを登録する
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.get('/', async (request, reply) => {
  const session = await fastify.auth0Client.getSession({ request, reply });
  return reply.view('views/home.ejs', {
    isAuthenticated: !!session,
  });
});

// プロファイルルート - 保護済み
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 });
});

// サーバーを起動する
fastify.listen({ port }, (err) => {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }
  fastify.log.info(`Server running at http://localhost:${port}`);
});

要点:

ホームルートでは認証状態を確認し、その結果をテンプレートに渡します
プロファイルルートでは、ルートを保護するために preHandler を使用します
getSession() は、認証済みであればユーザーのセッションを返し、未認証の場合は null を返します
getUser() は、認証済みユーザーのプロファイル情報を返します

アプリを実行する

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

npm run dev

ブラウザで http://localhost:3000 を開きます。

Node.js 20 以降では、--watch フラグを使うと、ファイルの変更時にサーバーが自動的に再起動します。

チェックポイントこれで、Auth0 のログインページが完全に機能するようになっているはずです。次のように動作します。

“Login” をクリック - Auth0 の Universal Login ページにリダイレクトされます
認証を完了 - アプリにリダイレクトされます
“/profile” にアクセス - ユーザー情報が表示されます
“Logout” をクリック - アプリと Auth0 の両方からログアウトします

高度な使い方

アクセストークンを使用して保護されたAPIを呼び出す

アクセストークンが必要な外部APIを呼び出すには、SDKで audience を設定します。

server.js

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,
  audience: process.env.AUTH0_AUDIENCE, // これを追加
});

.env ファイルに次を追加します。

.env

AUTH0_AUDIENCE=https://your-api.example.com

次に、アクセストークンを取得して使用します。

server.js

fastify.get('/api-data', {
  preHandler: async (request, reply) => {
    const session = await fastify.auth0Client.getSession({ request, reply });
    if (!session) {
      return reply.redirect('/auth/login');
    }
  }
}, async (request, reply) => {
  try {
    const { accessToken } = await fastify.auth0Client.getAccessToken({ request, reply });

    // 保護されたAPIを呼び出す
    const response = await fetch('https://your-api.example.com/data', {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    });

    const data = await response.json();
    return data;
  } catch (error) {
    fastify.log.error('API call failed:', error);
    return reply.status(500).send({ error: 'Failed to fetch data' });
  }
});

デフォルトでは、Auth0 のルートは /auth/* にマウントされます。自動マウントを無効にして、カスタムルートを作成することもできます。

server.js

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,
  mountRoutes: false, // 自動マウントを無効化
});

// カスタムログインルート
fastify.get('/custom-login', async (request, reply) => {
  const authorizationUrl = await fastify.auth0Client.startInteractiveLogin(
    {
      authorizationParams: {
        redirect_uri: `${process.env.APP_BASE_URL}/custom-callback`
      }
    },
    { request, reply }
  );
  return reply.redirect(authorizationUrl.href);
});

// カスタムコールバックルート
fastify.get('/custom-callback', async (request, reply) => {
  await fastify.auth0Client.completeInteractiveLogin(
    new URL(request.url, process.env.APP_BASE_URL),
    { request, reply }
  );
  return reply.redirect('/');
});

// カスタムログアウトルート
fastify.get('/custom-logout', async (request, reply) => {
  const logoutUrl = await fastify.auth0Client.logout(
    { returnTo: process.env.APP_BASE_URL },
    { request, reply }
  );
  return reply.redirect(logoutUrl.href);
});

カスタムコールバックURLを含めるよう、Auth0 Dashboard の Allowed Callback URLs を忘れずに更新してください。

アカウントリンク

ユーザーが複数の認証プロバイダーを1つのアカウントにリンクできるようにします。

server.js

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,
  mountConnectRoutes: true, // アカウントリンク用ルートを有効化
});

これにより、次のルートが自動的に作成されます。

/auth/connect - 新しいプロバイダーをリンク
/auth/connect/callback - リンク用コールバックを処理
/auth/unconnect - プロバイダーをリンク解除
/auth/unconnect/callback - リンク解除用コールバックを処理

プロファイルページにリンク用のボタンを追加します。

views/profile.ejs

<div>
  <a href="/auth/connect?connection=google-oauth2">Link Google Account</a>
  <a href="/auth/unconnect?connection=google-oauth2">Unlink Google Account</a>
</div>

TypeScript を使う

型安全性を高めるため、プロジェクトを TypeScript に移行します。

npm install --save-dev typescript @types/node tsx

tsconfig.json を作成します。

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

server.js の名前を server.ts に変更し、型を追加します。

server.ts

import 'dotenv/config';
import Fastify, { FastifyRequest, FastifyReply } from 'fastify';
import fastifyView from '@fastify/view';
import fastifyAuth0 from '@auth0/auth0-fastify';
import ejs from 'ejs';

const fastify = Fastify({ logger: true });
const port = process.env.PORT || 3000;

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

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.get('/', async (request: FastifyRequest, reply: FastifyReply) => {
  const session = await fastify.auth0Client.getSession({ request, reply });
  return reply.view('views/home.ejs', {
    isAuthenticated: !!session,
  });
});

fastify.listen({ port: Number(port) });

package.json を更新します。

package.json

{
  "scripts": {
    "dev": "tsx watch server.ts",
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

トラブルシューティング

よくある問題と解決策

ログイン後の「Invalid state」エラー

問題: 認証リクエストとコールバックの間で state が一致していません。解決策:

Cookie が正しく設定されていることを確認してください (ブラウザでブロックされていないこと)
コールバック URL が Auth0 Dashboard で完全に一致していることを確認してください (/auth/callback を含む)
SESSION_SECRET が設定されており、64 文字以上であることを確認してください

「session is undefined」エラー

問題: セッションデータを取得できません。解決策: セッションメソッドにアクセスする前に、Auth0 プラグインが登録されていることを確認してください。

// ✅ 正しい順序
await fastify.register(fastifyAuth0, { ... });
fastify.get('/profile', async (request, reply) => {
  const session = await fastify.auth0Client.getSession({ request, reply });
});

// ❌ 誤り - プラグインがawaitされていない
fastify.register(fastifyAuth0, { ... }); // awaitが不足
fastify.get('/profile', async (request, reply) => { ... });

コールバック URL の不一致

問題: Auth0 から「Callback URL mismatch」エラーが返されます。解決策:

Auth0 Dashboard → アプリケーション → あなたのアプリ → 設定に移動します
Allowed Callback URLs に http://localhost:3000/auth/callback を追加します
URL は完全に一致している必要があります (/auth/callback パスを含む)

環境変数が読み込まれない

問題: 設定値が undefined になっています。解決策:

import 'dotenv/config' がエントリーファイルの先頭にあることを確認してください
.env ファイルがルートディレクトリにあることを確認してください
変数名にタイプミスがないか確認してください

// デバッグ: 設定値をログに出力（本番環境では削除してください！）
console.log('Config check:', {
  hasDomain: !!process.env.AUTH0_DOMAIN,
  hasClientID: !!process.env.AUTH0_CLIENT_ID,
  hasSecret: !!process.env.SESSION_SECRET,
});

次のステップ

認証が正しく動作するようになったので、次もぜひ確認してみてください。

Fastify API 認証 - JWT の検証で API エンドポイントを保護する
Universal Login をカスタマイズする - ログイン体験をブランドに合わせる
ソーシャル接続を追加する - Google、GitHub などのソーシャルログインを有効にする
MFA を実装する - 多要素認証を追加する

リソース

auth0-fastify GitHub - ソースコードとサンプル
Fastify Documentation - Fastify について詳しく知る
Auth0 Community - Auth0 Community でサポートを受ける

Quickstarts

Auth0 の概要

Auth0 を設定する

アプリケーション

Fastifyアプリケーションにログイン機能を追加

はじめる

高度な使い方

トラブルシューティング

ログイン後の「Invalid state」エラー

「session is undefined」エラー

コールバック URL の不一致

環境変数が読み込まれない

次のステップ

リソース

​はじめる

​高度な使い方

​トラブルシューティング

​ログイン後の「Invalid state」エラー

​「session is undefined」エラー

​コールバック URL の不一致

​環境変数が読み込まれない

​次のステップ

​リソース

はじめる

高度な使い方

トラブルシューティング

ログイン後の「Invalid state」エラー

「session is undefined」エラー

コールバック URL の不一致

環境変数が読み込まれない

次のステップ

リソース