two-factor-authentication-best-practices

two-factor-authentication-best-practices スキルの概要

two-factor-authentication-best-practices スキルは、Better Auth 環境に 2FA を実装するための実践ガイドです。一般的な MFA 解説ではなく、Better Auth をすでに使っている開発者が、twoFactor プラグインに合わせて TOTP アプリ、OTP 配信、バックアップコード、信頼済みデバイス、サインインフロー変更までを迷い少なく組み込むための内容に絞られています。

このスキルでできること

Better Auth を使った Access Control 向けに、安全で実運用できる 2FA フローを実装したいときに使うスキルです。プラグインの導入、サーバー側とクライアント側の正しい接続、マイグレーション実行、セットアップから検証・リカバリーまでのユーザーフロー設計を進められます。

このスキルが向いているユーザー

このスキルが特に合うのは、次のようなケースです。

• 既存アプリに MFA を追加したい Better Auth ユーザー
• 理論ではなく、実装ベースの two-factor-authentication-best-practices を必要としているチーム
• まず TOTP を軸にログイン強化を行い、その後バックアップコードや OTP 配信などのフォールバック経路も実装したい開発者

汎用プロンプトと何が違うのか

通常のプロンプトでも MFA の概念説明はできますが、このスキルは Better Auth 固有の実装情報が必要な場面で強みがあります。

• twoFactor() を使ったサーバープラグイン設定
• twoFactorClient() を使ったクライアントプラグイン設定
• マイグレーションとスキーマ確認
• 2FA がいつ正式に有効化されるかを含む有効化フロー
• サインイン時のリダイレクト処理

インストール前に知っておきたいこと

このスキルは意図的にスコープが狭く作られています。前提として、すでに Better Auth がスタックに入っていることを想定しています。ベンダー非依存の認証アーキテクチャ設計、コンプライアンス向けポリシー文書作成、MFA 製品の比較検討が目的なら、最初に選ぶ資料としては適していません。

two-factor-authentication-best-practices スキルの使い方

このスキルの導入コンテキスト

このスキルは better-auth/skills リポジトリ内の better-auth/twoFactor にあります。リポジトリ上の確認できる構成は SKILL.md のみで、補助スクリプトや追加の参照ファイルは見当たりません。つまり価値の中心は自動化ではなく、実装を直接進めるためのガイドにあります。

スキルローダーを使う環境なら、リポジトリから導入して twoFactor スキルを指定してください。手動で確認する場合は、次のファイルを開きます。

• better-auth/twoFactor/SKILL.md

最初に読むべきファイル

アプリのコードを触る前に、まず SKILL.md を読みます。このスキルでは、ユーザーが最も気にする判断材料がそのファイルにまとまっています。

• サーバー設定
• クライアント設定
• マイグレーション手順
• 有効化フロー
• TOTP 検証時の挙動

単一ファイルを最初に読むだけで適合性をかなり早く判断できる、珍しいタイプのスキルです。

このスキルに最低限必要な入力

two-factor-authentication-best-practices スキルから実用的な出力を得るには、少なくとも次を渡してください。

• Better Auth サーバー設定ファイルのパス
• Better Auth クライアント設定ファイルのパス
• TOTP のみか、TOTP + email/SMS OTP か
• ユーザーテーブルの状態とマイグレーション状況
• セットアップ、チャレンジ、バックアップコード、信頼済みデバイスに関する希望 UX

これらがないと、どうしても出力が一般論に寄りがちです。

基本のセットアップ手順

このスキルが示す実践的なセットアップの流れは次のとおりです。

1. Better Auth のサーバー設定に twoFactor() を追加する
2. issuer を設定する
3. クライアント設定に twoFactorClient() を追加する
4. npx @better-auth/cli migrate を実行する
5. ユーザーテーブルに期待される 2FA シークレット用カラムがあることを確認する

このマイグレーション確認は重要です。導入失敗の多くはプラグイン自体の問題ではなく、実際にはスキーマ不一致が原因だからです。

実装の軸になるサーバー側の例

このスキルでは、サーバー設定の中心として次のような形を置いています。

