reCAPTCHA Enterprise を有効にする

このドキュメントでは、Identity Platform と reCAPTCHA Enterprise の統合を使用して、ユーザーのセキュリティを強化する方法について説明します。この機能により、スパムや不正行為などの不正行為に対するアプリの復元力が高まります。

Identity Platform と reCAPTCHA Enterprise の統合により、ユーザーリクエストを検証する reCAPTCHA Enterprise の評価を、ユーザーに代わって作成します。価格については、reCAPTCHA Enterprise の料金をご覧ください。

概要

Identity Platform と reCAPTCHA Enterprise の統合を構成すると、ユーザーに代わって、Identity Platform がプロジェクトのスコアベースの reCAPTCHA Enterprise サイトキーをプロビジョニングします。ユーザーが次のいずれかの操作を使用してアプリまたはサイトにアクセスすると、クライアント SDK は reCAPTCHA Enterprise を読み込みます。

オペレーション	メソッド
メールアドレスとパスワードによるログイン	`signInWithPassword`
メールアドレスとパスワードの登録	`signUpPassword`
メールリンクによるログイン	`getOobCode`
パスワードの再設定	`getOobCode`

reCAPTCHA は、構成とリスク許容度に基づいてリクエストのリスクを評価するリスクシグナルを Identity Platform に提供します。

詳細については、reCAPTCHA Enterprise の概要をご覧ください。

始める前に

ユーザーのメールログインを構成する。

サービスアカウントを作成する

reCAPTCHA Enterprise を有効にする前に、reCAPTCHA を使用するプロジェクトごとにサービスアカウントを作成し、各サービスアカウントに reCAPTCHA Enterprise へのアクセス権を付与する必要があります。これにより、Identity Platform がユーザーに代わって reCAPTCHA キーを管理できます。

サービスアカウントを作成するには、次のようにします。

Google Cloud CLI を使用して、サービスアカウントを作成します。
```
gcloud beta services identity create \
    --service=identitytoolkit.googleapis.com \
    --project=PROJECT_ID
```
PROJECT_ID をそのプロジェクトの ID に置き換えます。
サービスアカウントに reCAPTCHA Enterprise へのアクセス権を付与します。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
    --role=roles/identitytoolkit.serviceAgent
