Better Auth インテグレーションガイド

概要

Better Auth は TypeScript 向けの型安全な認証フレームワークで、複数のプロバイダー、2FA、SSO、組織、パスキーに対応しています。このスキルでは、Drizzle ORM + PostgreSQL を使用した NestJS バックエンド と Next.js App Router フロントエンドのインテグレーションパターンについて説明しています。

使用場面

• NestJS バックエンドで Better Auth をセットアップするとき
• Next.js App Router フロントエンドを統合するとき
• PostgreSQL で Drizzle ORM スキーマを設定するとき
• ソーシャルログイン (GitHub、Google、Facebook、Microsoft) を実装するとき
• TOTP、パスキーレスパスワード認証、マジックリンクを使用して MFA/2FA を追加するとき
• 信頼できるデバイスとバックアップコードを管理してアカウント復旧を行うとき
• 組織または SSO でマルチテナントアプリを構築するとき
• セッション管理で保護されたルートを作成するとき

クイックスタート

インストール

# バックエンド (NestJS)
npm install better-auth @auth/drizzle-adapter drizzle-orm pg
npm install -D drizzle-kit

# フロントエンド (Next.js)
npm install better-auth

4 フェーズセットアップ

1. データベース: Drizzle をインストールし、スキーマを設定し、マイグレーションを実行
2. バックエンド: NestJS モジュールで Better Auth インスタンスを作成
3. フロントエンド: 認証クライアントを設定し、ページを作成し、ミドルウェアを追加
4. プラグイン: 必要に応じて 2FA、パスキー、組織を追加

完全なバックエンドセットアップについては references/nestjs-setup.md を、プラグイン設定については references/plugins.md を参照してください。

手順

フェーズ 1: データベースセットアップ

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

   npm install drizzle-orm pg @auth/drizzle-adapter better-auth
   npm install -D drizzle-kit
   

2. Drizzle 設定を作成 (drizzle.config.ts)

   import { defineConfig } from 'drizzle-kit';
   export default defineConfig({
     schema: './src/auth/schema.ts',
     out: './drizzle',
     dialect: 'postgresql',
     dbCredentials: { url: process.env.DATABASE_URL! },
   });
   

3. マイグレーションを生成して実行

   npx drizzle-kit generate
   npx drizzle-kit migrate
   

   チェックポイント: テーブルが作成されたことを確認: psql $DATABASE_URL -c "\dt" で user、account、session、verification_token テーブルが表示されるはずです。

フェーズ 2: バックエンドセットアップ (NestJS)

1. データベースモジュールを作成 - Drizzle 接続サービスをセットアップ

2. Better Auth インスタンスを設定

   // src/auth/auth.instance.ts
   import { betterAuth } from 'better-auth';
   import { drizzleAdapter } from '@auth/drizzle-adapter';
   import * as schema from './schema';
   
   export const auth = betterAuth({
     database: drizzleAdapter(schema, { provider: 'postgresql' }),
     emailAndPassword: { enabled: true },
     socialProviders: {
       github: {
         clientId: process.env.AUTH_GITHUB_CLIENT_ID!,
         clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET!,
       }
     }
   });
   

3. 認証コントローラーを作成

   @Controller('auth')
   export class AuthController {
     @All('*')
     async handleAuth(@Req() req: Request, @Res() res: Response) {
       return auth.handler(req);
     }
   }
   

   チェックポイント: GET /auth/get-session エンドポイントをテストすると、認証されていない場合に (エラーなしで) { session: null } が返されます。

フェーズ 3: フロントエンドセットアップ (Next.js)

1. 認証クライアントを設定 (lib/auth.ts)

   import { createAuthClient } from 'better-auth/client';
   export const authClient = createAuthClient({
     baseURL: process.env.NEXT_PUBLIC_APP_URL!
   });
   

2. ミドルウェアを追加 (middleware.ts)

   import { auth } from '@/lib/auth';
   export default auth((req) => {
     if (!req.auth && req.nextUrl.pathname.startsWith('/dashboard')) {
       return Response.redirect(new URL('/sign-in', req.nextUrl.origin));
     }
   });
   export const config = { matcher: ['/dashboard/:path*'] };
   

3. サインインページを作成 - フォームまたはソーシャルボタン付きで

   チェックポイント: ログアウト状態で /dashboard にアクセスすると /sign-in にリダイレクトされます。

フェーズ 4: 高度な機能

references/plugins.md からプラグインを追加:

• 2FA: twoFactor({ issuer: 'AppName', otpOptions: { sendOTP } })

• パスキー: passkey({ rpID: 'domain.com', rpName: 'App' })

• 組織: organization({ avatar: { enabled: true } })

• マジックリンク: magicLink({ sendMagicLink })

• SSO: sso({ saml: { enabled: true } })

  チェックポイント: プラグイン追加後、マイグレーションを再実行し、新しいテーブルが存在することを確認してください。

例

例 1: セッション付き Server Component

