reCAPTCHA Enterprise を有効にする

このドキュメントでは、Identity Platform と reCAPTCHA のインテグレーションを使用してユーザーのセキュリティを強化する方法について説明します。この機能により、スパム、不正使用、その他の不正行為に対するアプリのレジリエンスが向上します。

Identity Platform と reCAPTCHA のインテグレーションにより、ユーザーリクエストを検証する reCAPTCHA 評価を、ユーザーに代わって作成します。料金については、reCAPTCHA の料金をご覧ください。

概要

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

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

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

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

始める前に

ユーザーのメールアドレスでのログインを構成します。

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

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

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

Google Cloud CLI を使用してサービスアカウントを作成します。
```
gcloud beta services identity create \
    --service=identitytoolkit.googleapis.com \
    --project=PROJECT_ID
```
PROJECT_ID をそのプロジェクトの ID に置き換えます。

サービスアカウントに reCAPTCHA へのアクセス権を付与します。

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 を有効にする

reCAPTCHA には、ユーザーの保護に役立つ次の 2 つのモードがあります。

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

reCAPTCHA を有効にするには、次の操作を行います。

まだ行っていない場合は、プロジェクトで reCAPTCHA API を有効にします。

Admin SDK を使用して、プロジェクトで reCAPTCHA との Identity Platform インテグレーションを有効にします。reCAPTCHA のサポートは、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 を使用して、テナントに対して Identity Platform と reCAPTCHA のインテグレーションを有効にします。次に例を示します。

// 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 を構成する

アプリのプラットフォームに応じて、Client SDK を構成します。

ウェブ

Web SDK の最新バージョンに更新します。 reCAPTCHA は、JavaScript SDK バージョン 9.20.0 以上でサポートされています。Web SDK をアプリと統合した後、reCAPTCHA 構成が自動的に取得され、構成したプロバイダが保護されます。

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 をサポートするには、API レベル 19（KitKat）以降と Android 4.4 以降が必要です。Android SDK をアプリと統合した後、reCAPTCHA 構成が自動的に取得され、構成したプロバイダが保護されます。
アプリレベルの 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 構成が自動的に取得され、構成したプロバイダが保護されます。
reCAPTCHA iOS SDK をアプリに統合するには、環境を準備するをご覧ください。
リンカーフラグに -ObjC が含まれていることを確認します。[Target] > [Build Settings] > [All] > [Linking] に移動して、Other Linker Flags に -ObjC が表示されていることを確認します。

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 指標

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

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

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

reCAPTCHA から返されるさまざまな判定をトラッキングします。判定は、トークンが存在する場合に生成されます。以下の判定でフィルタリングできます。

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

スコア範囲を変更して、判定結果の「合格」と「不合格」の比率を変更するには、reCAPTCHA Enterprise を有効にするをご覧ください。

`identitytoolkit.googleapis.com/recaptcha/token_count`

Identity Platform バックエンドで受信された reCAPTCHA トークンの数とステータスをトラッキングします。以下のステータスでフィルタできます。

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

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

`identitytoolkit.googleapis.com/recaptcha/risk_scores`

reCAPTCHA のスコア分布をトラッキングします。これは、構成の最適スコア範囲の定義に役立つ場合があります。

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

最近のリクエストの大部分に有効なトークンがあり、PASSED と FAILED_AUDIT または FAILED_ENFORCE 判定の比率がビジネスケースで許容できる場合、適用の有効化を検討します。
最近のリクエストの大部分が古いクライアントからのリクエストである可能性が高い場合、適用を有効にする前に、より多くのユーザーがアプリを更新するまで待つことを検討します。Identity Platform と reCAPTCHA のインテグレーションを適用すると、reCAPTCHA とのインテグレーションが未実行である旧アプリバージョンが機能しなくなります。

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

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

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

適用を有効にする

アプリが許容できるユーザートラフィックを受信していることを確認した後、ユーザーを保護するため reCAPTCHA の適用を有効化できます。古いバージョンのアプリを使用しているユーザーを含む、既存のユーザーを中断しないようにします。

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

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

reCAPTCHA を無効にする

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

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

Cloud Run 関数を使用して reCAPTCHA の判定をオーバーライドする

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

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

トラブルシューティング

ユーザーがログイン、登録、パスワードのリセットを実行できない

ユーザーが古いバージョンのアプリを使用している可能性があります。Client SDK を使用する更新バージョンのアプリが提供されていない場合は、すぐに適用モードをオフにしてください。そうでない場合は、アプリを更新していただくようお客様に伝えてください。

また、現在の構成に基づいてユーザーがブロックされることもあります。次のようにしてください。

reCAPTCHA キースコアを調整して、より許容できる構成を検討します。
別のデバイス、ブラウザ、ネットワークを試すようにユーザーへ伝えます。
監査モードに戻り、適用モードを再び有効にする前に指標をモニタリングします。