```
以下を置き換えます。
- PROJECT_ID: プロジェクト ID
- PROJECT_NUMBER: プロジェクトアカウント番号

reCAPTCHA Enterprise を有効にする

reCAPTCHA には、ユーザーを保護するための 2 つのモードがあります。

監査: 有効にすると、Identity Platform は、1 つ以上の reCAPTCHA Enterprise キーをプロジェクトに作成し、それらはリクエストをブロックせずに Identity Platform API へのトラフィックを評価するために使用されます。監査モードで出力された指標を使用して、reCAPTCHA の適用を有効にするかどうかを決定します。
適用: 有効にすると、Identity Platform は、Identity Platform API へのトラフィックの評価に使用される 1 つ以上の reCAPTCHA Enterprise キーをプロジェクトに作成します。reCAPTCHA トークンを含まない API リクエストは拒否されます。reCAPTCHA Enterprise をサポートする SDK にすべてのクライアントを移行した後にのみ、適用を有効にします。

reCAPTCHA Enterprise を有効にする手順は次のとおりです。

プロジェクトで reCAPTCHA Enterprise API を有効にします（まだ有効にしていない場合）。

Admin SDK を使用して、プロジェクトで reCAPTCHA Enterprise との Identity Platform 統合を有効にします。reCAPTCHA Enterprise のサポートは、Node.js Admin SDK バージョン 11.7.0 以降で利用できます。

例:

// Get project config
const getProjectConfig = () => {
  getAuth().projectConfigManager().getProjectConfig()
  .then((response) => {
    console.log('Project reCAPTCHA config: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error getting project config:', error);
  });
}

// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'AUDIT',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};
const updateProjectConfigWithRecaptcha = () => {
  getAuth().projectConfigManager().updateProjectConfig(updateConfigRequest).then((response) => {
    console.log('Updated reCAPTCHA config for project: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error updating project config:', error);
  });
}

Admin SDK を使用して、テナントの reCAPTCHA Enterprise と Identity Platform の統合を有効にします。例:

// Update tenant with reCAPTCHA config
const updateTenantRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'AUDIT',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};
const updateTenantWithRecaptchaConfig = () => {
  getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest)
  .then((response) => {
    console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error updating the tenant:', error);
  });
}

以下を置き換えます。

TENANT_ID: テナント ID

Apple プラットフォームまたは Android で Identity Platform を使用している場合は、Firebase コンソールからアプリを登録する必要があります。
- Apple プラットフォームの場合、Identity Platform を使用する各バンドル ID を登録します
- Android の場合は、Identity Platform を使用する各 Android パッケージ名を登録します
ウェブで Identity Platform を使用している場合は、reCAPTCHA を使用するドメインごとに承認済みドメインを追加する必要があります。承認済みドメインを追加する手順は次のとおりです。
1. Google Cloud コンソールで、Identity Platform ページに移動します。
  
  Identity Platform に移動
2. [設定] > [セキュリティ] に移動します。
3. [ドメインを追加] をクリックします。
4. ドメイン名を入力し、[追加] をクリックしてドメインを保存します。
サイトキーのプロビジョニングが完了するまでに数分かかることがあります。フローが保護されていることを確認するには、指標を確認します。

クライアント SDK を構成する

アプリのプラットフォームに応じてクライアント SDK を設定します。

Web

最新バージョンのウェブ SDK に更新してください。reCAPTCHA Enterprise のサポートは、JavaScript SDK バージョン 9.20.0 以降で利用できます。ウェブ SDK をアプリに統合すると、reCAPTCHA Enterprise の構成が自動的に取得され、構成済みのプロバイダが保護されます。

SDK によるネットワーク呼び出しの回数を減らし、reCAPTCHA シグナルの収集を改善するには、次のように明示的に構成することをおすすめします。

import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Auth
const auth = getAuth();
initializeRecaptchaConfig(auth)
  .then(() => {
    console.log("Recaptcha Enterprise Config Initialization successful.")
  })
  .catch((error) => {
    console.error("Recaptcha Enterprise Config Initialization failed with " + error)
  });

Android

Android SDK バージョン 31.5.0 以降に更新してください。reCAPTCHA Enterprise のサポートには、API レベル 19（KitKat）以降と Android 4.4 以降が必要です。Android SDK をアプリに統合すると、reCAPTCHA Enterprise の構成が自動的に取得され、構成済みのプロバイダが保護されます。
アプリレベルの build.gradle ファイルの依存関係セクションに、次のビルドルールを追加します。
```
implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
```
reCAPTCHA SDK バージョン 18.4.0 以降を使用していることを確認します。

SDK によるネットワーク呼び出しの回数を減らし、reCAPTCHA シグナルの収集を効果的に行うには、次のように明示的に構成することをおすすめします。

Kotlin:

// Initialize Firebase Auth
auth = Firebase.auth

auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
    if (task.isSuccessful) {
        Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
    } else {
        Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
    }
}

Java:

// Initialize Firebase Auth
auth = FirebaseAuth.getInstance();
auth.initializeRecaptchaConfig().addOnCompleteListener(
  this, new OnCompleteListener<void>() {
  @Override
  public void onComplete(@NonNull Task<void> task) {
    if (task.isSuccessful()) {
      Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
    } else {
      Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
    }
  }
});

iOS

iOS SDK バージョン 10.14.0 以降に更新してください。iOS SDK をアプリに統合すると、reCAPTCHA Enterprise の構成が自動的に取得され、構成済みのプロバイダが保護されます。
reCAPTCHA iOS SDK をアプリに統合するには、環境を準備するをご覧ください。
リンカーフラグに -ObjC が含まれていることを確認します。[Target] > [Build Settings] > [All] > [Linking] に移動して、Other Linker Flags に -ObjC が表示されていることを確認します。

SDK によるネットワーク呼び出しの回数を減らし、reCAPTCHA シグナルの収集を効果的に行うには、次のように明示的に構成することをおすすめします。

Swift:

// Initialize Firebase Auth
try await Auth.auth().initializeRecaptchaConfig()

Objective-C:

// Initialize Firebase Auth
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Auth initialization finished
}];

reCAPTCHA Enterprise 指標

reCAPTCHA Enterprise を有効にした後、プロジェクトが出力する reCAPTCHA 指標をモニタリングして、認証フローが保護されていることを確認します。reCAPTCHA サイトキーのプロビジョニングが失敗した場合、または必要なサービスアカウントが作成されていない場合、reCAPTCHA 認証はフェールオープンになります。

プロジェクトが Cloud Monitoring に出力する次の指標を調べて、reCAPTCHA 認証が機能していることを確認します。

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

reCAPTCHA Enterprise から返されたさまざまな判定を追跡します。トークンが存在する場合、判定が生成されます。次の判定でフィルタリングできます。

PASSED: 適用が有効になっている場合に、指定されたリクエストを許可することを示します。
FAILED_AUDIT: reCAPTCHA 監査モードが有効になっている場合に、特定のリクエストが拒否されることを示します。
FAILED_ENFORCE: reCAPTCHA 適用モードが有効な場合に、指定されたリクエストが拒否されることを示します。
CLIENT_TYPE_MISSING: reCAPTCHA の適用が有効になっている場合、特定のリクエストにクライアントタイプがないことを示します。これは通常、reCAPTCHA をサポートしていない古いバージョンの SDK を使用してリクエストが送信された場合に発生します。
KEYS_MISSING: reCAPTCHA の適用が有効になっているときに、有効な reCAPTCHA キーを取得または生成できないため、特定のリクエストを検証できないことを示します。

合格または失敗の判定の比率を変更するようにスコア範囲を変更するには、reCAPTCHA Enterprise を有効にするをご覧ください。

`identitytoolkit.googleapis.com/recaptcha/token_count`

Identity Platform バックエンドが受信した reCAPTCHA Enterprise トークンの数とステータスを追跡します。次のステータスでフィルタリングできます。

VALID: 渡された reCAPTCHA トークンが有効であることを示します。
EXPIRED: 渡された reCAPTCHA トークンが期限切れであることを示します。トークンの有効期限が切れている場合、クライアントネットワークに問題がある可能性があります。
DUPLICATE: 渡された reCAPTCHA トークンが重複であることを示します。トークンが重複している場合、クライアントネットワークの問題や不正行為を示している可能性があります。
INVALID: 渡された reCAPTCHA トークンが無効であることを示します。無効なトークンは不正行為を示している可能性があります。
MISSING: 指定されたリクエストに reCAPTCHA トークンが存在しないことを示します。トークンがない場合は、クライアントアプリが古い可能性があります。
UNCHECKED: CLIENT_TYPE_MISSING または KEYS_MISSING の判定結果により reCAPTCHA トークンがチェックされなかったことを示します。

アプリがユーザーに正常にロールアウトされると、有効なトークンを含むトラフィックが表示されます。有効なトークンの数は、更新したアプリを使用しているユーザーの数に比例すると考えられます。

`identitytoolkit.googleapis.com/recaptcha/risk_scores`

reCAPTCHA スコアの分布を追跡します。これにより、構成に最適なスコア範囲を定義できます。

これらの指標を使用して、適用を有効にできるかどうかを判断します。適用を有効にする前に、次の点を考慮する必要があります。

最近のリクエストの大部分に有効なトークンがあり、FAILED_AUDIT または FAILED_ENFORCE 判定に対する PASSED の比率がビジネスケースで許容できる場合は、適用を有効にすることを検討してください。
最近のリクエストの大半が古いクライアントからのものである場合は、より多くのユーザーがアプリを更新するのを待ってから、適用を有効にすることを検討してください。Identity Platform を reCAPTCHA Enterprise と統合すると、reCAPTCHA Enterprise と統合されていない以前のアプリバージョンが中断されます。

これらの指標を表示するには、次の手順を行います。

Google Cloud コンソールで、[Metrics Explorer] ページに移動します。

Metrics Explorer に移動
[指標の選択] に「Identity Toolkit Tenant」と入力します。マルチテナンシーを使用している場合は、tenant_name を空のままにすることで、各テナントと親プロジェクトの指標を表示できます。

適用を有効にする

アプリが許容されるユーザートラフィックを受信していることを確認したら、reCAPTCHA の適用を有効にしてユーザーを保護できます。古いユーザー（古いバージョンのアプリを使用しているユーザーを含む）に悪影響を及ぼすことはありません。

プロジェクトまたはテナントに対して reCAPTCHA の適用を有効にするには、Admin SDK を使用して次のコマンドを実行します。

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

reCAPTCHA Enterprise を無効にする

reCAPTCHA Enterprise を無効にするには、Admin SDK を使用して次のコマンドを実行します。

const disableRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'OFF',
  }
};

Cloud Functions を使用して reCAPTCHA Enterprise の判定をオーバーライドする

スコアしきい値を構成するだけでなく、カスタム Cloud Functions ブロッキング関数を使用して、特定のトークンに対する reCAPTCHA Enterprise の判定をオーバーライドできます。これは、特定のユーザーログインに対して reCAPTCHA スコアが低くなる可能性がある一方で、そのユーザーが信頼できるか、他の方法で検証されているため、ログインを完了できる場合に便利です。

reCAPTCHA Enterprise でブロッキング関数を構成する方法については、ブロッキング Cloud Functions を使用して Firebase Authentication を拡張するをご覧ください。

トラブルシューティング

ユーザーがログイン、登録、パスワードを再設定できない

ユーザーが古いバージョンのアプリを使用している可能性があります。Client SDK を使用する更新バージョンのアプリが提供されていない場合は、すぐに適用モードをオフにしてください。それ以外の場合は、ユーザーにアプリの更新を依頼します。

または、現在の設定に基づいてユーザーがブロックされる可能性があります。次のようにしてください。

reCAPTCHA キースコアを調整して、より制限の厳しい構成を検討してください。
別のデバイス、ブラウザ、ネットワークを試すようにユーザーに依頼します。
強制適用モードを再度有効にする前に、監査モードに戻り、指標をモニタリングします。

reCAPTCHA Enterprise を有効にする

概要

始める前に

サービス アカウントを作成する

reCAPTCHA Enterprise を有効にする

クライアント SDK を構成する

Web

Android

iOS

reCAPTCHA Enterprise 指標

identitytoolkit.googleapis.com/recaptcha/verdict_count

identitytoolkit.googleapis.com/recaptcha/token_count

identitytoolkit.googleapis.com/recaptcha/risk_scores

適用を有効にする

reCAPTCHA Enterprise を無効にする

Cloud Functions を使用して reCAPTCHA Enterprise の判定をオーバーライドする

トラブルシューティング

ユーザーがログイン、登録、パスワードを再設定できない

サービスアカウントを作成する

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

`identitytoolkit.googleapis.com/recaptcha/token_count`

`identitytoolkit.googleapis.com/recaptcha/risk_scores`