better-auth

Better Auth 統合ガイド

概要

Better Auth は、複数のプロバイダー、2FA、SSO、組織、パスキーに対応した、型安全な TypeScript 向け認証フレームワークです。このスキルでは、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 を使用するマルチテナントアプリを構築する場合
• セッション管理を使用して保護されたルートを作成する場合

クイックスタート

インストール

# Backend (NestJS)
npm install better-auth @auth/drizzle-adapter drizzle-orm pg
npm install -D drizzle-kit

# Frontend (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：セッションを使用するサーバーコンポーネント

入力：Next.js サーバーコンポーネントにユーザーデータを表示します。

// 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 を有効にしたユーザーが、デバイスを信頼済みとしてマークしてサインインしようとしています。

// Server: Configure 2FA with OTP sending
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}`
          });
        }
      }
    })
  ]
});

// Client: Verify TOTP and trust device
const verify2FA = async (code: string) => {
  const { data } = await authClient.twoFactor.verifyTotp({
    code,
    trustDevice: true  // Device trusted for 30 days
  });

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

出力：ユーザーは認証され、2FA を求められることなく、デバイスは 30 日間信頼済みになります。

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

入力：パスワードレスログインのために、パスキー（WebAuthn）認証を有効にします。

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

// Client: Register passkey
const registerPasskey = async () => {
  const { data } = await authClient.passkey.register({
    name: 'My Device'
  });
};

// Client: Sign in with autofill
const signInWithPasskey = async () => {
  await authClient.signIn.passkey({
    autoFill: true,  // Browser suggests passkey
  });
};

出力：ユーザーは生体認証、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 シークレットや DB 認証情報は絶対にコミットしないでください
• リダイレクト 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 - ソーシャルプロバイダーの設定