Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Identity Platform と reCAPTCHA Enterprise API を統合する

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

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

概要

Identity Platform と reCAPTCHA Enterprise API の統合を設定すると、reCAPTCHA のデフォルトの保護機能である reCAPTCHA bot 対策が有効になります。bot 対策により、Identity Platform はユーザーに代わってプロジェクトにスコアベースの reCAPTCHA キーをプロビジョニングします。ユーザーが次のいずれかのオペレーションを使用してアプリまたはサイトにアクセスすると、対応するプロバイダが有効になっている場合に、クライアント SDK が reCAPTCHA を読み込みます。

プロバイダ	オペレーション	メソッド
`passwordProvider`	メールとパスワードによるログイン	`signInWithPassword`
	メールとパスワードによる登録	`signUpPassword`
	メールリンクによるログイン	`getOobCode`
	パスワードの再設定	`getOobCode`
`phoneProvider`	電話番号による登録またはログイン	`sendVerificationCode`
	MFA 電話番号の登録	`mfaSmsEnrollment`
	MFA 電話番号によるログイン	`mfaSmsSignIn`

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

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

始める前に

reCAPTCHA で保護する認証フローのタイプに基づいて、次のものが設定されていることを確認します。

メールとパスワードによる認証フローの場合は、ユーザーのメールアドレスでのログインを構成していることを確認します。
SMS ベースの認証フローの場合は、次のいずれかにオンボーディングしていることを確認します。
- ユーザーの電話番号によるログイン。
- iOS

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

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

サービスアカウントをまだ作成していない場合、または 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 bot 対策モード

reCAPTCHA bot 対策には、ユーザーの保護に役立つ次の 2 つのモードがあります。監査と適用。これらのモードは、ID プロバイダによって動作が異なります。

メールとパスワードのプロバイダ

メールとパスワードによる認証フローの場合、監査モードと適用モードは次のように動作します。

監査モード

メールとパスワードの適用を監査モードに設定すると、Identity Platform は、1 つ以上の reCAPTCHA キーをプロジェクトに作成し、それらはリクエストをブロックせずに Identity Platform API へのトラフィックを評価するために使用されます。監査モードで出力される指標を使用して、reCAPTCHA の適用を有効にするかどうかを判断します。

適用モード

メールとパスワードの適用を適用モードに設定すると、Identity Platform は、1 つ以上の reCAPTCHA キーをプロジェクトに作成し、Identity Platform API へのトラフィックを評価するために使用されます。reCAPTCHA トークンを含まない API リクエストは拒否されます。reCAPTCHA をサポートする SDK にすべてのクライアントを移行した後にのみ、適用を有効にします。

電話プロバイダ

電話認証フローの場合、監査モードと適用モードは次のように動作します。

監査モード

電話認証の適用を監査モードに設定すると、Identity Platform はアプリの確認に reCAPTCHA bot 対策を使用します。ユーザーのリクエストが通信不正利用の評価に合格すると、SMS 確認コードが送信されます。ユーザーのリクエストが通信不正利用の評価に不合格であり、クライアント SDK を使用している場合、Identity Platform はフォールバックの確認方法をトリガーして、電話認証フローを完了します。受け入れられるフォールバック方法は、アプリのプラットフォームによって異なります。

クライアント SDK は、次のシナリオでフォールバックの確認方法をトリガーします。

reCAPTCHA トークンがありません。
reCAPTCHA トークンが無効か、期限切れです。
reCAPTCHA トークンがスコアしきい値を超えていません。
reCAPTCHA が正しく設定されていません。

アプリのプラットフォームのフォールバック確認方法が設定され、必要に応じてクライアント SDK によってトリガーされる準備ができていることを確認します。

ウェブ

最初の bot 対策評価が失敗した場合、監査モードでは確認に reCAPTCHA v2 が使用されます。したがって、 reCAPTCHA 検証ツール（RecaptchaVerifier）を設定し、次の電話認証オペレーションに渡す必要があります。

verifyPhoneNumber
signInWithPhoneNumber
linkWithPhoneNumber
reauthenticateWithPhoneNumber

reCAPTCHA 検証ツールがない場合、Identity Platform は reCAPTCHA v2 を開始できず、auth/argument-error を返します。reCAPTCHA 検証ツールの設定の詳細については、Firebase ドキュメントの reCAPTCHA 検証ツールを設定するをご覧ください。

Android

最初の bot 対策評価が失敗した場合、監査モードでは Play Integrity API に対してアプリが検証されます。この検証が失敗すると、reCAPTCHA v2 がトリガーされます。 reCAPTCHA v2 は、次のような場合にトリガーされることがあります。

