Using SMS regions to protect your app from SMS abuse

This guide shows you how to use SMS regions to restrict Identity Platform SMS verification usage and view usage metrics.

Overview of SMS regions

SMS regions is an Identity Platform feature you can use to protect your apps from SMS abuse.

SMS abuse typically happens when a malicious actor causes a service to send SMS through a carrier that they have a revenue sharing agreement with. SMS abuse can lead to higher costs and damage your product's reputation with customers.

Because Identity Platform allows SMS phone authorizations, SMS abuse can occur.

The SMS regions feature lets you set which regions can receive SMS phone authorizations.

The feature provides the following:

  • A Firebase console interface for you to set up your SMS region policy.
  • An API for you to set up your SMS region policy.
  • Metrics that can inform your decision to use an SMS region policy.

Set a region policy

This section describes an Identity Platform region policy. You can set up the following types of policies, and only one can be active:

  • Allowlist-only: only the regions that you specify in an allowlist can receive phone authorization requests.
  • Denylist-only: all regions can receive phone authorization requests except the ones you specify in a denylist.

After you change the configuration, the system immediately starts to enforce the policy. It blocks phone authorization requests from the regions that are disallowed by the policy based on the region code of the phone number.

Allowlist-only policy

To set up an allowlist-only policy, follow these steps:

Firebase console

  1. In the Firebase console, go to the Firebase Auth Settings page.

    Go to Firebase Auth settings

    1. Select SMS region policy in the navigation pane.

    2. Select Allow.

    3. Click Select regions.

  2. Add only regions you want SMS messages to be sent to. Regions not on the list are blocked.

  3. Click Save.

    You can configure either an allowlist or a denylist but not both. Doing so overwrites any previous configuration.

Identity Toolkit API

  1. In the Google Cloud console, to print an access token for your project, run the following command:

    gcloud auth print-access-token --project=PROJECT_ID

  2. Update your project configuration to include your new policy using the Identity Toolkit API:

    curl -X PATCH -d "{'sms_region_config':{'allowlist_only':{'allowed_regions':['REGION_LIST']}}}" \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
'https://identitytoolkit.googleapis.com/admin/v2/projects/PROJECT_ID/config?updateMask=sms_region_config'

Replace the following:

  • ACCESS_TOKEN: the access token you generated earlier.
  • REGION_LIST: one or more regions, for example, IN or US.
  • PROJECT_ID: your project ID.

You must provide an update mask to prevent other fields from being changed.

Denylist-only policy

To set up a denylist-only policy, follow these steps:

Firebase Console

  1. In the Firebase console, go to the Firebase Auth Settings page and select SMS region policy in the navigation pane.

    Go to Firebase Auth settings

    1. Select Deny.

    2. Click Select regions.

  2. Add any regions that you want to block sending SMS messages to. Regions not on the list will be allowed.

  3. Click Save.

    You can configure either an allowlist or a denylist but not both. Doing so overwrites any previous configuration.

Identity Toolkit API

  1. In the Google Cloud console, to print an access token for your project, run the following command:

    gcloud auth print-access-token --project=PROJECT_ID

  2. Update your project configuration to include your new policy using the Identity Toolkit API:

    curl -X PATCH -d "{'sms_region_config':{'allow_by_default':{'disallowed_regions':['REGION_LIST']}}}" \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
'https://identitytoolkit.googleapis.com/admin/v2/projects/PROJECT_ID/config?updateMask=sms_region_config'

Replace the following:

  • ACCESS_TOKEN: the access token you generated earlier.
  • REGION_LIST: one or more regions, for example, IN or US.
  • PROJECT_ID: your project ID.

You must provide an update mask to prevent other fields from being changed.

Access regional SMS use metrics

This section describes how to view SMS use metrics.

To view the metrics, do the following:

  1. In the Google Cloud console, Go to the Metrics explorer page in Cloud Monitoring:

    Go to Cloud Monitoring.

  2. Select the following fields:

    • identitytoolkit.googleapis.com/usage/sent_sms_count,
    • identitytoolkit.googleapis.com/usage/blocked_sms_count, and
    • firebaseauth.googleapis.com/phone_auth/phone_verification_count.

    Note that the metrics have a field region_code. You use this code to view the regions that receive SMS authorizations.

  3. Compute the verification success rate as verification_success_rate = phone_verification_count/sent_sms_count, in a particular region. Typically, verification success rates above 75% are considered acceptable.

A low verification_success_rate can indicate abuse, especially in a region in which you wouldn't expect to have users. Typically, verification success rates below 75% are considered low.

If you suspect SMS abuse, you can set a region policy.