Detect and prevent SMS fraud

This document shows you how to use SMS defense to detect and prevent SMS pumping attacks in businesses that rely on SMS for two-factor authentication (2FA) or phone verification, which is a potential target for SMS toll fraud.

SMS-based authentication (2FA and login) is an industry standard for login and signup security, but it doesn't provide protection against SMS toll fraud or SMS pumping fraud. Before you send an SMS, SMS defense provides you with a risk score that indicates the likelihood of that phone number committing SMS toll fraud. Based on this score, you can allow or block fraudulent SMS messages before they are sent to your SMS provider.

The SMS defense risk score works inversely in comparison to the reCAPTCHA global score. A SMS defense risk score of 0.0 shows low confidence of SMS toll fraud occurring; a risk score of 1.0 shows high confidence of SMS toll fraud occurring. For more information about reCAPTCHA scores, see Interpret assessments for websites. If you're using Firebase Authentication or Identity Platform, see the Identity Platform documentation.

For additional information, see the SMS defense blog.

Before you begin

Depending on whether you are an existing user of reCAPTCHA or new to reCAPTCHA, follow the instructions in the appropriate tab:

Create an assessment with the phone number

For SMS defense, create assessments with the token that is generated by the execute() function and the phone number, by using either the reCAPTCHA Client Libraries or the REST API from your backend.

This document shows how to create an assessment using the REST API. To learn how to create an assessment using Client Libraries, see Create assessments.

Before you create an assessment, do the following:

• Set up authentication to Fraud Defense.

  The authentication method you choose depends on the environment where Fraud Defense is set up. The following table helps you choose the appropriate authentication method and the supported interface to set up authentication:

  Environment	Interface	Authentication method
  Google Cloud	REST Client libraries	Use attached service accounts.
  On-premises or a different cloud provider	REST	Use API keys or Workload Identity Federation. If you want to use API keys, then we recommend securing the API keys by applying API key restrictions.
  	Client libraries	Use the following: For Python or Java, use API keys or Workload Identity Federation. If you want to use API keys, then we recommend securing the API keys by applying API key restrictions. For other languages, use Workload Identity Federation.

• Choose a stable account identifier accountId that is not often changed by the user and provide it to the assessment in the projects.assessments.create method. This stable account identifier should have the same value for all the events related to the same user. You can provide the following as the account identifier:

  User identifiers

  If every account can be uniquely associated with a stable username, email address, or phone number, you can use it as the accountId. When you provide such cross-site identifiers (identifiers that can be reused across sites), Fraud Defense uses this information to improve protection for your user accounts based on cross-site models by flagging abusive account identifiers and using knowledge of cross-site abuse patterns related to these identifiers.

  Alternatively, if you have an internal user ID uniquely associated with each account, you can provide it as the accountId.

  Hashed or encrypted

  If you do not have an internal user ID uniquely associated with each account, you can turn any stable identifier into an opaque, site-specific account identifier. This identifier is still needed for Fraud Defense account defender to understand user activity patterns and detect anomalous behaviour, but it is not shared across other sites.

  Pick any stable account identifier and make it opaque before sending to Fraud Defense by using encryption or hashing:

  • encryption (recommended): encrypt the account identifier using a deterministic encryption method that produces a stable ciphertext. For detailed instructions, see encrypt data deterministically. When you choose symmetric encryption over hashing, you don't need to keep a mapping between your user identifiers and the corresponding opaque user identifiers. Decrypt the opaque identifiers that are returned by Fraud Defense to turn them into the user identifier.

  • hashing: we recommend hashing the account identifier using the SHA256-HMAC method with a custom salt of your choice. Because hashes are one-way only, you need to keep a mapping between the generated hashes and your user identifiers so that you can map the hashed account identifier that are returned back to the original accounts.

Add the accountId parameter and the phone number in the E.164 format as the UserId to verify in the assessment in the projects.assessments.create method.

Before using any of the request data, make the following replacements:

• PROJECT_ID: your Google Cloud project ID.
• TOKEN: token returned from the grecaptcha.enterprise.execute() call.
• KEY_ID: the score-based key that you installed on your website.
• ACCOUNT_ID: an identifier for a user account that is unique to your website.
• PHONE_NUMBER: the phone number that needs to be checked for maliciousness. The phone number must be in the E.164 format and it should not be hashed or encrypted.

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

Request JSON body:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userInfo": {
      "accountId": "ACCOUNT_ID",
      "userIds": [
        {
          "phoneNumber": "PHONE_NUMBER"
        }
      ]
    }
  }
}

To send your request, choose one of these options: