Enable reCAPTCHA SMS defense for SMS-based authentication

This document explains how you can use reCAPTCHA to protect your Identity Platform SMS-based flows, such as phone and multi-factor authentication, against SMS toll fraud (also known as SMS pumping attacks).

Overview

If your app relies on an SMS-based flow for authentication, you can enable the Firebase Authentication or Identity Platform integration with reCAPTCHA. When enabled, Firebase Authentication and Identity Platform invoke the reCAPTCHA SMS defense feature when a user requests a verification SMS from your app or site using the following phoneProvider operations:

Operation	Method
Phone number sign up or sign in	`sendVerificationCode`
MFA phone number enrollment	`mfaSmsEnrollment`
MFA phone number sign in	`mfaSmsSignIn`

reCAPTCHA then provides Firebase Authentication or Identity Platform with a risk score that indicates the likelihood that the user's phone number will commit SMS toll fraud. Firebase Authentication and Identity Platform compare this score to the threshold you set in your reCAPTCHA SMS defense configuration and then handle the request based on the action you've set in your configuration.

For more information on the reCAPTCHA SMS defense feature, see Detect and prevent SMS fraud.

Before you begin

Before you enable reCAPTCHA SMS defense for Identity Platform, complete the following tasks:

Configure the following for your app or site as applicable:
- Phone sign in for users.
- Multi-factor authentication for your web, Android, or iOS app.
If you haven't already done so, create a service account for each project that will use reCAPTCHA. For instructions, see Create a service account.

reCAPTCHA phone authentication enforcement modes

reCAPTCHA SMS defense requires that you've set up reCAPTCHA phone authentication enforcement, which has two modes: audit and enforce.

Audit mode

When you set phone authentication enforcement to audit mode, Identity Platform uses reCAPTCHA SMS defense for app verification. If the user request passes the toll fraud assessment, Identity Platform sends an SMS message containing a verification code to the user's phone. If a request fails the toll fraud assessment and you are using the client SDK, fallback verification methods are triggered to complete the phone authentication flow. The fallback methods accepted depend on your app's platform.

The client SDK triggers the fallback verification methods in the following scenarios:

The reCAPTCHA token is missing.
The reCAPTCHA token is invalid or expired.
The reCAPTCHA token doesn't pass the score threshold.
reCAPTCHA is not configured correctly.

Ensure that the fallback verification methods for your app's platform are set up and ready to be triggered by the client SDK if necessary.

Web

If the initial toll fraud assessment fails, audit mode relies on reCAPTCHA v2 for verification. Therefore, you must set up the reCAPTCHA verifier (RecaptchaVerifier) and pass it to the following phone authentication operations:

verifyPhoneNumber
signInWithPhoneNumber
linkWithPhoneNumber
reauthenticateWithPhoneNumber

Without the reCAPTCHA verifier, Identity Platform can't initiate reCAPTCHA v2 and will return auth/argument-error. For more information on setting up the reCAPTCHA verifier, see Set up the reCAPTCHA verifier in the Firebase documentation.

Android

If the initial toll fraud assessment fails, audit mode verifies your app against the Play Integrity API. If this verification fails, reCAPTCHA v2 is triggered. reCAPTCHA v2 might be triggered in the following scenarios:

If the end-user's device does not have Google Play services installed.
If the app is not distributed through Google Play Store (on Authentication SDK v21.2.0 and later).
If the obtained SafetyNet token was not valid (on Authentication SDK versions prior to v21.2.0).

For more information on setting up Android app verification, see Enable app verification in the Firebase documentation.

iOS

If the initial toll fraud assessment fails, audit mode relies on silent push notifications for verification. This verification method involves sending a token to your app on the requesting device with a silent push notification. If your app successfully receives the notification, the phone authentication flow proceeds. If your app does not receive the push notification, reCAPTCHA v2 is triggered. reCAPTCHA v2 might be triggered if silent push notifications are not configured properly.

For more information on setting up iOS app verification, see Enable app verification in the Firebase documentation.

