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

ユーザープールで TOTP ソフトウェアトークン MFA を設定すると、ユーザーはユーザー名とパスワードでサインインし、TOTP を使用して認証を完了します。ユーザーがユーザー名とパスワードを設定して検証した後、MFA の TOTP ソフトウェアトークンを有効化できます。アプリケーションでユーザーのサインインに Amazon Cognito でホストされた UI を使用する場合は、ユーザーはユーザー名とパスワードを送信し、追加のサインインページで 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 を要求するようにユーザープールを設定し、ユーザーがホストされた UI でアプリにサインアップすると、Amazon Cognito はユーザープロセスを自動化します。Amazon Cognito は、ユーザーに MFA メソッドの選択を促し、認証アプリを設定するための QR コードを表示し、MFA 登録を確認します。ユーザーが SMS と TOTP MFA のどちらかを選択できるようにしたユーザープールでは、Amazon Cognito もユーザーに選択肢を提示します。ホストされた UI サインアップのエクスペリエンスについて詳しくは、「新しいユーザープロファイルにサインアップする方法」を参照してください。

重要

AWS WAF ウェブ ACL がユーザープールに関連付けられていて、ウェブ ACL 内のルールが CAPTCHA を提示した場合、ホストされた UI TOTP 登録で回復不能なエラーが発生する可能性があります。CAPTCHA アクションを含み、ホストされた UI TOTP には影響しないルールを作成するには、「ホストされた UI TOTP MFA 用に AWS WAF ウェブ ACL を設定する」を参照してください。AWS WAF ウェブ ACL と Amazon Cognito の詳細については、「AWS WAF ウェブ ACL をユーザープールに関連付ける」を参照してください。

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

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

TOTP MFA 考慮事項と制約事項

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

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

   • SignUp API オペレーションまたはホストされた UI を介してユーザープールにサインアップしたユーザーが、サインアップを完了すると 1 回限りのトークンを受け取ります。

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

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

3. MFA を必要とするユーザープール内のユーザーがワンタイムアクセストークンをすでに受け取っていても TOTP MFA を設定していない場合、ユーザーは MFA を設定するまでホストされた UI でサインインできません。アクセストークンの代わりに、InitiateAuth または AdminInitiateAuth への MFA_SETUP チャレンジからの session 応答値を AssociateSoftwareToken リクエストで使用することができます。

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

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

Amazon Cognito ユーザープール API でユーザーの MFA を設定する

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

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 を非アクティブ化したことをユーザーに伝え、再度サインインするよう促します。

ホストされた UI TOTP MFA 用に AWS WAF ウェブ ACL を設定する

AWS WAF ウェブ ACL がユーザープールに関連付けられていて、ウェブ ACL 内のルールが CAPTCHA を提示した場合、ホストされた UI TOTP 登録で回復不能なエラーが発生する可能性があります。AWS WAFCAPTCHA ルールはこのようにホストされた UI の TOTP MFA にのみ影響します。SMS MFA は影響を受けません。

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

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

このエラーは、ユーザープールがバックグラウンドで行う AssociateSoftwareToken と VerifySoftwareToken API リクエストに対する応答として AWS WAF が CAPTCHA の入力を求める場合に発生します。CAPTCHA アクションを含む、ホストされた UI TOTP に影響しないルールを作成するには、ルール内の CAPTCHA アクションから AssociateSoftwareToken と VerifySoftwareToken の x-amzn-cognito-operation-name のヘッダー値を除外します。

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

AWS WAF ウェブ ACL と Amazon Cognito の詳細については、「AWS WAF ウェブ ACL をユーザープールに関連付ける」を参照してください。