エンドユーザーのデバイスに Google Play 開発者サービスがインストールされていない場合。
（Authentication SDK v21.2.0 以降で）アプリが Google Play ストアを通じて配布されたものでない場合。
（Authentication SDK バージョン v21.2.0 より前で）取得した SafetyNet トークンが有効でない場合。

Android アプリの確認の設定の詳細については、Firebase ドキュメントのアプリの確認を有効にするをご覧ください。

iOS

最初の bot 対策評価が失敗した場合、監査モードでは確認にサイレントプッシュ通知が使用されます。この確認方法では、リクエスト元のデバイス上のアプリにトークンをサイレントプッシュ通知で送信します。アプリが通知を正常に受信すると、電話認証フローが続行されます。アプリがプッシュ通知を受信しない場合、reCAPTCHA v2 がトリガーされます。サイレントプッシュ通知が正しく構成されていない場合、reCAPTCHA v2 がトリガーされることがあります。

iOS アプリの確認の設定の詳細については、Firebase ドキュメントのアプリの確認を有効にするをご覧ください。

適用モード

電話認証の適用を適用モードに設定すると、Identity Platform はアプリの確認に reCAPTCHA bot 対策を使用します。ユーザーのリクエストが通信不正利用の評価に合格すると、SMS 確認コードが送信されます。ユーザーのリクエストが通信不正利用の評価に不合格の場合、Identity Platform はリクエストをブロックし、確認コードを含む SMS メッセージを送信しません。

適用モードではフォールバック検証は必要ないため、アプリに追加の検証方法を設定する必要はありません。ただし、アプリの reCAPTCHA モードを AUDIT または OFF に変更する場合は、reCAPTCHA v2 が有効になるように、ウェブアプリに reCAPTCHA 検証ツールを設定することをおすすめします。

Identity Platform と reCAPTCHA Enterprise API の統合を設定する

Identity Platform と reCAPTCHA Enterprise API の統合を設定するには、次のタスクを行います。

Admin SDK を使用して reCAPTCHA の適用状態を設定し、bot 対策を有効にします。
アプリのプラットフォームのクライアント SDK を構成します。

最初に監査モードで reCAPTCHA の適用を有効にし、プロジェクトが出力する reCAPTCHA 指標をモニタリングして、認証フローが適切に保護されていることを確認することをおすすめします。これにより、ユーザーによる reCAPTCHA の使用を監査している間、ユーザートラフィックが中断されるのを防ぐことができます。認証フローが保護されていることを確認したら、bot 対策を ENFORCE に設定します。

reCAPTCHA bot 対策を有効にする

メールとパスワードのプロバイダ

メールとパスワードによる認証フローで reCAPTCHA bot 対策を有効にするには、次の操作を行います。

まだ行っていない場合は、プロジェクトで reCAPTCHA Enterprise API を有効にします。
プロジェクトで bot 対策を有効にするには、Admin SDK を使用します。 reCAPTCHA のサポートは、Node.js Admin SDK バージョン 11.7.0 以降で利用できます。

次に例を示します。
```
// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE_MODE',
    managedRules: [{
      endScore: END_SCORE,
      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);
  });
}
```
以下を置き換えます。
- ENFORCE_MODE: reCAPTCHA のメールとパスワードによる認証の適用に設定するモード。有効な値は OFF、AUDIT、ENFORCE です。bot 対策を有効にするには、このパラメータを AUDIT または ENFORCE に設定する必要があります。初めて bot 対策を有効にする場合は、このパラメータを AUDIT に設定し、認証フローが保護されていることを確認してから ENFORCE に設定することをおすすめします。モードの仕組みの詳細については、 reCAPTCHA bot 対策モードをご覧ください。
- END_SCORE: リクエストが失敗する前に設定できる bot 対策評価の最低スコア。このスコアは 0.0～1.0 の範囲で設定できます。たとえば、しきい値を 0.6 に設定すると、reCAPTCHA は 0.5 以下のリクエストをすべて失敗させます。したがって、スコアを高く設定するほど、ルールが厳しくなります。
Admin SDK を使用して、テナントで同じ構成方法で bot 対策を有効にすることもできます。テナントの更新の詳細については、テナントを更新するをご覧ください。
iOS または Android で Identity Platform を使用する場合は、 Firebase コンソールからアプリを登録する必要があります。
- iOS の場合は、Identity Platform を使用する各バンドル ID を登録します
- Android の場合は、Identity Platform を使用する各 Android パッケージ名を登録します
ウェブで Identity Platform を使用している場合は、reCAPTCHA を使用する各ドメインに対して承認済みドメインを追加する必要があります。承認済みドメインを追加するには、次の操作を行います。
1. コンソールで、Identity Platform ページに移動します。 Google Cloud
  
  Identity Platform に移動