import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";

export const auth = betterAuth({
  appName: "My App",
  plugins: [
    twoFactor({
      issuer: "My App",
    }),
  ],
});

実運用で特に重要なのは issuer です。これは認証アプリ上の表示名に影響し、セットアップ時のユーザー信頼にも直結します。

クライアント側の例とリダイレクト処理

プラグイン導入と同じくらい、クライアントフローも重要です。

import { createAuthClient } from "better-auth/client";
import { twoFactorClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [
    twoFactorClient({
      onTwoFactorRedirect() {
        window.location.href = "/2fa";
      },
    }),
  ],
});

Access Control 向けの two-factor-authentication-best-practices では、リダイレクト処理を単なる仕上げの UI と見なしてはいけません。これは認証フローの一部です。チャレンジ画面をどこに置くか、その画面がどんな状態を受け取る必要があるかを早い段階で決めておくべきです。

このスキルにうまく依頼する方法

弱い依頼例:

• "Help me add 2FA"

強い依頼例:

• "I use Better Auth in a React app. My server config is in src/lib/auth.ts and my client auth setup is in src/lib/auth-client.ts. I want TOTP with backup codes, a /settings/security enrollment page, a /2fa challenge route, and a migration checklist. Show exact code changes and call out anything that can break the flow."

後者のように書くと、スキルが広い助言ではなく、そのまま実装に入れるレベルの出力を返しやすくなります。

ざっくりした要件を完全なプロンプトにする方法

より良い two-factor-authentication-best-practices 活用のために、次の形で整理すると効果的です。

• 現在のスタック: フレームワーク、Better Auth 関連ファイルの場所
• 欲しい認証要素: TOTP、email OTP、SMS OTP、バックアップコード
• UX 上の要点: 登録ページ、チャレンジルート、リカバリーフロー
• セキュリティルール: パスワード再確認、信頼済みデバイス、セッション挙動
• 出力形式: patch、checklist、code snippets、review notes

例:

Apply two-factor-authentication-best-practices to my Better Auth setup.
Server file: `server/auth.ts`
Client file: `web/auth-client.ts`
Need: TOTP enrollment, backup codes, trusted-device option, redirect to `/auth/2fa`
Also include migration verification and note when `twoFactorEnabled` becomes true.

ミスを減らすワークフロー

失敗しにくい進め方は次の順番です。

1. まず 2FA なしで Better Auth が正常動作していることを確認する
2. サーバープラグインを追加する
3. クライアントプラグインとリダイレクト処理を追加する
4. マイグレーションを実行する
5. スキーマ変更を確認する
6. 登録 UI を実装する
7. 最初の検証フローをテストする
8. バックアップコードの表示・保管 UX を追加する
9. サインイン時のチャレンジとリカバリーパスをテストする

この順番には意味があります。マイグレーションやフロー接続より先に UI を作り込むと、本当の破綻ポイントが見えにくくなりがちです。

多くのチームが見落とす重要な挙動

このスキルは重要な挙動を明示しています。twoFactorEnabled は、最初の TOTP 検証が成功するまで true になりません。これは次の点に影響します。

• オンボーディングの分岐ロジック
• 登録開始直後の UI 状態
• 監査ログ
• QR コードを読み取ったものの、検証完了まで進まなかったユーザーへのサポート対応

この種の実装ディテールこそ、汎用的な MFA プロンプトよりこのスキルが役立つ理由です。

このスキルが自動化しないこと

このスキルのリポジトリパスには、同梱スクリプト、ルール、補助ファイルはありません。そのため、ターンキーなインストーラーではなく、高密度な実装ガイドとして扱うべきです。以下は引き続き自分で対応する必要があります。

• 利用中フレームワークに合わせたコード調整
• QR コード表示 UI の実装
• バックアップコードの表示方法と確認 UX の設計
• 信頼済みデバイスとリカバリー挙動の自アプリ上での検証

two-factor-authentication-best-practices スキル FAQ

このスキルは Better Auth 専用ですか？

