TOTP ソフトウェアトークン MFA

ユーザープールで TOTP ソフトウェアトークン MFA を設定すると、ユーザーはユーザー名とパスワードでサインインし、TOTP を使用して認証を完了します。ユーザーがユーザー名とパスワードを設定して検証した後、MFA の TOTP ソフトウェアトークンを有効化できます。アプリが Amazon Cognito マネージドログインを使用してユーザーをサインインする場合、ユーザーはユーザー名とパスワードを送信し、追加のサインインページで TOTP パスワードを送信します。

ユーザープールの TOTP MFA は、Amazon Cognito コンソールでアクティブ化することも、Amazon Cognito API オペレーションを使用してもかまいません。ユーザープールレベルでは、SetUserPoolMfaConfig を呼び出すことで、MFA を設定して TOTP MFA を有効化できます。

注記

TOTP ソフトウェアトークン MFA がユーザープールに対して有効になっていない場合は、Amazon Cognito で、ユーザーをトークンに関連付けたり、トークンで検証することができません。この場合、ユーザーはSoftwareTokenMFANotFoundException説明による例外Software Token MFA has not been enabled by the userPoolを受診します。ソフトウェアトークン MFA が後にユーザープールに対して非アクティブ化された場合、以前に TOTP トークンを関連付けて検証したユーザーは、引き続き MFA で使用することができます。

ユーザーの TOTP の設定には複数のステップが伴います。ユーザーはシークレットコードを受け取り、ワンタイムパスワードを入力して、このコードを検証します。次に、ユーザーの TOTP MFA を有効にするか、ユーザーの優先 MFA メソッドとして TOTP を設定することができます。

TOTP MFA を要求するようにユーザープールを設定し、ユーザーがマネージドログインでアプリにサインアップすると、Amazon Cognito はユーザープロセスを自動化します。Amazon Cognito は、ユーザーに MFA メソッドの選択を促し、認証アプリを設定するための QR コードを表示し、MFA 登録を確認します。ユーザーが SMS と TOTP MFA のどちらかを選択できるようにしたユーザープールでは、Amazon Cognito もユーザーに選択肢を提示します。

重要

ユーザープールに関連付けられた AWS WAF ウェブ ACL があり、ウェブ ACL のルールが CAPTCHA を提示すると、マネージドログイン TOTP 登録で回復不可能なエラーが発生する可能性があります。CAPTCHA アクションを持ち、マネージドログイン TOTP に影響を与えないルールを作成するには、「」を参照してくださいマネージドログイン TOTP MFA 用の AWS WAF ウェブ ACL の設定。 AWS WAF ウェブ ACL と Amazon Cognito の詳細については、「AWS WAF ウェブ ACL とユーザープールの関連付け」を参照してください。

AWS SDK と Amazon Cognito ユーザープール API を使用してカスタムビルド UI に TOTP MFA を実装するには、「」を参照してくださいユーザーの TOTP MFA の設定。

MFA をユーザープールに追加するには、「ユーザープールに MFA を追加します」を参照してください。

TOTP MFA 考慮事項と制約事項

1. Amazon Cognito は、TOTP コードを生成する認証システムアプリケーションを介してソフトウェアトークン MFA をサポートします。Amazon Cognito はハードウェアベースの MFA をサポートしていません。

2. TOTP を設定していないユーザーに対してユーザープールが TOTP を必要とする場合、ユーザーはワンタイムアクセストークンを受け取り、アプリはそれを使ってユーザーの TOTP MFA を有効化することができます。後続のサインイン試行は、ユーザーが追加の TOTP サインイン要素を登録するまで失敗します。

   • SignUp API オペレーションまたはマネージドログインを使用してユーザープールにサインアップするユーザーは、ユーザーがサインアップを完了すると 1 回限りのトークンを受け取ります。

   • ユーザーを作成し、ユーザーが初期パスワードを設定すると、Amazon Cognito はマネージドログインからユーザーに 1 回限りのトークンを発行します。ユーザーに永続的なパスワードを設定すると、ユーザーが最初にサインインしたときに Amazon Cognito が 1 回限りのトークンを発行します。

   • Amazon Cognito は、InitiateAuth または AdminInitiateAuth API オペレーションでサインインする管理者が作成したユーザーには 1 回限りのトークンを発行しません。ユーザーが初期パスワードの設定のチャレンジに成功した後、またはユーザーに永続的なパスワードを設定すると、Amazon Cognito はすぐに MFA の設定をユーザーに要求します。