2. [設定] [>] [セキュリティ] に移動します。
3. [ドメインを追加] をクリックします。
4. ドメイン名を入力し、[追加] をクリックしてドメインを保存します。
reCAPTCHA キーのプロビジョニングが完了するまでに数分かかることがあります。
適用を監査モードに設定した場合は、bot 対策の reCAPTCHA 指標をモニタリングして、フローが保護されていることを確認することをおすすめします。

電話プロバイダ

SMS ベースの認証フローで reCAPTCHA bot 対策を有効にするには、次の操作を行います。

まだ行っていない場合は、プロジェクトで reCAPTCHA Enterprise API を有効にします。
プロジェクトで bot 対策を有効にするには、Admin SDK を使用します。 reCAPTCHA のサポートは、Node.js Admin SDK バージョン 12.7.0 以降で利用できます。

次に例を示します。
```
// Update project config with reCAPTCHA config
const updateProjectConfigRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE_MODE',
    managedRules: [{ endScore: END_SCORE, action: 'BLOCK' }],
    useSmsBotScore: 'true',
  }
}
let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
```
以下を置き換えます。
- ENFORCE_MODE: reCAPTCHA 電話認証の適用に設定するモード。有効な値は OFF、AUDIT、ENFORCE です。SMS ベースのフローで bot 対策を有効にするには、このパラメータを AUDIT または ENFORCE に設定し、useSmsBotScore を true に設定する必要があります。
  
  初めて bot 対策を有効にする場合は、このパラメータを AUDIT に設定し、認証フローが保護されていることを確認してから ENFORCE に設定することをおすすめします。モードの仕組みの詳細については、 reCAPTCHA bot 対策モードをご覧ください。
- END_SCORE: リクエストが失敗する前に設定できる bot 対策評価の最低スコア。このスコアは 0.0～1.0 の範囲で設定できます。たとえば、しきい値を 0.6 に設定すると、reCAPTCHA は 0.5 以下のリクエストをすべて失敗させます。したがって、スコアを高く設定するほど、ルールが厳しくなります。
Admin SDK を使用して、テナントで同じ構成方法で bot 対策を有効にすることもできます。テナントの更新の詳細については、テナントを更新するをご覧ください。

**注:** Identity Platform では、モバイルプラットフォームで複数のテナントを使用して電話認証と SMS 多要素認証を使用することはサポートされていません。
iOS または Android で Identity Platform を使用する場合は、アプリをFirebase コンソールから登録する必要があります。
- iOS の場合は、Identity Platform を使用する各バンドル ID を登録します
- Android の場合は、Identity Platform を使用する各 Android パッケージ名を登録します
ウェブで Identity Platform を使用している場合は、reCAPTCHA を使用する各ドメインに対して承認済みドメインを追加する必要があります。承認済みドメインを追加するには、次の操作を行います。
1. コンソールで、Identity Platform ページに移動します。 Google Cloud
  
  Identity Platform に移動
2. [設定] [>] [セキュリティ] に移動します。
3. [ドメインを追加] をクリックします。
4. ドメイン名を入力し、[追加] をクリックしてドメインを保存します。
reCAPTCHA キーのプロビジョニングが完了するまでに数分かかることがあります。
適用を監査モードに設定した場合は、bot 対策の reCAPTCHA 指標をモニタリングして、フローが保護されていることを確認することをおすすめします。

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

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

ウェブ

Web SDK の最新バージョンに更新します。
- ウェブアプリのメールとパスワードによる認証の reCAPTCHA サポートは、JavaScript SDK バージョン 9.20.0 以降で利用できます。
- ウェブアプリの電話認証の reCAPTCHA サポートは、JavaScript SDK バージョン 11 以降で利用できます。
Web SDK をアプリと統合すると、SDK は reCAPTCHA 構成を自動的に取得し、構成したプロバイダの保護を有効にします。

必要に応じて、次のように reCAPTCHA シグナルを強制的に取得できます。

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

// Initialize Firebase Authentication
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 の最新バージョンに更新します。Android アプリのメールとパスワードによる認証と電話認証の reCAPTCHA サポートは、Android SDK バージョン 23.1.0 以降で利用できます。

また、reCAPTCHA のサポートには、API レベル 23（Marshmallow）以降と Android 6 以降が必要です。

