Get started using App Check with reCAPTCHA Enterprise in web apps

Select platform:

iOS+ Android Web Flutter

This page shows you how to set up App Check in a web app, using the reCAPTCHA Enterprise provider. App Check helps to ensure that only your app can access your project's backend resources. To learn more, review our overview of App Check.

App Check requires the use of score-based reCAPTCHA keys, which makes it invisible to users. This means that the reCAPTCHA Enterprise provider won't require users to solve a challenge at any time.

If your use case requires reCAPTCHA Enterprise features not implemented by App Check, or if you want to use App Check with your own custom provider, see Implement a custom App Check provider.

1. Set up your Firebase project

If you haven't already, add Firebase to your JavaScript project.
In the Google Cloud console, go to the Fraud Defense page, and do the following for the reCAPTCHA Enterprise provider:
1. Make sure that you're in the correct project (see the project picker at the top of the screen).
2. If prompted, enable the reCAPTCHA Enterprise API.
3. Create a Web-type key, and specify each of the domains for your web apps.
  - App Check does not support web apps that serve on more than 250 domains.
  - Never add localhost as a domain to a reCAPTCHA key that is deployed to (or is going to be deployed to) production.
  - Leave the "Use checkbox challenge" option unselected.
  For detailed instructions, see Create score-based reCAPTCHA keys.
4. Take note of this key. You'll need to add it into the registration flow in the Firebase console.
In the Firebase console, navigate to Security > App Check.
In the Apps tab, register your Web apps to use App Check with the reCAPTCHA Enterprise provider. You'll need to provide the key you got in the Google Cloud console.

Important: Make sure to register all of your project's apps with an attestation provider (like reCAPTCHA Enterprise). Once you enable enforcement for a service, only registered apps will be able to access the service.
Optional: Set the token time to live (TTL).

In the app registration settings, set a custom time to live (TTL) for App Check tokens issued by the provider. You can set the TTL to any value between 30 minutes and 7 days. When changing this value, be aware of the following tradeoffs:
- Security: Shorter TTLs provide stronger security, because it reduces the window in which a leaked or intercepted token can be abused by an attacker.
- Performance: Shorter TTLs mean your app will perform attestation more frequently. Because the app attestation process adds latency to network requests every time it's performed, a short TTL can impact the performance of your app.
- Quota and cost: Shorter TTLs and frequent re-attestation deplete your quota faster, and for paid services, potentially cost more. See Quotas & limits.
The default TTL of 1 hour is reasonable for most apps. Note that the App Check library refreshes tokens at approximately half the TTL duration.
Optional: Configure advanced settings.
Click Save.

(Optional) Configure advanced settings

When a user opens your app, reCAPTCHA Enterprise evaluates the level of risk the user interaction under the key poses, and returns a score between 0.0 and 1.0, in increments of 0.1.

A score of 0.0 indicates that the interaction poses high risk and might be fraudulent.
A score of 1.0 indicates that the interaction poses low risk and is very likely legitimate.

App Check lets you configure an app risk threshold so you can adjust your tolerance for this risk.

For most use cases, the default threshold value of 0.5 is recommended. If your use case requires adjustment, you can configure this value for each of your apps in the Firebase console (go to Security > App Check). Make sure to expand and review some important considerations about configuring the app risk threshold below.

View important considerations about app risk threshold

App Check uses your configured app risk threshold as the minimum reCAPTCHA Enterprise score required for a user interaction to be deemed legitimate. All reCAPTCHA Enterprise scores strictly less than your configured threshold will be rejected. When adjusting your app risk threshold, be aware of the following:

If your Firebase project is on the no-cost Spark pricing plan, then out of the 11 possible reCAPTCHA Enterprise score levels, only the following four score levels are available: 0.1, 0.3, 0.7, and 0.9.