3. MFA を必要とするユーザープールのユーザーが既に 1 回限りのアクセストークンを受け取っているが、TOTP MFA を設定していない場合、ユーザーは MFA を設定するまでマネージドログインでサインインできません。アクセストークンの代わりに、InitiateAuth または AdminInitiateAuth への MFA_SETUP チャレンジからの session 応答値を AssociateSoftwareToken リクエストで使用することができます。

4. ユーザーが TOTP を設定した場合は、TOTP が後でユーザープールに対して無効にされた場合でも、その TOTP を MFA に使用できます。

5. Amazon Cognito は、HMAC-SHA1 ハッシュ関数を使用してコードを生成する認証アプリケーションからの TOTP のみを受け入れます。SHA-256 ハッシュで生成されたコードは Code mismatch エラーを返します。

ユーザーの TOTP MFA の設定

ユーザーが最初にサインインすると、アプリはワンタイムアクセストークンを使用して TOTP プライベートキーを生成し、テキスト形式または QR コード形式でユーザーに提示します。ユーザーは認証システムアプリケーションを設定し、その後のサインイン試行の TOTP を提供します。アプリまたはマネージドログインは、MFA チャレンジレスポンスで TOTP を Amazon Cognito に提示します。

状況によっては、マネージドログインにより、新しいユーザーに TOTP 認証を設定するように求められます。詳細については、「」を参照してくださいユーザー実行時の MFA ロジックの詳細。

TOTP ソフトウェアトークンを関連付ける

TOTP トークンを関連付けるには、ワンタイムパスワードで検証する必要のあるシークレットコードをユーザーに送信する必要があります。トークンの関連付けには 3 つのステップが必要です。

1. ユーザーが TOTP ソフトウェアトークン MFA を選択したら、AssociateSoftwareToken を呼び出して、一意に生成された共有シークレットキーコードをユーザーアカウントに返します。AssociateSoftwareToken は、アクセストークンまたはセッション文字列を使用して承認できます。

2. アプリは、プライベートキーまたはプライベートキーから生成した QR コードをユーザーに提示します。ユーザーは、キーを Google Authenticator などの TOTP 生成アプリに入力する必要があります。libqrencode を使用して、QR コードを生成できます。

3. ユーザーがキーを入力するか、Google Authenticator などの認証システムアプリケーションに QR コードをスキャンすると、アプリがコードの生成を開始します。

TOTP トークンを検証

次に、TOTP トークンを検証します。以下のように、ユーザーからサンプルコードをリクエストし、Amazon Cognito サービスに提供して、ユーザーが TOTP コードを正常に生成していることを確認します。

1. アプリは、ユーザーが認証システムアプリケーションを適切に設定したことを示すコードの入力をユーザーに促します。

2. ユーザーの認証システムアプリケーションは、一時的なパスワードを表示します。認証システムアプリケーションは、ユーザーに与えたシークレットキーに基づいてパスワードを作成します。

3. ユーザーは一時パスワードを入力します。アプリは、VerifySoftwareToken API リクエストで一時パスワードを Amazon Cognito に渡します。

4. Amazon Cognito は、ユーザーに関連付けられたシークレットキーを保持し、TOTP を生成し、ユーザーが指定したシークレットキーと比較します。一致した場合は、VerifySoftwareToken は SUCCESS レスポンスを返します。

