Implement limited-use App Check tokens. (#4876)

* Implement `getLimitedUseAppCheckToken`.

* Add unit tests.

* Update `api.txt` and changelog.

* Update test application.

* Additional javadoc update.

* Address review comment.

* Update link to public docs.

Author: rosalyntan

appcheck/firebase-appcheck/CHANGELOG.md

@@ -1,4 +1,6 @@
 # Unreleased
+* [feature] Added `getLimtedUseAppCheckToken()` for obtaining limited-use tokens
+  for protecting non-Firebase backends.
 
 # 16.1.2
 * [unchanged] Updated to keep [app_check] SDK versions aligned.

appcheck/firebase-appcheck/api.txt

@@ -21,6 +21,7 @@ package com.google.firebase.appcheck {
     method @NonNull public abstract com.google.android.gms.tasks.Task<com.google.firebase.appcheck.AppCheckToken> getAppCheckToken(boolean);
     method @NonNull public static com.google.firebase.appcheck.FirebaseAppCheck getInstance();
     method @NonNull public static com.google.firebase.appcheck.FirebaseAppCheck getInstance(@NonNull com.google.firebase.FirebaseApp);
+    method @NonNull public abstract com.google.android.gms.tasks.Task<com.google.firebase.appcheck.AppCheckToken> getLimitedUseAppCheckToken();
     method public abstract void installAppCheckProviderFactory(@NonNull com.google.firebase.appcheck.AppCheckProviderFactory);
     method public abstract void installAppCheckProviderFactory(@NonNull com.google.firebase.appcheck.AppCheckProviderFactory, boolean);
     method public abstract void removeAppCheckListener(@NonNull com.google.firebase.appcheck.FirebaseAppCheck.AppCheckListener);

appcheck/firebase-appcheck/src/main/java/com/google/firebase/appcheck/FirebaseAppCheck.java

@@ -75,10 +75,29 @@ public abstract void installAppCheckProviderFactory(
    * Requests a Firebase App Check token. This method should be used ONLY if you need to authorize
    * requests to a non-Firebase backend. Requests to Firebase backends are authorized automatically
    * if configured.
+   *
+   * <p>If your non-Firebase backend exposes sensitive or expensive endpoints that has low traffic
+   * volume, consider protecting it with <a
+   * href=https://firebase.google.com/docs/app-check/custom-resource-backend#replay-protection>Replay
+   * Protection</a>. In this case, use the #getLimitedUseAppCheckToken() instead to obtain a
+   * limited-use token.
    */
   @NonNull
   public abstract Task<AppCheckToken> getAppCheckToken(boolean forceRefresh);
 
+  /**
+   * Requests a Firebase App Check token. This method should be used ONLY if you need to authorize
+   * requests to a non-Firebase backend.
+   *
+   * <p>Returns limited-use tokens that are intended for use with your non-Firebase backend
+   * endpoints that are protected with <a
+   * href=https://firebase.google.com/docs/app-check/custom-resource-backend#replay-protection>Replay
+   * Protection</a>. This method does not affect the token generation behavior of the
+   * #getAppCheckToken() method.
+   */
+  @NonNull
+  public abstract Task<AppCheckToken> getLimitedUseAppCheckToken();
+
   /**
    * Registers an {@link AppCheckListener} to changes in the token state. This method should be used
    * ONLY if you need to authorize requests to a non-Firebase backend. Requests to Firebase backends

appcheck/firebase-appcheck/src/main/java/com/google/firebase/appcheck/internal/DefaultFirebaseAppCheck.java

@@ -229,6 +229,19 @@ public Task<AppCheckToken> getAppCheckToken(boolean forceRefresh) {
         });
   }
 
+  @NonNull
+  @Override
+  public Task<AppCheckToken> getLimitedUseAppCheckToken() {
+    if (appCheckProvider == null) {
+      return Tasks.forException(new FirebaseException("No AppCheckProvider installed."));
+    }
+
+    // We explicitly do not call the fetchTokenFromProvider helper method, as that method includes
+    // side effects such as notifying listeners, updating the cached token, and scheduling token
+    // refresh.
+    return appCheckProvider.getToken();
+  }
+
   /** Fetches an {@link AppCheckToken} via the installed {@link AppCheckProvider}. */
   Task<AppCheckToken> fetchTokenFromProvider() {
     return appCheckProvider

appcheck/firebase-appcheck/src/test/java/com/google/firebase/appcheck/internal/DefaultFirebaseAppCheckTest.java

@@ -228,6 +228,13 @@ public void testGetAppCheckToken_noFactoryInstalled_taskFails() throws Exception
     assertThat(tokenTask.isSuccessful()).isFalse();
   }
 
+  @Test
+  public void testGetLimitedUseAppCheckToken_noFactoryInstalled_taskFails() throws Exception {
+    Task<AppCheckToken> tokenTask = defaultFirebaseAppCheck.getLimitedUseAppCheckToken();
+    assertThat(tokenTask.isComplete()).isTrue();
+    assertThat(tokenTask.isSuccessful()).isFalse();
+  }
+
   @Test
   public void testGetToken_factoryInstalled_proxiesToAppCheckFactory() {
     defaultFirebaseAppCheck.installAppCheckProviderFactory(mockAppCheckProviderFactory);
@@ -396,4 +403,23 @@ public void testGetAppCheckToken_existingInvalidToken_requestsNewToken() {
 
     verify(mockAppCheckProvider).getToken();
   }
+
+  @Test
+  public void testGetLimitedUseAppCheckToken_noExistingToken_requestsNewToken() {
+    defaultFirebaseAppCheck.installAppCheckProviderFactory(mockAppCheckProviderFactory);
+
+    defaultFirebaseAppCheck.getLimitedUseAppCheckToken();
+
+    verify(mockAppCheckProvider).getToken();
+  }
+
+  @Test
+  public void testGetLimitedUseAppCheckToken_existingToken_requestsNewToken() {
+    defaultFirebaseAppCheck.setCachedToken(validDefaultAppCheckToken);
+    defaultFirebaseAppCheck.installAppCheckProviderFactory(mockAppCheckProviderFactory);
+
+    defaultFirebaseAppCheck.getLimitedUseAppCheckToken();
+
+    verify(mockAppCheckProvider).getToken();
+  }
 }

appcheck/firebase-appcheck/test-app/src/main/java/com/googletest/firebase/appcheck/MainActivity.java

@@ -47,6 +47,7 @@ public class MainActivity extends AppCompatActivity {
   private Button installSafetyNetButton;
   private Button installDebugButton;
   private Button getAppCheckTokenButton;
+  private Button getLimitedUseTokenButton;
   private Button listStorageFilesButton;
 
   @Override
@@ -74,7 +75,7 @@ private void initFirebase() {
         new AppCheckListener() {
           @Override
           public void onAppCheckTokenChanged(@NonNull AppCheckToken token) {
-            Log.d(TAG, "onAppCheckTokenChanged");
+            Log.d(TAG, "onAppCheckTokenChanged: " + token.getToken());
           }
         };
 
@@ -86,6 +87,7 @@ private void initViews() {
     installSafetyNetButton = findViewById(R.id.install_safety_net_app_check_button);
     installDebugButton = findViewById(R.id.install_debug_app_check_button);
     getAppCheckTokenButton = findViewById(R.id.exchange_app_check_button);
+    getLimitedUseTokenButton = findViewById(R.id.limited_use_app_check_button);
     listStorageFilesButton = findViewById(R.id.storage_list_files_button);
 
     setOnClickListeners();
@@ -134,20 +136,55 @@ public void onClick(View v) {
                 new OnSuccessListener<AppCheckToken>() {
                   @Override
                   public void onSuccess(AppCheckToken appCheckToken) {
-                    Log.d(TAG, "Successfully retrieved AppCheck token.");
-                    showToast("Successfully retrieved AppCheck token.");
+                    // Note: Logging App Check tokens is bad practice and should NEVER be done in a
+                    // production application. We log the token here in our unpublished test
+                    // application for easier debugging.
+                    Log.d(
+                        TAG, "Successfully retrieved App Check token: " + appCheckToken.getToken());
+                    showToast("Successfully retrieved App Check token.");
                   }
                 });
             task.addOnFailureListener(
                 new OnFailureListener() {
                   @Override
                   public void onFailure(@NonNull Exception e) {
-                    Log.d(TAG, "AppCheck token exchange failed with error: " + e.getMessage());
-                    showToast("AppCheck token exchange failed.");
+                    Log.d(TAG, "App Check token exchange failed with error: " + e.getMessage());
+                    showToast("App Check token exchange failed.");
                   }
                 });
           }
         });
+
+    getLimitedUseTokenButton.setOnClickListener(
+        new OnClickListener() {
+          @Override
+          public void onClick(View v) {
+            Task<AppCheckToken> task = firebaseAppCheck.getLimitedUseAppCheckToken();
+            task.addOnSuccessListener(
+                new OnSuccessListener<AppCheckToken>() {
+                  @Override
+                  public void onSuccess(AppCheckToken appCheckToken) {
+                    // Note: Logging App Check tokens is bad practice and should NEVER be done in a
+                    // production application. We log the token here in our unpublished test
+                    // application for easier debugging.
+                    Log.d(
+                        TAG,
+                        "Successfully retrieved limited-use App Check token: "
+                            + appCheckToken.getToken());
+                    showToast("Successfully retrieved limited-use App Check token.");
+                  }
+                });
+            task.addOnFailureListener(
+                new OnFailureListener() {
+                  @Override
+                  public void onFailure(@NonNull Exception e) {
+                    Log.d(TAG, "App Check token exchange failed with error: " + e.getMessage());
+                    showToast("App Check token exchange failed.");
+                  }
+                });
+          }
+        });
+
     listStorageFilesButton.setOnClickListener(
         new OnClickListener() {
           @Override

appcheck/firebase-appcheck/test-app/src/main/res/layout/activity_main.xml

@@ -26,6 +26,11 @@
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:text="@string/exchange_app_check_button_text"/>
+  <Button
+      android:id="@+id/limited_use_app_check_button"
+      android:layout_width="wrap_content"
+      android:layout_height="wrap_content"
+      android:text="@string/limited_use_app_check_button_text"/>
   <Button
       android:id="@+id/storage_list_files_button"
       android:layout_width="wrap_content"

appcheck/firebase-appcheck/test-app/src/main/res/values/strings.xml

@@ -3,6 +3,7 @@
   <string name="install_play_integrity_app_check_button_text">Install PlayIntegrityAppCheckProvider</string>
   <string name="install_safety_net_app_check_button_text">Install SafetyNetAppCheckProvider</string>
   <string name="install_debug_app_check_button_text">Install DebugAppCheckProvider</string>
-  <string name="exchange_app_check_button_text">Exchange attestation for App Check token</string>
+  <string name="exchange_app_check_button_text">Get App Check token</string>
+  <string name="limited_use_app_check_button_text">Get limited-use App Check token</string>
   <string name="storage_list_files_button_text">List Cloud Storage files with App Check token</string>
 </resources>