Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Identity Platform を reCAPTCHA Enterprise API と統合する

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

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

概要

reCAPTCHA Enterprise API との Identity Platform の統合を設定すると、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 ベースの認証フローの場合は、次のいずれかにオンボーディングしていることを確認してください。
- ユーザーの電話番号でのログイン。
- ウェブ、Android、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. \
    --role=roles/identitytoolkit.serviceAgent
```
以下を置き換えます。
- PROJECT_ID: プロジェクト ID
- PROJECT_NUMBER: プロジェクトアカウント番号

プロバイダ別の reCAPTCHA bot 保護の動作

reCAPTCHA bot 保護の動作は、構成する ID プロバイダによって異なります。

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

メール / パスワード認証フローの場合、reCAPTCHA bot 保護は監査と適用の 2 つのモードをサポートしています。

監査モード

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

適用モード

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

電話プロバイダ

phoneEnforcementState を ENFORCE に、useSmsBotScore を true に設定して、電話認証フローの bot 保護を有効にすると、Identity Platform はアプリの確認に reCAPTCHA bot 保護を使用します。ユーザーのリクエストが bot 保護の評価に合格すると、SMS 確認コードが送信されます。ユーザーのリクエストが bot 保護評価に不合格になると、Identity Platform はリクエストをブロックし、確認コードを含む SMS メッセージを送信しません。

電話認証フローで bot 保護が有効になっている場合、フォールバック検証は必要ありません。アプリに追加の検証方法を設定する必要もありません。ただし、bot 保護を無効にする場合に reCAPTCHA v2 を使用できるように、ウェブアプリに reCAPTCHA 検証ツールを設定することをおすすめします。

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

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

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

メール / パスワード認証フローでは、まず監査モードで reCAPTCHA の適用を有効にし、プロジェクトで出力される reCAPTCHA 指標をモニタリングして、認証フローが保護されていることを確認しながら、ユーザートラフィックの中断を回避することをおすすめします。認証フローが保護されていることを確認したら、bot 保護を ENFORCE に設定します。電話認証フローの場合は、phoneEnforcementState を ENFORCE に、useSmsBotScore を true に設定して bot 保護を有効にし、reCAPTCHA 指標をモニタリングしてスコアしきい値を微調整します。

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. Google Cloud コンソールで、[Identity Platform] ページに移動します。
  
  Identity Platform に移動
2. [Settings] > [Security] に移動します。
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',
    managedRules: [{
      endScore: END_SCORE,
      action: 'BLOCK'
    }],
    useSmsBotScore: true,
  }
};
let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
```
END_SCORE は、リクエストが失敗する前に取得できる bot 対策評価スコアの最小値に置き換えます。このスコアは 0.0～1.0 の範囲で設定できます。たとえば、しきい値を 0.6 に設定すると、reCAPTCHA は 0.5 以下のリクエストを失敗させます。したがって、スコアを高く設定するほど、ルールは厳しくなります。

phoneEnforcementState を ENFORCE に、useSmsBotScore を true に設定すると、SMS ベースの認証フローで bot 保護の適用が有効になります。電話プロバイダの適用方法の詳細については、プロバイダ別の reCAPTCHA bot 保護の動作をご覧ください。

Admin SDK を使用して、テナントに対して同じ構成方法で bot 保護を有効にすることもできます。テナントの更新の詳細については、テナントを更新するをご覧ください。

注: Identity Platform では、モバイルプラットフォームの複数のテナントで電話認証と SMS 多要素認証を使用することはサポートされていません。
iOS または Android で Identity Platform を使用している場合は、Firebase コンソールからアプリを登録する必要があります。
- iOS の場合、Identity Platform を使用する各バンドル ID を登録します
- Android の場合は、Identity Platform を使用する各 Android パッケージ名を登録します
ウェブで Identity Platform を使用している場合は、reCAPTCHA を使用する各ドメインに対して承認済みドメインを追加する必要があります。承認済みドメインを追加するには、次の操作を行います。
1. Google Cloud コンソールで、[Identity Platform] ページに移動します。
  
  Identity Platform に移動
2. [Settings] > [Security] に移動します。
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 指標をモニタリングし、認証フローが保護されていることを確認します。メールとパスワードによる認証フローでは、適用を適用モードに設定する前に、監査モードで指標をモニタリングすることをおすすめします。たとえば、これらの指標は、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 保護を適用する

最初に AUDIT モードで構成したメール / パスワード認証フローの場合、アプリが許容できるユーザートラフィックを受信していることを確認した後、emailPasswordEnforcementState を ENFORCE に切り替えて、reCAPTCHA 評価に失敗したリクエストをブロックできます。古いバージョンのアプリを使用しているユーザーを含む、既存のユーザーを中断しないようにします。

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

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

reCAPTCHA bot 保護を無効にする

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

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

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

電話プロバイダ

SMS ベースの認証フローで、bot 保護を含むすべての電話 reCAPTCHA 保護を無効にするには、Admin SDK を使用して次のコマンドを実行します。

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

reCAPTCHA SMS 防御も使用していて、bot 保護を無効にしながら有効にしておく場合は、useSmsBotScore を false に設定し、phoneEnforcementState を ENFORCE に設定したままにします。

const disableBotScoreOnlyRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    useSmsBotScore: false,
    useSmsTollFraudProtection: true
  }
};

Cloud Run functions を使用して 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 保護の動作

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

監査モード

適用モード

電話プロバイダ

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

reCAPTCHA bot 対策を有効にする

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

電話プロバイダ

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

Web

Android

iOS

bot 保護の reCAPTCHA 指標をモニタリングする

メール / パスワード フローに reCAPTCHA bot 保護を適用する

reCAPTCHA bot 保護を無効にする

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

電話プロバイダ

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

Node.js

次のステップ

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

メール / パスワードフローに reCAPTCHA bot 保護を適用する