多要素認証の構成

このページでは、メールで確認コードを送信してユーザーの ID 確認を行う多要素認証（MFA）の構成方法について説明します。この機能を使用すると、ユーザーがアカウントに関連付けられたメールアドレスを所有していることを確認できます。MFA は、クレデンシャルスタッフィングやアカウントの乗っ取り（ATO）からユーザーを保護するのに役立ちます。

MFA はスコアベースのキーで使用できますが、チェックボックスキーでは使用できません。

MFA の構成プロセスについて

reCAPTCHA Enterprise の MFA 機能は、通常の reCAPTCHA Enterprise ワークフロー上に実装されています。

MFA ワークフローの概要は次のとおりです。

ウェブサイト上の重要なワークフローを計測する。
execute() 呼び出しで返されるトークンと MFA パラメータを使用して評価を作成し、MFA requestToken を取得します。
使用するチャネルに従って requestToken で MFA チャレンジをトリガーします（メールのみ対応）。
ウェブサイトでエンドユーザーが入力した PIN を確認します。
確認リクエストで返されるトークンを使用して、新しい評価を作成します。

準備

reCAPTCHA Enterprise の環境を準備します。
MFA はセキュリティ審査後にアクセスできます。この機能へのサイトのオンボーディングについては、Google の営業チームまでお問い合わせください。次のオンボーディング情報を営業チームに提供してください。
- Google Cloud プロジェクト番号
- オンボーディングする reCAPTCHA キー
- 平均 QPS（1 秒あたりのメールメッセージ数）
- ピーク QPS（1 秒あたりのメールメッセージ数）
- メール MFA、送信者アドレス、テストに必要なメールアドレスまたはドメイン
MFA のメール確認機能を有効にする場合は、次の手順に沿って操作します。

注: Google ではメール配信の信頼性を向上させるためにさまざまな対策を行っていますが、エンドユーザーによるメッセージの受信を妨げる要因は多数あります。MFA と統合する場合は、この要因を考慮する必要があります。たとえば、エンドユーザーがカスタマーサポートに連絡してアカウントを確認できるようにすることを検討する必要があります。
1. Google Cloud コンソールで、[reCAPTCHA Enterprise] ページに移動します。
  
  [reCAPTCHA Enterprise] に移動
2. リソースセレクタにプロジェクトの名前が表示されていることを確認します。
  
  プロジェクトの名前が表示されない場合は、リソースセレクタをクリックしてプロジェクトを選択します。
3. [設定] をクリックします。
4. [多要素認証] ペインで、[構成] をクリックします。
5. [多要素認証を構成] ダイアログで、次の操作を行います。
  1. メール確認を有効にするには、[メールを有効にする] 切り替えボタンをクリックします。
  2. [送信者名] ボックスに名前を入力します。
  3. [送信者のメールアドレス] ボックスに、メールアドレスを入力します。
6. [保存] をクリックします。
注: デフォルトでは、送信されるメールは汎用的で、ブランド化されていません。このメールのブランド化やカスタマイズが必要な場合は、担当技術スペシャリストにお問い合わせください。
スコアベースのキーを使用して、ウェブサイトで reCAPTCHA Enterprise を設定する。

ウェブサイト上の重要なワークフローを計測する

リスク評価の execute() 関数を使用して、reCAPTCHA Enterprise に必要な情報を渡します。execute() 関数は、トークンの生成時に解決される Promise を返します。

次のサンプルコードに示すように、execute() 関数に twofactor パラメータを追加します。

  grecaptcha.enterprise.execute(KEY_ID, {
    action: 'login',
    twofactor: true
  }).then(token => {
    // Handle the generated token.
  });

KEY_ID は、ウェブサイト用に作成したスコアベースのキーに置き換えます。

評価の作成

execute() 関数によって生成されたトークンで、バックエンドの reCAPTCHA Enterprise クライアントライブラリか REST API を使用して評価を作成します。

このドキュメントでは、REST API を使用して MFA の評価を作成する方法について説明します。クライアントライブラリを使用して評価を作成する方法については、ウェブサイトの評価を作成するをご覧ください。

評価を作成する前に、次のことを行います。

reCAPTCHA Enterprise への認証を設定します。

選択する認証方法は、reCAPTCHA Enterprise が設定されている環境によって異なります。次の表は、適切な認証方法とサポートされている認証インターフェースを選択するのに役立ちます。

環境	インターフェース	認証方法
Google Cloud	REST クライアントライブラリ	接続されたサービスアカウントを使用する。
オンプレミスまたは別のクラウドプロバイダ	REST	API キーまたは　Workload Identity 連携を使用します。 API キーを使用する場合は、API キーの制限を適用して API キーを保護することをおすすめします。
クライアントライブラリ	以下の対象を使用します。 Python または Java の場合は、API キーまたは Workload Identity 連携を使用します。 API キーを使用する場合は、API キーの制限を適用して API キーを保護することをおすすめします。他の言語の場合は、Workload Identity 連携を使用します。

環境

インターフェース

認証方法