During this time, App Check will correspondingly only allow app risk threshold values of 0.1, 0.3, 0.5, 0.7, and 0.9. An app risk threshold value of 0.5 is still recommended for most use cases.
- To enable all 11 reCAPTCHA Enterprise score levels, link a Cloud Billing account to your project (which means you upgrade your Firebase project to the pay-as-you-go Blaze pricing plan). Once you've upgraded your project, App Check will let you configure any app risk threshold values between 0.0 and 1.0, in increments of 0.1.
  
  Note: After a Cloud Billing account is linked to your project, an automatic security review is triggered for your project. For more information, see the reCAPTCHA Enterprise documentation.
To monitor the distribution of high and low reCAPTCHA Enterprise scores for your app, go to the reCAPTCHA Enterprise page in the Google Cloud console, and select the key used by your app.
Set your app risk threshold appropriately for your tolerance:
- If you have high app risk tolerance, move the slider to the right to decrease the app risk threshold.
  - A value of 0.0 is not recommended, as this setting disables abuse protection.
- If you have low app risk tolerance, move the slider to the left to increase the app risk threshold.
  - A value of 1.0 is not recommended, as this setting can also potentially deny access for legitimate users who don't meet this high trust threshold.
  Warning: To avoid disrupting your legitimate users, gradually increase the app risk threshold when App Check is enforced. Always monitor App Check request metrics to verify that traffic has not been disrupted.

For additional details, review the reCAPTCHA Enterprise documentation.

2. Add the App Check library to your app

If you haven't already, install the Firebase JavaScript SDK and initialize Firebase in your app.

3. Initialize App Check

Add the following App Check initialization code early in your app so that it runs before you access any Firebase services in your app.

Make sure to pass the same reCAPTCHA key that you used to register your app with reCAPTCHA Enterprise in the Firebase console (see first section of the guide).

Web

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";

const app = initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance
// using your reCAPTCHA Enterprise key and pass it to `initializeAppCheck()`.
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(RECAPTCHA_KEY),
  isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
});

Web

firebase.initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance
// using your reCAPTCHA Enterprise key and pass it to `activate()`.
const appCheck = firebase.appCheck();
appCheck.activate(
  new firebase.appCheck.ReCaptchaEnterpriseProvider(
    RECAPTCHA_KEY
  ),
  true // Set to true to allow auto-refresh.
);

4. Monitor metrics and enable enforcement

After you've set up App Check in your app, start distributing the updated app to your users.

The updated client app will begin sending App Check tokens along with every request it makes to Firebase. However, App Check won't block requests with invalid tokens until App Check is enforced.

Monitor metrics

Before you enable enforcement, make sure that doing so won't disrupt your existing legitimate users. However, if you're seeing suspicious use of your app resources, you might want to enable enforcement sooner.

To help make this decision, you can review App Check metrics for the services you use:

Monitor App Check request metrics for Firebase AI Logic, SQL Connect, Realtime Database, Cloud Firestore, Cloud Storage, Authentication, Google Identity for iOS, Maps JavaScript API, and Places API (New).
Monitor App Check request metrics for Cloud Functions.

Enable App Check enforcement

When you understand how App Check will affect your users and you're ready to proceed, you can enable App Check enforcement:

Enable App Check enforcement for Firebase AI Logic, SQL Connect, Realtime Database, Cloud Firestore, Cloud Storage, Authentication, Google Identity for iOS, Maps JavaScript API, and Places API (New).
Enable App Check enforcement for Cloud Functions.

Use App Check in debug environments

App Check classifies some environments as invalid, such as requests from localhost during development or from a continuous integration (CI) environment.

To run your app in these types of environments after App Check is enforced, you need to create a debug build of your app that uses the App Check debug provider instead of a production attestation provider.

For more details, see Use App Check with the debug provider in web apps.

Pricing

App Check creates an assessment on your behalf to validate the user's response token each time your app refreshes its App Check token. Your Firebase project will be charged for each assessment created above the no-cost quota. For details, see reCAPTCHA pricing.

By default, your app will refresh this token twice every 1 hour. To control how frequently your app refreshes App Check tokens (and thus how frequently new assessments are created), you can configure the token TTL.