Enforce mode

When you set phone authentication enforcement to enforce mode, Identity Platform uses reCAPTCHA SMS defense for app verification. If the user request passes the toll fraud assessment, Identity Platform sends an SMS message containing a verification code to the user's phone. If the request fails the toll fraud assessment, Identity Platform blocks the request and doesn't send an SMS message containing a verification code.

There is no fallback verification required in enforce mode, you don't have to set up any additional verification methods for your app. However, we recommend setting up reCAPTCHA verifier for web apps to ensure that reCAPTCHA v2 is enabled if you decide to change your app's reCAPTCHA mode to AUDIT or OFF.

Enable reCAPTCHA SMS defense

To enable reCAPTCHA SMS defense, do the following:

If you haven't already done so, enable the reCAPTCHA Enterprise API on your project.
Enable reCAPTCHA SMS defense with reCAPTCHA. For instructions, see the Before you begin section of the Detect and prevent SMS fraud page in the reCAPTCHA documentation.
To enable reCAPTCHA SMS defense for a Firebase Authentication or Identity Platform project, use the Google APIs Explorer to call updateConfig by copy pasting the following HTTP URL in a new browser window where you're logged into the Google Cloud Console.
```
https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"emailPasswordEnforcementState":"OFF","phoneEnforcementState":"ENFORCE_MODE","useSmsTollFraudProtection":true,"tollFraudManagedRules":[{"action":"BLOCK","startScore":START_SCORE}]}}}
```
Note: Replace the following variables in the preceding HTTP URL before copy pasting.
- PROJECT_ID: the project identifier with identity-platform enabled.
- ENFORCE_MODE: the mode you want to set for reCAPTCHA phone authentication enforcement. Valid values are OFF, AUDIT, and ENFORCE. To enable reCAPTCHA SMS defense, this parameter must be set to AUDIT or ENFORCE and useSmsTollFraudProtection must be set to true.
  
  When enabling reCAPTCHA SMS defense for the first time, we recommend setting the enforcement state to AUDIT and ensuring your authentication flows are protected before setting this to ENFORCE. For more information on how the modes work, see reCAPTCHA phone authentication enforcement modes.
- START_SCORE: the highest toll fraud assessment score a request can have before it fails. You can set this score to be between 0.0 and 1.0. Any score above the threshold you set will be considered SMS toll fraud. For example, if you set a threshold of 0.3, reCAPTCHA will fail any request with a 0.4 or higher. Therefore, the lower you set the score, the stricter the rules will be.
If you are using Identity Platform on the web or Android, register your app from the Firebase console:
- For Android, Register each Android package name that uses Identity Platform.
- For the web, add an authorized domain for each domain that uses reCAPTCHA. To add authorized domains, do the following:
  1. In the Google Cloud console, go to the Identity Platform page.
    
    Go to Identity Platform
  2. Go to Settings > Security.
  3. Click Add domain.
  4. Enter the domain name and click Add to save the domain.
reCAPTCHA key provisioning can take several minutes to complete.
If you've set enforcement to audit mode, we recommend that you monitor the reCAPTCHA metrics for reCAPTCHA SMS defense to ensure that your flows are being protected.

Configure the client SDK

Configure the client SDK according to your app's platform.

Web

Update to the latest version of the web SDK.
- reCAPTCHA support for email and password authentication in web apps is available on JavaScript SDK versions 9.20.0 and later.
- reCAPTCHA support for phone authentication in web apps is available on JavaScript SDK versions 11 and later.
After you've integrated the web SDK with your app, the SDK automatically fetches your reCAPTCHA configuration and enables protection for the providers you've configured.

If needed, you can force fetch the reCAPTCHA signal as follows:

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

Update to the latest version of the Android SDK. reCAPTCHA support for email and password authentication and phone authentication in Android apps is available on Android SDK version 23.1.0 and later.

In addition, reCAPTCHA support requires API level 23 (Marshmallow) or higher and Android 6 or higher.