入力: Next.js Server Component でユーザーデータを表示します。

// app/dashboard/page.tsx
import { auth } from '@/lib/auth';
import { redirect } from 'next/navigation';

export default async function DashboardPage() {
  const session = await auth();

  if (!session) {
    redirect('/sign-in');
  }

  return (
    <div>
      <h1>Welcome, {session.user.name}</h1>
      <p>Email: {session.user.email}</p>
    </div>
  );
}

出力: 認証されたユーザーのユーザー情報をレンダリング; 認証されていない場合はサインインページにリダイレクト。

例 2: 信頼できるデバイス付き 2FA TOTP 検証

入力: ユーザーが 2FA を有効にしており、サインインしてデバイスを信頼済みとしてマークしたいとします。

// サーバー: 2FA を OTP 送信で設定
export const auth = betterAuth({
  plugins: [
    twoFactor({
      issuer: 'MyApp',
      otpOptions: {
        async sendOTP({ user, otp }, ctx) {
          await sendEmail({
            to: user.email,
            subject: 'Your verification code',
            body: `Code: ${otp}`
          });
        }
      }
    })
  ]
});

// クライアント: TOTP を検証してデバイスを信頼
const verify2FA = async (code: string) => {
  const { data } = await authClient.twoFactor.verifyTotp({
    code,
    trustDevice: true  // デバイスを 30 日間信頼
  });

  if (data) {
    router.push('/dashboard');
  }
};

出力: ユーザーが認証済み; デバイスは 2FA プロンプトなしで 30 日間信頼されます。

例 3: パスキー登録とログイン

入力: パスキー (WebAuthn) 認証を有効にして、パスワードレスログインを実現します。

// サーバー
import { passkey } from '@better-auth/passkey';
export const auth = betterAuth({
  plugins: [
    passkey({
      rpID: 'example.com',
      rpName: 'My App',
    })
  ]
});

// クライアント: パスキーを登録
const registerPasskey = async () => {
  const { data } = await authClient.passkey.register({
    name: 'My Device'
  });
};

// クライアント: パスキーでサインイン
const signInWithPasskey = async () => {
  await authClient.signIn.passkey({
    autoFill: true,  // ブラウザはパスキーを提案
  });
};

出力: ユーザーは生体認証、PIN、またはセキュリティキーで登録・認証できます。

その他の例 (バックアップコード、組織、マジックリンク、条件付き UI) については、references/plugins.md と references/passkey.md を参照してください。

ベストプラクティス

1. 環境変数: すべてのシークレットを .env に保存し、.gitignore に追加してください
2. シークレット生成: BETTER_AUTH_SECRET には openssl rand -base64 32 を使用してください
3. HTTPS 必須: OAuth コールバックには HTTPS が必要です (ローカルテストには ngrok を使用)
4. セッション有効期限: セキュリティ要件に基づいて設定してください (デフォルト 7 日)
5. データベースインデックス: email、userId にインデックスを追加してパフォーマンスを向上させてください
6. エラーハンドリング: 機密情報を公開しない汎用的なエラーを返してください
7. レート制限: ブルートフォース攻撃を防ぐため、認証エンドポイントにレート制限を追加してください
8. 型安全性: 完全な TypeScript カバレッジのために npx better-auth typegen を使用してください

制約と警告

セキュリティに関する注意

• シークレットをコミットしない: .env を .gitignore に追加し、OAuth シークレットやデータベース認証情報をコミットしないでください
• リダイレクト URL を検証: 常に OAuth リダイレクト URL を検証して、オープンリダイレクトを防いでください
• パスワードをハッシュ化: Better Auth は自動的にパスワードをハッシュ化します; カスタムハッシュを実装しないでください
• セッションストレージ: 本番環境では Redis または別のスケーラブルなセッションストアを使用してください
• HTTPS のみ: 本番環境では認証に常に HTTPS を使用してください
• メール検証: パスワードベースの認証では常にメール検証を実装してください

既知の制限

• Better Auth は Next.js App Router サポートに Node.js 18+ が必要です
• 一部の OAuth プロバイダーは特定のリダイレクト URL 形式が必要です
• パスキーには HTTPS と互換性のあるブラウザが必要です
• 組織機能には追加のデータベーステーブルが必要です

リソース

ドキュメント

• Better Auth - 公式ドキュメント
• Drizzle ORM - データベース ORM
• NestJS - バックエンドフレームワーク
• Next.js - フロントエンドフレームワーク

参考実装

• references/nestjs-setup.md - 完全な NestJS バックエンドセットアップ
• references/nextjs-setup.md - 完全な Next.js フロントエンドセットアップ
• references/plugins.md - プラグイン設定 (2FA、パスキー、組織、SSO、マジックリンク)
• references/mfa-2fa.md - 詳細な MFA/2FA ガイド
• references/passkey.md - 詳細なパスキー実装
• references/schema.md - Drizzle スキーマリファレンス
• references/social-providers.md - ソーシャルプロバイダー設定