Google Cloud

REST
クライアントライブラリ

接続されたサービスアカウントを使用する。

オンプレミスまたは別のクラウドプロバイダ

REST

API キーまたは　Workload Identity 連携を使用します。

API キーを使用する場合は、API キーの制限を適用して API キーを保護することをおすすめします。

クライアントライブラリ

以下の対象を使用します。

Python または Java の場合は、API キーまたは Workload Identity 連携を使用します。
API キーを使用する場合は、API キーの制限を適用して API キーを保護することをおすすめします。
他の言語の場合は、Workload Identity 連携を使用します。

ユーザーが頻繁に変更しない固定のアカウント ID accountId を選択し、 projects.assessments.create メソッドで評価を指定します。この固定アカウント ID は、同じユーザーに関連するすべてのイベントで同じ値を持つ必要があります。アカウント ID として以下を指定できます。
ユーザー識別子

すべてのアカウントを固定のユーザー名、メールアドレス、電話番号に一意に関連付けることができる場合は、accountId として使用できます。このようなクロスサイト ID（サイト間で再利用できる ID）を指定すると、reCAPTCHA Enterprise がこの情報を使用して、不正なアカウント ID にフラグを立て、クロスサイトモデルに基づいてユーザーアカウントの保護を強化し、これらの識別子に関連するクロスサイト不正行為のパターンに関する知識を活用します。

また、各アカウントに一意に関連付けられた内部ユーザー ID がある場合は、accountId として指定できます。
ハッシュ化または暗号化

各アカウントに一意に関連付けられた内部ユーザー ID がない場合は、任意の固定 ID を不透明なサイト固有のアカウント ID に変換できます。この ID は、reCAPTCHA Enterprise のアカウント保護がユーザーアクティビティパターンを理解し、異常な動作を検出するために引き続き必要ですが、他のサイト間で共有されません。

暗号化またはハッシュ化を使用して、reCAPTCHA Enterprise に送信する前に、安定したアカウント ID を選択し、不透明にします。
- 暗号化（推奨）:安定した暗号テキストを生成する決定的な暗号化方法を使用して、アカウント ID を暗号化します。詳細な手順については、データを確定的に暗号化するをご覧ください。ハッシュ化ではなく対称暗号化を選択した場合、ユーザー ID と対応する不透明なユーザー ID とのマッピングを維持する必要はありません。reCAPTCHA Enterprise から返される不透明な識別子を復号して、ユーザー ID に変換します。
- ハッシュ化: SHA256-HMAC メソッドを使用して、任意のカスタムソルトでアカウント ID をハッシュ化することをおすすめします。ハッシュは一方向のため、生成されたハッシュとユーザー ID の間のマッピングを維持する必要があります。これにより、元のアカウントに返されるハッシュ化されたアカウント ID をマッピングできます。

accountId パラメータとエンドポイント（メールアドレスなど）を追加し、projects.assessments.create メソッドの評価で確認します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクト ID。
TOKEN: grecaptcha.enterprise.execute() 呼び出しから返されたトークン。
KEY_ID: ウェブサイトにインストールするスコアベースのキー。
ACCOUNT_ID: ウェブサイト固有のユーザーアカウントの識別子。
EMAIL_ID: 確認リクエストをトリガーするメールアドレス。

HTTP メソッドと URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

リクエストの本文（JSON）:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userInfo": {
       "accountId": "ACCOUNT_ID"
    }
  }
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "EMAIL_ID",
    }]
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。


{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "",
    }],
    "latestVerificationResult": "RESULT_UNSPECIFIED"
  }
}

評価には、トークンを発行したデバイス（存在する場合）の特定のエンドポイントについて、確認が最後に成功した日時が記載されています。また、エンドポイントごとに 1 つの requestToken フィールドも存在します。このフィールドには暗号化された文字列が含まれます。そのエンドポイントで MFA チャレンジをトリガーする場合は、この暗号化された文字列をウェブページに送り返す必要があります。リクエストトークンは 15 分間有効です。

推奨される対応

プロジェクトで reCAPTCHA Enterprise アカウント防御を有効にしている場合、評価レスポンスには、MFA に関連する情報に加えて、アカウント防御に関連する情報が含まれます。recommended_action フィールドには、MFA チャレンジをトリガーする前に実行できるアクションが表示されます。

次の例は、推奨されるアクションとして MFA をスキップするサンプル評価を示しています。

{
  [...],
  "accountDefenderAssessment": {
    labels: ["PROFILE_MATCH"],
    "recommended_action": "SKIP_2FA"
  }
}

recommended_action フィールドは次のいずれかの値になります。

値	説明
`RECOMMENDED_ACTION_UNSPECIFIED`	アカウント防御がこのリクエストについて判断できなかったことを示します。
`SKIP_2FA`	アカウント防御がこの評価の MFA をスキップしても安全であると判断したことを示します。これは通常、このデバイスのサイトに対してユーザーが最近確認されたことを意味します。
`REQUEST_2FA`	ユーザーの MFA チャレンジをトリガーすることを示します。詳細については、アカウント防御の評価レスポンスをご覧ください。

