アプリに二要素認証を追加する方法

アプリに二要素認証（2FA）を追加するには、利用者が認証アプリを、QRコードを読み取って連携できるようにし、パスワードの後に表示される6桁のコードを入力してもらい、そのコードが正しいと確認できたときに初めて、サーバー上で完全なセッションを作成します。2FAを有効にするときには、すべての利用者に1回限りのリカバリーコードを発行し、誰かがコードを推測できる回数を制限して、2FAを無効にするには、パスワードと現在のコードの両方を要求してください。ホスト型の認証プロバイダーを使っている場合は、自前で作る代わりに、その組み込みの多要素認証を有効にしてください。

このガイドでは、選択肢、正確な流れ、AIビルダーに与えられるプロンプト、そして2FAがあるように見えても実際には機能しないミスを扱います。この概念が初めてなら、二要素認証とはから読んでください。

始める前に：動作するログインが必要です

2FAは、既存のサインインの上に成り立ちます。次のどちらかが先に必要です。

• 自前のログイン：利用者とハッシュ化されたパスワードが、アプリのデータベースに保存されている。
• ホスト型の認証プロバイダー：利用者を代わりに管理してくれる。

まだどちらもない場合は、アプリにログインを追加する方法から始めてください。このガイドの残りの部分は、パスワードの手順がすでに動いていることを前提としています。

第2の要素を選ぶ

TOTPは、time-based one-time passwordの略で、認証アプリが使う標準規格（RFC 6238）です。サーバーと利用者のスマートフォンが秘密情報を共有し、双方が、その秘密情報と現在時刻から同じ短いコードを生成します。コードは通常30秒ごとに変わります。ネットワーク接続もSMSの送信業者も必要ありません。

パスキーは、利用者のデバイスに保存された暗号鍵を使い、パスワードを置き換えるか補完するものです。より強固ですが、自分で作るには手間がかかります。そのため、多くのアプリはTOTPから始めて、後からパスキーを追加するか、認証プロバイダーから提供を受けます。

自分で作るか、有効にするか

対応している要素や、どのプランで使えるかは、プロバイダーの最新のドキュメントで確認してください。どちらの場合も、コード生成の数学を自分で書いてはいけません。広く使われているライブラリを使ってください。

先に方針を決める

プロンプトを書く前に、次の点に答えてください。設計が変わるためです。

1. 誰が使う必要があるか？ 全員に任意、管理者やスタッフには必須、全員に必須。管理権限を持つ人に必須にするのはよくあるパターンです。ロールベースのアクセス制御を参照してください。
2. 利用者はどのくらいの頻度でコードを入力し直すか？ ログインのたびか、デバイスごとに30日間（「このデバイスを記憶する」）か。
3. どの操作で改めて確認が必要か？ メールアドレスの変更、支払い情報の変更、2FAの無効化などが良い候補です。これはステップアップ認証と呼ばれます。
4. 電話をなくしたときの手続きは何か？ リカバリーコードに加えて、あなたが実行できる手作業のフォールバックを用意します。

ステップごとの進め方：自前のログインでのTOTP 2FA

1. 正しいフィールドを保存する

各利用者には次のものが必要です。2FAが有効かどうか、TOTPの秘密情報（保存時に暗号化されていること。平文ではないこと）、有効化された日時、そしてハッシュ化して保存されたリカバリーコードの一覧です。失敗した試行の回数を数える場所も追加してください。

2. 登録

1. 利用者が設定を開き、二要素認証を有効にするをクリックします。
2. サーバーが新しい秘密情報を生成し、QRコードとして返します。スキャンできない人のために、テキストの形式も返します。
3. 利用者が認証アプリでスキャンし、現在のコードを入力します。
4. サーバーがコードを確認します。正しい場合にのみ、秘密情報を保存し、2FAを有効として記録します。
5. アプリは8〜10個のリカバリーコードを一度だけ表示し、利用者に保存するよう求めます。

4の手順が重要です。コードを確認する前に2FAを有効にすると、スキャンに失敗した人が、次回のログイン時に締め出されてしまいます。

3. 2段階目のあるログイン

1. 利用者がメールアドレスとパスワードを送信します。サーバーがそれらを確認します。
2. 2FAが有効であれば、サーバーは完全なセッションを作成しません。代わりに、短時間有効な「第2要素の待機」状態を作成します。
3. アプリがコードの入力画面を表示します。サーバーはコードを確認します。時計のずれを考慮して、少しの許容時間を設けます。
4. ここで初めて、サーバーが本物のセッションを発行します。

すべての保護されたルートとAPIエンドポイントは、この待機状態を拒否しなければなりません。ブラウザでだけ2FAの画面を隠しているなら、APIを直接呼び出すことで回避できてしまいます。

4. 制限とアラート

6桁のコードには100万通りの組み合わせがあり、制限がなければ推測できてしまいます。試行回数を制限し、失敗が繰り返された後は一定時間2段階目をロックして、利用者にメールで知らせてください。レート制限とアプリからメールを送るを参照してください。