After you've integrated the Android SDK with your app, the SDK automatically fetches your reCAPTCHA configuration and enables protection for the providers you've configured.
Add the following build rule to the dependencies section of your app-level build.gradle file:
```
implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
```
Make sure to use reCAPTCHA SDK version 18.5.1 or later.

If needed, you can force fetch the reCAPTCHA signal as follows:

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

Update to iOS SDK version 11.6.0 or later. After you've integrated the iOS SDK with your app, the SDK automatically fetches your reCAPTCHA configuration and enables protection for the providers you've configured.
To integrate reCAPTCHA iOS SDK to your app, see Prepare your environment.
Ensure that -ObjC is listed in your linker flags. Navigate to Target > Build Settings > All > Linking and verify that Other Linker Flags shows -ObjC.

If needed, you can force fetch the reCAPTCHA signal as follows:

Swift:

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

Objective-C:

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

Monitor reCAPTCHA metrics for reCAPTCHA SMS defense

Before you set the reCAPTCHA enforcement to enforce mode, we recommend you use audit mode and monitor the reCAPTCHA metrics your project emits to ensure that your SMS-based authentication flows are protected. For example, these metrics can help you determine if you've set up the Identity Platform integration with the reCAPTCHA Enterprise API correctly. They can also help you fine-tune your score threshold for your user traffic.

Ensure that the reCAPTCHA SMS defense feature is working by examining the following metrics your project emits to Cloud Monitoring:

For more information, see Monitor reCAPTCHA metrics.

Enforce reCAPTCHA SMS defense

After you verify that your app is receiving acceptable user traffic, you can enable reCAPTCHA enforcement to protect your users. Ensure you don't disrupt existing users, including users who may be using an older version of your app.

To enable reCAPTCHA enforcement for SMS-based authentication flows on a project or tenant, use the Google APIs Explorer to update the project config:

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE',
      useSmsTollFraudProtection: 'true'
    }

Disable reCAPTCHA SMS defense

To disable reCAPTCHA SMS defense, use the Google APIs Explorer to update the project config:

    recaptchaConfig: {
      phoneEnforcementState:  'OFF',
      useSmsTollFraudProtection: 'false'
    }

To disable reCAPTCHA SMS defense while you are using bot protection, see Disable reCAPTCHA SMS defense while using bot protection.

Use reCAPTCHA SMS defense with bot protection

It is possible to use reCAPTCHA SMS defense simultaneously with bot protection. For configurations that use both protection features, consider the following:

When you've set the phone authentication enforcement state to audit, Identity Platform passes a request when it satisfies at least one of the assessments. We encourage you to monitor the reCAPTCHA metrics to ensure both reCAPTCHA SMS defense and bot protection are configured with reasonable score settings.
When you've set the phone authentication enforcement state to enforce, Identity Platform only passes a request when it satisfies both assessments and the request fail closes without falling back to another verification method.

To enable both features, use the Google APIs Explorer to update the project config:

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: true,
      useSmsBotScore: true
    }

Replace ENFORCE_MODE with the mode you want to set for reCAPTCHA phone authentication enforcement. Valid values are OFF, AUDIT, and ENFORCE. To enable reCAPTCHA SMS defense, this parameter must be set to AUDIT or ENFORCE. When enabling reCAPTCHA SMS defense for the first time, we recommend setting this parameter to AUDIT and ensuring your authentication flows are protected before setting this to ENFORCE. For more information on how the modes work, see reCAPTCHA phone authentication enforcement modes.

Disable reCAPTCHA SMS defense while using bot protection

If you are using both reCAPTCHA SMS defense and bot protection simultaneously, and you want to disable reCAPTCHA SMS defense without disabling bot protection, use the Google APIs Explorer to update the project config:

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }

Replace ENFORCE_MODE with the mode you've previously set for reCAPTCHA phone authentication enforcement. This value should be either AUDIT or ENFORCE. For more information on how the modes work, see reCAPTCHA phone authentication enforcement modes.

What's next

Learn more about the reCAPTCHA SMS defense feature.