ウェブサイトで MFA チャレンジをトリガーする

評価に含まれた情報に基づいてユーザーへのチャレンジを行うには、MFA を送信します。requestToken確認するエンドポイントからウェブページに戻ります。

challengeAccount() を呼び出して MFA チャレンジをトリガーします。 challengeAccount() 関数は、チャレンジの完了後に解決される Promise、またはエラーやタイムアウトが発生した場合は拒否される Promise を返します。完了すると、更新された情報を含む新しいトークンが生成され、評価のために送信されます。

MFA チャレンジをトリガーするには、次のようにします。

MFA インテグレーションをテストします。

次の値を指定して、challengeAccount() を呼び出し、MFA チャレンジをトリガーします。
- KEY_ID: ウェブサイトにインストールするスコアベースのキー。
- REQUEST_TOKEN_FROM_ASSESSMENT: 評価レスポンスの requestToken フィールドの値。
- CONTAINER_HTML_COMPONENT_ID: 確認チャレンジをレンダリングする必要がある HTML コンポーネントの ID。このパラメータを指定しない場合、チャレンジはページ上のオーバーレイにレンダリングされます。
次の例では、challengeAccount()　の呼び出しで MFA チャレンジをトリガーする方法を示します。
```
grecaptcha.enterprise.challengeAccount(KEY_ID, {
  'account-token': REQUEST_TOKEN_FROM_ASSESSMENT,
  'container': CONTAINER_HTML_COMPONENT_ID
}).then(newToken => {
  // Handle the new token.
});
```
challengeAccount() リクエストが成功すると、受信した PIN を入力するための HTML コンポーネントが表示されます。正しい　PIN が入力されると、newToken 変数が、バックエンドで作成された評価を通じて検証される検証トークンを含むチェーン関数に渡されます。

注: このデフォルトのチャレンジ UI には、本番環境に適したエラー処理や他のカスタマイズ機能がありません。したがって、インテグレーションフェーズ以外では、このプロトタイプを使用しないことをおすすめします。

検証ハンドルを作成し、次のパラメータを使用してチャレンジを開始します。

// Initialize verification handle.
const verificationHandle = grecaptcha.enterprise.eap.initTwoFactorVerificationHandle(
  KEY_ID,
  REQUEST_TOKEN_FROM_ASSESSMENT
);

// Call the challenge API.
verificationHandle.challengeAccount().then(
  (challengeResponse) => {
    if (challengeResponse.isSuccess()) {
      // Handle success: This means displaying an input for the end user to
      // enter the PIN that they received and then call the `verifyAccount(pin)`
      // method.
    } else {
      // Handle API failure
    }
  });

ウェブページから MFA コードを確認する

エンドユーザーから PIN を取得したら、PIN が正しいかどうかを検証する必要があります。

PIN を検証するには、エンドユーザーが入力した PIN を使用して verificationHandle.verifyAccount() を呼び出します。

verificationHandle.verifyAccount(pin).then(
  (verifyResponse) => {
    if (verifyResponse.isSuccess()) {
      // Handle success: Send the result of `verifyResponse.getVerdictToken()`
      // to the backend in order to determine if the code was valid.
    } else {
      // Handle API failure
    }
  },
  (error) => {
    // Handle other errors
  }
);

新しい評価を作成する

accountId と endpoints を使用して新しい評価を作成します。手順については、MFA の評価を作成するをご覧ください。

クライアントでワークフローが完了すると、新しいトークンが返されます。これを使用して、トリガーした確認の判定を取得できます。評価には、最新の成功した確認に関する最新のタイムスタンプと、成功結果のステータスが含まれます。

次の例は、クライアントから取得した新しいトークンを使用して新しい評価をリクエストした場合に受け取る、サンプル評価を示します。

{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "2020-03-23 08:27:12 PST",
    }],
    "latestVerificationResult": "SUCCESS_USER_VERIFIED"
  }
}

latestVerificationResult フィールドには、下の表のように異なるステータスが表示されます。

検証の結果のステータス	説明
SUCCESS_USER_VERIFIED	ユーザーは正しく検証されました。
ERROR_USER_NOT_VERIFIED	ユーザーの本人確認に失敗しました。
ERROR_SITE_ONBOARDING_INCOMPLETE	サイトが正しく導入されていません。
ERROR_RECIPIENT_NOT_ALLOWED	この受信者は、メールの送信が承認されていません（テスト中のみ）。
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED	この宛先は、短期間にあまりにも多くの確認コードを受け取っています。
ERROR_CUSTOMER_QUOTA_EXHAUSTED	利用可能な MFA の割り当てを超えました。
ERROR_CRITICAL_INTERNAL	システムの内部エラーにより、確認が完了していません。
RESULT_UNSPECIFIED	最新の確認に関する情報はありません（未確認）。

次のステップ

reCAPTCHA Enterprise アカウント防御を使用して、アカウント関連の不正行為を検出して防止する