better-auth

better-auth

パッケージ: [email protected]（v1.4.0以降はESMのみ） ドキュメント: https://better-auth.com/docs | GitHub: https://github.com/better-auth/better-auth

環境設定

変数	用途
BETTER_AUTH_SECRET	暗号化シークレット（32文字以上）。生成方法: openssl rand -base64 32
BETTER_AUTH_URL	ベースURL（例: https://example.com）

環境変数が設定されていない場合にのみ、設定でbaseURL／secretを定義してください。CLIは次の場所でauth.tsを探します: ./、./lib、./utils、または./src。

コア設定オプション

オプション	備考
appName	表示名（任意）
baseURL	BETTER_AUTH_URLが設定されていない場合のみ
basePath	デフォルトは/api/auth。ルートには/を設定します。
secret	BETTER_AUTH_SECRETが設定されていない場合のみ
database	ステートレスモード（v1.4以降）を使用する場合を除き必須
secondaryStorage	セッションとレート制限用のRedis／KV
emailAndPassword	有効化するには{ enabled: true }を指定
socialProviders	{ google: { clientId, clientSecret }, ... }
plugins	プラグインの配列
trustedOrigins	CSRFの許可リスト

プラグインリファレンス

プラグイン	説明
twoFactor	TOTP、メールOTP、バックアップコード
organization	マルチテナント組織、チーム、招待、RBAC
admin	ユーザー管理、なりすまし、利用停止
passkey	WebAuthnによるパスワードレスログイン
magicLink	メールを使ったパスワードレスログイン
jwt	キーローテーションとJWKSに対応したJWTトークン
oauthProvider	独自のOAuth 2.1プロバイダーを構築（別パッケージ@better-auth/oauth-provider）
sso	OIDC、OAuth2、SAML 2.0に対応したエンタープライズSSO（別パッケージ@better-auth/sso）
scim	エンタープライズ向けユーザープロビジョニング（別パッケージ@better-auth/scim）
stripe	決済とサブスクリプションの管理
bearer	モバイル／CLI向けAPIトークン認証
apiKey	レート制限付きのトークンベース認証
oneTap	手間のかからないGoogle One Tapサインイン
anonymous	PIIを必要としないゲストユーザーアクセス
genericOAuth	PKCEに対応したカスタムOAuthプロバイダー
emailOTP	メールベースのワンタイムパスワード認証
phoneNumber	電話番号／SMSベースのOTPサインイン
username	ユーザー名ベースのサインイン（メールの代替）
multiSession	同じブラウザーで複数のアカウントを利用
openAPI	/api/auth/referenceでインタラクティブなAPIドキュメントを提供

セッション戦略

戦略	形式	ユースケース
Compact（デフォルト）	Base64url + HMAC-SHA256	最小かつ最速
JWT	標準の JWT	相互運用可能
JWE	A256CBC-HS512 暗号化	最も安全

はじめに

新しいプロジェクトや Better Auth を初めてセットアップする場合は、公式の対話型セットアップスキルを使用してください。

npx skills add better-auth/skills -s create-auth-skill

このスキルでは、フレームワークの検出、データベースの選択、認証方式の選択、プラグインのセットアップを順に進め、初期設定を生成します。

避けるべきパターン

避けるべきパターン	正しい方法
d1Adapter を使用する	provider: "sqlite" を指定した Drizzle または Kysely アダプターを使用します
設定でテーブル名を使用する	DB のテーブル名ではなく、ORM のモデル名を使用します
プラグイン変更後に CLI を実行し忘れる	npx @better-auth/cli@latest generate を再実行します
tanstackStartCookies() を最後のプラグインにしない	配列の最後のプラグインにする必要があります（TanStack Start）
ログイン状態の確認に session を使う	session?.user を確認します。session オブジェクトは常に truthy です
nodejs_compat フラグを設定し忘れる	Cloudflare Workers では wrangler.toml で必須です
認証で Kysely の CamelCasePlugin を使う	プラグインを使用しない別の Kysely インスタンスを使用します
古い reactStartCookies のインポートを使う	v1.4.14 で better-auth/tanstack-start の tanstackStartCookies に名称変更されました

よくある間違い

間違い	正しいパターン
環境変数がすでに設定されているのに、設定で baseURL と secret を指定する	BETTER_AUTH_URL と BETTER_AUTH_SECRET の環境変数が設定されていない場合に限り、設定でこれらを定義します
better-auth v1.4 以降で CommonJS の require 構文を使う	better-auth は v1.4.0 以降 ESM 専用です。import 構文のみを使用してください
プラグインの追加や変更後に CLI の generate を再実行しない	プラグイン変更後は、DB スキーマを更新するために必ず npx @better-auth/cli@latest generate を実行します
ログイン検出に session オブジェクトが truthy かどうかを使う	代わりに session?.user を確認します。session オブジェクト自体は常に truthy です
Cloudflare D1 に d1Adapter を直接使う	D1 との互換性のため、provider: "sqlite" を指定した Drizzle または Kysely アダプターを使用します

破壊的変更

バージョン	変更
v1.4.14	reactStartCookies は tanstackStartCookies に名称変更されました（better-auth/tanstack-start からインポート）
v1.4.6	allowImpersonatingAdmins のデフォルト値が false になりました
v1.4.0	ESM 専用（CommonJS 非対応）。SSO、SCIM、OAuth Provider は別パッケージに移動しました
v1.3.0	複数チームのテーブル構造：新しい teamMembers テーブルが必要です

委任

認証に取り組む場合は、以下に委任してください。

• application-security — セキュリティアーキテクチャと脅威モデリング
• database — Drizzle ORM のスキーマとマイグレーション
• tanstack-start — TanStack Start の統合パターン

リソース

• ドキュメント：https://better-auth.com/docs
• オプションのリファレンス：https://better-auth.com/docs/reference/options
• LLMs.txt：https://better-auth.com/llms.txt
• 変更履歴：https://www.better-auth.com/changelogs
• TanStack Start：https://www.better-auth.com/docs/integrations/tanstack
• Expo：https://www.better-auth.com/docs/integrations/expo

参考資料

• データベースアダプター — Drizzle、Kysely、Prisma のアダプター、Cloudflare Workers のファクトリーパターン
• セッション管理 — Cookie キャッシュ、ステートレスセッション、ストレージの優先順位、freshAge の制約
• プラグインとソーシャル認証 — プラグインの設定、OAuth 2.1 プロバイダー、管理者 RBAC、ソーシャルプロバイダーのスコープ
• メールとパスワード — 確認、パスワードのリセット、タイミング攻撃の防止、ハッシュ化（scrypt、argon2）、トークンのセキュリティ
• 二要素認証 — TOTP、メール／SMS OTP、バックアップコード、信頼済みデバイス、2FA のセッションフロー
• 組織 — マルチテナント組織、チーム、招待、RBAC、動的アクセス制御、ライフサイクルフック
• 設定 — ユーザー／アカウントの設定、レート制限、フック、CSRF、信頼済みオリジン、Cookie／OAuth のセキュリティ、本番環境のチェックリスト
• フレームワークとの統合 — TanStack Start のセットアップ、Expo／React Native、クライアントのインポート、型安全性
• 移行ガイド — スキーママッピングとセッション戦略を使用して、NextAuth/Auth.js、Clerk、Supabase Auth から移行する方法
• トラブルシューティング — D1 の整合性、CORS、OAuth リダイレクト、管理者の 403、nanostore の更新、既知のバグ