oauth

使用する場面

以下の場合にこのスキルを使用してください：

• Fastify アプリケーションで OAuth 2.0/2.1 フローを実装またはデバッグする必要がある
• トークンを検証、PKCE を設定、またはリフレッシュトークンローテーションをセットアップする
• Fastify ルートおよびプラグインをアクセス制御ミドルウェアで保護する
• RFC 準拠に関する質問を解決したり、セキュリティアンチパターンを特定したりする

---

ステップバイステップ：Fastify での認可コード + PKCE

1. 依存関係をインストール

npm install @fastify/oauth2 @fastify/cookie @fastify/session fastify-plugin

2. OAuth プラグインを登録

// plugins/oauth.ts
import fp from 'fastify-plugin'
import oauth2, { OAuth2Namespace } from '@fastify/oauth2'
import { FastifyInstance } from 'fastify'

export default fp(async function (fastify: FastifyInstance) {
  fastify.register(oauth2, {
    name: 'oauth2',
    scope: ['openid', 'profile', 'email'],
    credentials: {
      client: {
        id: process.env.CLIENT_ID!,
        secret: process.env.CLIENT_SECRET!,
      },
      auth: {
        authorizeHost: process.env.AUTH_SERVER!,
        authorizePath: '/authorize',
        tokenHost: process.env.AUTH_SERVER!,
        tokenPath: '/token',
      },
    },
    startRedirectPath: '/login',
    callbackUri: process.env.CALLBACK_URI!,
    pkce: 'S256',               // RFC 7636 — 公開クライアントでは常に使用
    generateStateFunction: (req) => req.session.state = crypto.randomUUID(),
    checkStateFunction: (req, callback) =>
      req.query.state === req.session.state ? callback() : callback(new Error('State mismatch')),
  })
})

検証チェックポイント： 先に進む前に、callbackUri が認可サーバーに登録されているリダイレクト URI と完全に一致することを確認してください (RFC 6749 §3.1.2)。

3. コールバックを処理してコードを交換

// routes/auth.ts
import { FastifyInstance } from 'fastify'

export default async function authRoutes(fastify: FastifyInstance) {
  fastify.get('/login/callback', async (request, reply) => {
    // @fastify/oauth2 が state を検証し、コードを自動的に交換します
    const tokenResponse = await fastify.oauth2.getAccessTokenFromAuthorizationCodeFlow(request)

    // 必要なもののみを保存します。生のトークンをログに出力しないでください
    request.session.set('accessToken', tokenResponse.token.access_token)
    request.session.set('refreshToken', tokenResponse.token.refresh_token)

    return reply.redirect('/')
  })

  fastify.get('/logout', async (request, reply) => {
    await request.session.destroy()
    return reply.redirect('/')
  })
}

4. JWT 検証ミドルウェア (トークンイントロスペクションフック)

// hooks/verifyToken.ts
import { FastifyRequest, FastifyReply } from 'fastify'
import jwt from '@fastify/jwt'

export async function verifyToken(request: FastifyRequest, reply: FastifyReply) {
  try {
    await request.jwtVerify()
    // 必須クレームを検証します (RFC 7519)
    const payload = request.user as Record<string, unknown>
    const now = Math.floor(Date.now() / 1000)

    if (typeof payload.exp === 'number' && payload.exp < now)
      return reply.code(401).send({ error: 'token_expired' })

    if (payload.iss !== process.env.EXPECTED_ISSUER)
      return reply.code(401).send({ error: 'invalid_issuer' })

    if (payload.aud !== process.env.EXPECTED_AUDIENCE)
      return reply.code(401).send({ error: 'invalid_audience' })

  } catch (err) {
    return reply.code(401).send({ error: 'invalid_token', error_description: (err as Error).message })
  }
}

検証チェックポイント：

• すべてのリクエストで exp、iss、aud、sub を検証します。スキップしないでください (RFC 7519 §4)
• サードパーティサーバーが発行したトークンの場合、HS256 ではなく fastify.jwt.verify (RS256/ES256 の非対称型) を使用してください

5. ルートを保護

// routes/api.ts
import { FastifyInstance } from 'fastify'
import { verifyToken } from '../hooks/verifyToken'

export default async function apiRoutes(fastify: FastifyInstance) {
  fastify.addHook('onRequest', verifyToken)   // このスコープのすべてのルートに適用されます

  fastify.get('/me', {
    schema: {
      response: { 200: { type: 'object', properties: { sub: { type: 'string' } } } },
    },
  }, async (request) => {
    const user = request.user as { sub: string }
    return { sub: user.sub }
  })
}

6. リフレッシュトークンローテーション

async function refreshAccessToken(fastify: FastifyInstance, refreshToken: string) {
  const newToken = await fastify.oauth2.getNewAccessTokenUsingRefreshTokenFlow({ refresh_token: refreshToken })

  // ローテーションが使用されている場合、保存されたリフレッシュトークンを常に置き換えます (RFC 6749 §10.4)
  return {
    accessToken: newToken.token.access_token,
    refreshToken: newToken.token.refresh_token ?? refreshToken,
  }
}

---

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

要件	RFC リファレンス
リダイレクト URI をアロウリストに対して検証する	RFC 6749 §3.1.2
公開クライアントすべてに PKCE (S256) を使用	RFC 7636 §4.2
CSRF を防ぐために state を検証	RFC 6749 §10.12
すべての JWT で iss、aud、exp を検証	RFC 7519 §4
使用するたびにリフレッシュトークンをローテーション	RFC 6749 §10.4
至る所で HTTPS を使用。HTTP リダイレクト URI を拒否	RFC 6749 §3.1.2.1
トークンエンドポイントにレート制限を設定	OAuth 2.1 §7

---

よくあるアンチパターン

• localStorage にトークンを保存する — 代わりに HttpOnly、Secure、SameSite=Strict クッキーを使用してください
• オーディエンス検証をスキップする — サービス間でのトークンの再利用を許可してしまいます
• 暗黙フロー (Implicit Flow) を使用する — OAuth 2.1 では廃止されました。認可コード + PKCE を使用してください
• ブラウザアプリで response_type=token を受け入れる — URL フラグメント内のトークンはログ/リファラで漏洩します
• サードパーティトークンに対称署名 (HS256) を使用する — JWKS エンドポイントを持つ RS256/ES256 を使用してください

---

さらなる実装リファレンス

• デバイス認可フロー (RFC 8628) の実装については DEVICE_FLOW.md を参照してください
• JWKS ローテーション、キャッシング戦略、不透明なトークンイントロスペクションについては TOKEN_VALIDATION.md を参照してください
• マシンツーマシンのサービス認証パターンについては CLIENT_CREDENTIALS.md を参照してください
• ネイティブ/モバイルアプリフロー (RFC 8252) とカスタム URI スキームについては MOBILE_OAUTH.md を参照してください