auth0-fastify-api

Auth0 Fastify API 統合

@auth0/auth0-fastify-api を使用して JWT アクセストークンを検証し、Fastify API のエンドポイントを保護します。

---

前提条件

• Fastify API アプリケーション（v5.x 以降）
• Node.js 20 LTS 以降
• Auth0 API の設定（Application ではなく、API リソースである必要があります）
• まだ Auth0 を設定していない場合は、まず auth0-quickstart スキルを使用してください

使用しないケース

• サーバーサイドレンダリングのウェブアプリケーション - セッションベースの認証には @auth0/auth0-fastify を使用してください
• シングルページアプリケーション - クライアントサイド認証には auth0-react、auth0-vue、または auth0-angular を使用してください
• Next.js アプリケーション - auth0-nextjs スキルを使用してください
• モバイルアプリケーション - React Native/Expo には auth0-react-native を使用してください

---

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

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

npm install @auth0/auth0-fastify-api fastify dotenv

2. Auth0 API を作成する

Auth0 で必要なのは API です（Application ではありません）。

# Using Auth0 CLI
auth0 apis create \
  --name "My Fastify API" \
  --identifier https://my-api.example.com

または、Auth0 Dashboard → Applications → APIs から手動で作成します

3. 環境を設定する

.env を作成します。

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://my-api.example.com

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

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

import 'dotenv/config';
import Fastify from 'fastify';
import fastifyAuth0Api from '@auth0/auth0-fastify-api';

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

// Register Auth0 API plugin
await fastify.register(fastifyAuth0Api, {
  domain: process.env.AUTH0_DOMAIN,
  audience: process.env.AUTH0_AUDIENCE,
});

fastify.listen({ port: 3001 });

5. ルートを保護する

// Public route - no authentication
fastify.get('/api/public', async (request, reply) => {
  return {
    message: 'Hello from a public endpoint!',
    timestamp: new Date().toISOString(),
  };
});

// Protected route - requires valid JWT
fastify.get('/api/private', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  return {
    message: 'Hello from a protected endpoint!',
    user: request.user.sub,
    timestamp: new Date().toISOString(),
  };
});

// Protected route with user info
fastify.get('/api/profile', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  return {
    profile: request.user,  // JWT claims
  };
});

6. API をテストする

公開エンドポイントをテストします。

curl http://localhost:3001/api/public

保護されたエンドポイントをテストします（アクセストークンが必要です）。

# First, obtain an access token (e.g. via Auth0 Dashboard > APIs > Test tab)
curl http://localhost:3001/api/private \
  -H "Authorization: Bearer $ACCESS_TOKEN"

---

よくある間違い

間違い	対処方法
Auth0 で API ではなく Application を作成した	Auth0 Dashboard → Applications → APIs で API リソースを作成する必要があります
Authorization ヘッダーがない	保護されたエンドポイントへのすべてのリクエストに Authorization: Bearer <token> を含めてください
トークンの audience が間違っている	クライアントは、一致する audience パラメーターを指定してトークンをリクエストする必要があります
アクセストークンではなく ID トークンを使用している	API 認証には ID トークンではなく、アクセストークンを使用する必要があります
401/403 エラーを処理していない	未認証／アクセス禁止のレスポンスに対する適切なエラー処理を実装してください

---

関連スキル

• auth0-quickstart - Auth0 の基本設定
• auth0-fastify - セッションを使用するサーバーサイドレンダリングの Fastify ウェブアプリ向け
• auth0-mfa - 多要素認証を追加する
• auth0-cli - ターミナルから Auth0 リソースを管理する

---

クイックリファレンス

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

• domain - Auth0 テナントのドメイン（必須）
• audience - Auth0 API 設定にある API 識別子（必須）

リクエストのプロパティ：

• request.user - デコードされた JWT クレームオブジェクト
• request.user.sub - ユーザー ID（サブジェクト）

ミドルウェア：

• fastify.requireAuth() - JWT 検証でルートを保護します
• fastify.requireAuth({ scopes: 'read:data' }) - 特定のスコープを要求します
• fastify.requireAuth({ scopes: ['read:data', 'write:data'] }) - 特定のスコープを要求します

よくあるユースケース：

• ルートを保護する → preHandler: fastify.requireAuth() を使用します（ステップ 5 を参照）
• ユーザー ID を取得する → request.user.sub
• カスタムクレーム → request.user['namespace/claim'] からアクセスします

---

参考資料

• Auth0 Fastify API のドキュメント
• SDK の GitHub リポジトリ
• アクセストークンのガイド