はい。これは Better Auth の twoFactor プラグインと関連するクライアントプラグインの使い方に特化した two-factor-authentication-best-practices ガイドです。Auth.js、Firebase Auth、Cognito、独自認証基盤を使っている場合は、別の資料を選んでください。

初心者にも向いていますか？

Better Auth がすでに動いている前提なら、初心者でも使いやすい内容です。ただし、認証全般、データベース、マイグレーション運用までを一から学ぶための入門資料ではありません。

TOTP だけを扱っていますか？

いいえ。スキル説明には email/SMS 経由の OTP、バックアップコード、信頼済みデバイス、サインインフロー処理も含まれています。ただし、見えているセットアップ例は明確に TOTP 中心なので、最も分かりやすく進めやすいのは TOTP 実装だと考えておくとよいです。

どんな場合はこのスキルを使わないほうがよいですか？

次のような場合は、このスキルは見送るのが適切です。

• Better Auth を使っていない
• 実装支援ではなく製品比較が目的
• コードを伴わない広義の two-factor-authentication-best-practices ポリシーガイドが欲しい
• Better Auth の 2FA プラグインフローではなく、WebAuthn や passkeys を主軸にしたい

AI モデルに直接聞くより優れていますか？

Better Auth 固有の 2FA 実装という意味では、多くの場合こちらのほうが有利です。汎用モデルだと Better Auth のプラグイン API や有効化挙動に合わない MFA パターンを提案してしまうことがあります。このスキルは、使うべき実装プリミティブを正しい範囲に絞り込んでくれます。

Access Control 設計にも役立ちますか？

はい、スコープ内であれば有用です。Access Control 向けの two-factor-authentication-best-practices という観点では、サインインやアカウント保護に対して step-up security を適用したいケースで特に力を発揮します。一方で、RBAC や ABAC のようなより広い認可モデル設計にはあまり向いていません。

two-factor-authentication-best-practices スキルを改善する方法

実際のファイルパスと現在のコード構成を渡す

出力品質を最も早く上げる方法は、現在使っているサーバー側・クライアント側の認証ファイルをそのまま共有することです。そうすれば、import 構成、plugins 配列の形、ルーティングパターンに合った差分を返しやすくなります。

要素構成とリカバリーポリシーを最初に明示する

欲しいフローを具体的に指定してください。

• TOTP のみ
• TOTP + バックアップコード
• TOTP + email/SMS フォールバック
• 信頼済みデバイス対応
• 登録前のパスワード再確認

これらの選択で出力内容は大きく変わります。省略すると、スキル側で推測するしかありません。

マイグレーションと検証手順を明示的に要求する

よくある失敗は、コード断片だけ受け取って運用チェックが抜けることです。次を明示して依頼すると安全です。

• migration command
• schema verification step
• expected column presence
• test cases for enrollment and sign-in challenge

こうすることで、two-factor-authentication-best-practices の導入プロセスをより安全に進められます。

セットアップと UX を分けて出力させる

次のようにセクション分けして返すよう依頼してください。

1. plugin installation
2. schema changes
3. enrollment UI
4. challenge flow
5. backup/recovery handling
6. test checklist

これで、コード、ルーティング、ポリシー助言が一緒くたになる回答を避けやすくなります。

よくある失敗パターンに注意する

問題が起きる典型例は、次のようなものです。

• クライアントプラグインを入れ忘れる
• リダイレクトロジックがない
• マイグレーションを実行していない
• 初回検証前に 2FA が有効になっていると思い込む
• QR コード表示だけ作ってバックアップコード処理がない
• 信頼済みデバイスを UI だけの機能として扱ってしまう

最初の回答にこうした抜けがあれば、フロー全体を見直す形で修正レビューを依頼してください。

初回ドラフトの後にもう一段詰める

スキルから実装プランが返ってきたら、次のように追加で詰めると完成度が上がります。

• "What edge cases are missing?"
• "Review this flow for lockout risk."
• "Add test scenarios for failed TOTP, backup code use, and device trust."
• "Rewrite this for my exact route structure."

実際には、この 2 回目のやり取りでデプロイ前提の品質に届くことがよくあります。