5. Amazon Cognito は TOTP 要素をユーザーに関連付けます。

6. VerifySoftwareToken オペレーションが ERROR レスポンスを返した場合は、ユーザーのクロックが正しいこと、およびリトライの最大回数を超えていないことを確認します。Amazon Cognito は、試行の前後 30 秒以内の TOTP トークンを受け入れ、マイナークロックスキューを考慮します。問題が解決したら、VerifySoftwareToken オペレーションをもう一度試してください。

TOTP MFA でのサインイン

この時点で、ユーザーは時間ベースのワンタイムパスワードを使用したサインインを行います。以下はその手順です。

1. ユーザーはユーザー名とパスワードを入力してクライアントアプリにサインインします。

2. TOTP MFA チャレンジが呼び出され、アプリが一時パスワードを入力するプロンプトをユーザーに表示します。

3. ユーザーは、関連付けられた TOTP 生成アプリから一時パスワードを取得します。

4. ユーザーが TOTP コードをクライアントアプリに入力します。アプリは、コードを検証するよう Amazon Cognito サービスに通知します。サインインごとに、RespondToAuthChallenge を呼び出して新しい TOTP 認証チャレンジに対するレスポンスを取得する必要があります。

5. Amazon Cognito によってトークンが検証されると、サインインが成功し、ユーザーは認証フローを続行します。

TOTP トークンを削除

最後に、アプリは TOTP 設定を非アクティブ化することをユーザーに許可する必要があります。現在、ユーザーの TOTP ソフトウェアトークンを削除することはできません。ユーザーのソフトウェアトークンを置き換えるには、新しいソフトウェアトークンを関連付けて検証します。ユーザーの TOTP MFA を無効にするには、SetUserMFAPreference を呼び出して、MFA を使用しないか、SMS MFA のみを使用するようにユーザーを変更します。

1. MFA をリセットしたいユーザーのためのインターフェイスをアプリケーション内に作成します。このインターフェイスでユーザーにパスワードの入力を求めます。

2. Amazon Cognito が TOTP MFA チャレンジを返す場合は、ユーザーの MFA 設定を SetUserMFAPreference で更新します。

3. アプリで、MFA を非アクティブ化したことをユーザーに伝え、再度サインインするよう促します。

マネージドログイン TOTP MFA 用の AWS WAF ウェブ ACL の設定

ユーザープールに関連付けられた AWS WAF ウェブ ACL があり、ウェブ ACL のルールが CAPTCHA を示している場合、マネージドログインとマネージドログイン TOTP 登録で回復不可能なエラーが発生する可能性があります。 AWS WAF CAPTCHA ルールは、マネージドログインとクラシックホスト UI の TOTP MFA にのみ影響します。SMS MFA は影響を受けません。

CAPTCHA ルールにより、ユーザーが TOTP MFA の設定を完了できない場合、Amazon Cognito は次のエラーを表示します。

Request not allowed due to WAF captcha. (WAF captcha によりリクエストは許可されていません。)

このエラーは、 がユーザープールがバックグラウンドで行う AssociateSoftwareToken および VerifySoftwareToken API リクエストに応答して CAPTCHA AWS WAF をプロンプトすると発生します。マネージドログインページの TOTP に影響を与えない CAPTCHA アクションを持つルールを作成するには、ルールの CAPTCHA アクションVerifySoftwareTokenから AssociateSoftwareTokenおよび のx-amzn-cognito-operation-nameヘッダー値を除外します。

次のスクリーンショットは、x-amzn-cognito-operation-nameヘッダー値が AssociateSoftwareTokenまたは でないすべてのリクエストに CAPTCHA アクションを適用する AWS WAF ルールの例を示していますVerifySoftwareToken。

AWS WAF ウェブ ACLs「」を参照してくださいAWS WAF ウェブ ACL とユーザープールの関連付け。 Amazon Cognito