5. リカバリーと無効化

• リカバリーコードは1回だけ使え、使ったら削除されます。
• 2FAを無効にするには、パスワードと、現在のコードまたはリカバリーコードの両方が必要です。
• リカバリーコードを再発行すると、古いコードの一覧は無効になります。
• 2FAを有効にしたり無効にしたりしたときは、必ず利用者にメールで知らせてください。

AIビルダーに与えるプロンプト

まずは中核となる流れから始めます。

既存のメールアドレスとパスワードのログインに、認証アプリ（TOTP）を使った任意の二要素認証を追加してください。よく知られたTOTPライブラリを使い、アルゴリズムを自分で書かないでください。設定画面にQRコードとテキストの秘密情報を表示し、利用者が有効なコードを入力するまで2FAを有効にしないでください。秘密情報は暗号化して保存し、設定後は二度と表示しないでください。1回限りのリカバリーコードを10個表示し、ハッシュ化して保存してください。

次に、強制の部分です。生成されたコードが最も不十分になりやすいのがここです。

サーバー側で2FAを強制してください。正しいパスワードの後、2FAが有効な利用者には、完全なセッションではなく、短時間有効な待機状態を与えてください。保護されたすべてのページとAPIルートは、この待機状態を拒否しなければなりません。コードの試行は5回までに制限し、その後は2段階目を15分間ロックして、利用者にメールで知らせてください。

次にポリシーです。

管理者アカウントには2FAを必須にしてください。2FAが無効な管理者は設定画面に誘導され、設定が完了するまで管理ダッシュボードに到達できないようにしてください。2FAを無効にする場合や、アカウントのメールアドレスを変更する場合は、パスワードと現在のコードの両方を要求してください。2FAを有効または無効にしたときは、利用者にメールで知らせてください。

最後に、エージェントに何を構築したかを説明させます。

完了した第2要素を確認しているすべてのルートを一覧にし、TOTPの秘密情報とリカバリーコードがどこに保存されていて、どのように保護されているかを説明してください。

よくある間違い

• パスワードの後にセッションを発行してしまう。 これが最も深刻なバグです。コードを確認する前に完全なセッションが存在すると、2FAは見せかけにすぎません。パスワードの段階の後で、保護されたAPIを直接呼び出してテストしてください。
• 試行回数の制限がない。 無制限に推測できるため、コードは総当たり攻撃で破られます。
• 秘密情報やリカバリーコードを平文で保存する。 データベースが漏えいすると、全員の第2要素が流出してしまいます。
• 確認する前に有効にしてしまう。 スキャンを間違えた利用者は、次回のログインで締め出されます。
• リカバリーの手段がない。 電話をなくした人のすべてが、サポートへの問い合わせや顧客の喪失になります。
• 無効化が簡単すぎる。 盗まれたセッションがコードなしで2FAを無効にできてしまうと、保護は意味を失います。
• コードがログに残る。 認証コードや秘密情報が、サーバーのログやエラーメッセージに出ないようにしてください。
• ログイン画面でだけ確認する。 パスワードのリセット、「マジックリンク」によるサインイン、ソーシャルログインも2FAを尊重しなければ、そこが回避の経路になってしまいます。

テストのチェックリスト

• 登録は、有効なコードを入力した後にのみ完了する
• 正しいパスワードはあるがコードがないログインでは、保護されたページやAPIに一切アクセスできない
• 誤ったコードは拒否される。誤ったコードが繰り返されるとロックアウトが発動し、メールが届く
• 数分前のコードは拒否される
• 各リカバリーコードは、ちょうど1回だけ使える
• 2FAを無効にするには、パスワードと現在のコードが必要
• パスワードのリセットで2FAを回避できない
• 2FAが必須の場合、2FAが無効な管理者は管理ページに到達できない
• 秘密情報とリカバリーコードは、データベースで暗号化またはハッシュ化されている
• コードや秘密情報がログに出ていない

公開前には、AIで作ったアプリのセキュリティチェックリストも完了してください。

Mythexで2FAを追加する

Mythexは、アプリのエンドユーザー向けの内蔵ログインシステムを提供していません。そのため、2FAは、選んだ認証方式の一部になります。プロジェクトのデータベースを使うご自身のメールとパスワードのログインか、多要素認証に対応したホスト型プロバイダーのいずれかです。上記のようなプロンプトでチャットに依頼してください。プロバイダーのキーは、メッセージ欄ではなく、プロジェクトのシークレットに入れてください（/secrets、プロジェクトの設定、またはエージェントが表示するシークレットのカードから追加できます）。ドキュメントのアプリにログインを追加するレシピには、開始用のプロンプトがあります。また、アプリで作るものへのセキュリティでは、キーや権限まわりの習慣を説明しています。エージェントが作業を終えたら、公開前にプレビューでチェックリストの項目をすべてテストしてください。

よくある質問