Android SDK をアプリと統合すると、SDK は reCAPTCHA 構成を自動的に取得し、構成したプロバイダの保護を有効にします。
アプリレベルの build.gradle ファイルの依存関係セクションに、次のビルドルールを追加します。
```
implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
```
reCAPTCHA SDK バージョン 18.5.1 以降を使用していることを確認します。

必要に応じて、次のように reCAPTCHA シグナルを強制的に取得できます。

Kotlin:

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

必要に応じて、次のように reCAPTCHA シグナルを強制的に取得できます。

Swift:

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

Objective-C:

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

bot 対策の reCAPTCHA 指標をモニタリングする

reCAPTCHA の適用を適用モードに設定する前に、監査モードを使用して、プロジェクトが出力する reCAPTCHA 指標をモニタリングし、認証フローが保護されていることを確認することをおすすめします。たとえば、これらの指標を使用すると、Identity Platform と reCAPTCHA Enterprise API の統合が正しく設定されているかどうかを判断できます。また、ユーザートラフィックのスコアしきい値を微調整することもできます。reCAPTCHA キーのプロビジョニングが失敗した場合や、必要なサービスアカウントが作成されなかった場合でも、reCAPTCHA 認証の試行は正常に成功します。

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

identitytoolkit.googleapis.com/recaptcha/verdict_count: reCAPTCHA から返されるさまざまな判定をトラッキングします。
identitytoolkit.googleapis.com/recaptcha/token_count: Identity Platform バックエンドで受信された reCAPTCHA トークンの数とステータスをトラッキングします。
identitytoolkit.googleapis.com/recaptcha/risk_scores: bot 対策スコアの分布をトラッキングします。

詳細については、reCAPTCHA 指標をモニタリングするをご覧ください。

reCAPTCHA bot 対策を適用する

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

メールとパスワードのプロバイダ

プロジェクトまたはテナントでメールとパスワードによる認証フローの reCAPTCHA の適用を有効にするには、Admin SDK を使用して次のコマンドを実行します。

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    }]
  }
};

電話プロバイダ

プロジェクトまたはテナントで SMS ベースの認証フローの reCAPTCHA の適用を有効にするには、Admin SDK を使用して次のコマンドを実行します。

const enforceRequest = {
  recaptchaConfig: {
    phoneEnforcementState:  'ENFORCE',
    useSmsBotScore: 'true'
    }]
  }
};

reCAPTCHA bot 対策を無効にする

メールとパスワードのプロバイダ

メールとパスワードによる認証フローの bot 対策を無効にするには、Admin SDK を使用して次のコマンドを実行します。

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

電話プロバイダ

SMS ベースの認証フローの bot 対策を無効にするには、Admin SDK を使用して次のコマンドを実行します。

const disableRequest = {
  recaptchaConfig: {
    phoneEnforcementState:  'OFF',
    useSmsBotScore: 'false'
  }
};

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

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

次の例は、ブロッキング関数を使用して reCAPTCHA の判定をオーバーライドする方法を示しています。

Node.js

  const functions = require("firebase-functions/v1");
  exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
    if (
      context.smsType === "SIGN_IN_OR_SIGN_UP" &&
      context.additionalUserInfo.phoneNumber.includes('+91')
    ) {
      return {
        recaptchaActionOverride: "ALLOW",
      };
    }

    // Allow users to sign in with recaptcha score greater than 0.5
    if (event.additionalUserInfo.recaptchaScore > 0.5) {
      return {
        recaptchaActionOverride: 'ALLOW',
      };
    }

    // Block all others.
    return  {
      recaptchaActionOverride: 'BLOCK',
    }
  });

次のステップ

SMS ベースの認証フローで reCAPTCHA SMS 防御を有効にする。
独自の reCAPTCHA キーを使用する方法を学習する。
reCAPTCHA 指標のモニタリングの詳細を確認する。
reCAPTCHA の詳細を確認する。

Identity Platform と reCAPTCHA Enterprise API を統合する

概要

始める前に

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

reCAPTCHA bot 対策モード

メールとパスワードのプロバイダ

監査モード

適用モード

電話プロバイダ

監査モード

ウェブ

Android

iOS

適用モード

Identity Platform と reCAPTCHA Enterprise API の統合を設定する

reCAPTCHA bot 対策を有効にする

メールとパスワードのプロバイダ

電話プロバイダ

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

ウェブ

Android

iOS

bot 対策の reCAPTCHA 指標をモニタリングする

reCAPTCHA bot 対策を適用する

メールとパスワードのプロバイダ

電話プロバイダ

reCAPTCHA bot 対策を無効にする

メールとパスワードのプロバイダ

電話プロバイダ

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

Node.js

次のステップ

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