Skip to main content

Fixing 'Permission Denied' Errors When Enabling Firebase App Check

 The deployment of Firebase App Check is a critical security milestone, but it often results in an immediate service disruption for developers and legitimate users. The error usually manifests as a Status{code=PERMISSION_DENIED, description=Missing or insufficient permissions} (gRPC code 7) when accessing Firestore, Realtime Database, or Cloud Storage.

This error indicates that the backend service requires a valid App Check token to fulfill the request, but the client failed to provide one that the server trusts. While the goal is to block abuse, this configuration often inadvertently blocks local emulators, simulators, and CI environments because they cannot pass standard attestation checks (like Play Integrity or App Attest).

This guide details the root cause of these failures and provides rigorous implementation patterns for Android and iOS to resolve them using Debug Providers.

The Anatomy of Error Code 7

To fix the error, you must understand the failure point. App Check relies on an Attestation Provider to verify the authenticity of the device and the app binary.

  1. Initialization: The app initializes the App Check SDK.
  2. Attestation: The SDK contacts the platform provider (Play Integrity on Android, DeviceCheck/App Attest on iOS).
  3. Token Exchange: If the platform verifies the device, it returns an attestation structure. The Firebase SDK sends this to the Firebase Exchange server to get a distinct App Check Token (JWT).
  4. Request: The app attaches this token to the header (X-Firebase-AppCheck) of every request sent to Firebase services.
  5. Verification: The Firebase backend validates the signature of the JWT. If missing or invalid, the request is rejected with PERMISSION_DENIED.

The Problem: Emulators and Simulators are not trusted devices. They fail step 2 by default. Without explicit configuration, the SDK cannot acquire a token, and your local development environment loses access to the database.

Solution 1: Android Local Development (Debug Provider)

Android emulators cannot pass Play Integrity checks. You must install a DebugAppCheckProviderFactory that exchanges a locally generated UUID for a valid App Check token.

Step 1: Configure Build Dependencies

Ensure your app/build.gradle.kts utilizes the latest Firebase BOM to avoid version conflicts.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:32.7.0"))

    // Declare the dependencies for the App Check libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-playintegrity")
    implementation("com.google.firebase:firebase-appcheck-debug")
}

Step 2: Conditional Provider Registration

Do not use the Debug Provider in production. It renders your security useless as anyone with the ID can spoof your app. Use a conditional check based on BuildConfig.DEBUG.

Add this directly to your custom Application class onCreate method.

import android.app.Application
import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
import com.google.firebase.initialize

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize Firebase first
        Firebase.initialize(context = this)

        val appCheck = Firebase.appCheck

        if (BuildConfig.DEBUG) {
            // Use Debug provider for local development/emulators
            appCheck.installAppCheckProviderFactory(
                DebugAppCheckProviderFactory.getInstance()
            )
        } else {
            // Use Play Integrity for production
            appCheck.installAppCheckProviderFactory(
                PlayIntegrityAppCheckProviderFactory.getInstance()
            )
        }
    }
}

Step 3: Extracting and Registering the Token

Upon running the app in the emulator with the code above, the SDK will generate a local secret. You must whitelist this secret in the Firebase Console.

  1. Launch the app in the Android Emulator.
  2. Open Logcat.
  3. Filter for AppCheck.
  4. Locate the log entry: Enter this debug secret into the allow list in the Firebase Console for your project: 12345678-abcd-1234-abcd-12345678abcd
  5. Go to Firebase Console > App Check > Apps > [Your Android App].
  6. Click the three dots menu > Manage debug tokens.
  7. Click Add debug token, paste the UUID, and name it (e.g., "John's Emulator").

Once saved, the emulator will successfully exchange this ID for a valid App Check token on the next launch.

Solution 2: iOS Local Development (Simulator)

iOS Simulators cannot use DeviceCheck or AppAttest. The pattern is similar to Android but requires specific Launch Arguments to prevent the Debug Provider from shipping to the App Store.

Step 1: Configure the App Delegate

In your AppDelegate.swift (or the entry point for SwiftUI App struct), you must set the provider factory before configuring Firebase.

import UIKit
import FirebaseCore
import FirebaseAppCheck

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // Create the provider factory based on build settings
        let providerFactory: AppCheckProviderFactory
        
        #if targetEnvironment(simulator)
            // Simulator uses the Debug Provider
            providerFactory = AppCheckDebugProviderFactory()
        #else
            // Real devices use App Attest (preferred) or DeviceCheck
            providerFactory = AppAttestProviderFactory()
        #endif

        // Set the factory BEFORE configuring Firebase
        AppCheck.setAppCheckProviderFactory(providerFactory)

        // Initialize Firebase
        FirebaseApp.configure()

        return true
    }
}

Step 2: Enable Debug Mode via Launch Arguments

Unlike Android, the iOS SDK often requires an explicit environment variable to print the token or enable the debug provider behavior.

  1. In Xcode, go to Product > Scheme > Edit Scheme.
  2. Select Run in the left sidebar.
  3. Go to the Arguments tab.
  4. Under Arguments Passed On Launch, add: -FIRDebugEnabled
  5. Run the app in the Simulator.

Step 3: Register the iOS Token

  1. Check the Xcode console output.
  2. Look for: [Firebase/AppCheck][I-FAA001001] Firebase App Check Debug Token: <UUID>
  3. Copy this UUID.
  4. Go to Firebase Console > App Check > Apps > [Your iOS App].
  5. Manage debug tokens > Add debug token.

Handling Cloud Functions (The "Why" Behind Backend Rejections)

If you are calling Cloud Functions directly, the PERMISSION_DENIED error often happens because the function logic explicitly checks for the token but receives undefined.

When using Cloud Functions 2nd Gen, context verification is built into the Callable interface. Here is how to safely handle App Check in a Node.js backend.

import { onCall, HttpsError } from "firebase-functions/v2/https";

export const sensitiveAction = onCall((request) => {
    // 1. Verify App Check Token Presence
    if (!request.app) {
        throw new HttpsError(
            'failed-precondition',
            'The function must be called from an App Check verified app.'
        );
    }

    // 2. (Optional) Check for Already Consumed Tokens
    // Replay protection is critical for high-security endpoints
    if (request.app.alreadyConsumed) {
         throw new HttpsError(
            'unauthenticated',
            'This token has already been used.'
        );
    }

    return { status: "success", data: "Secure data accessed" };
});

If request.app is undefined, it means the client SDK did not send the token (likely due to the initialization failures described in the Android/iOS sections above).

Common Edge Cases and Pitfalls

1. The "Token Refresh" Latency

App Check tokens have a Time-To-Live (TTL). If a user leaves the app open for days (backgrounded) and tries to perform an action immediately upon maximizing, the token might be stale.

  • Fix: The Firebase SDK handles auto-refresh, but ensure you handle network errors gracefully in your UI. If a PERMISSION_DENIED occurs, prompting the user to retry often resolves it as the SDK fetches a fresh token in the background.

2. CI/CD Integration Tests

Running integration tests in CI (like GitHub Actions) requires a permanent token, not a generated one.

  • Fix: Generate a Debug Token in the Firebase Console manually. Store this token as a secret in your CI environment (e.g., APP_CHECK_DEBUG_TOKEN). Inject this into your build via environment variables and pass it to the DebugAppCheckProviderFactory constructor explicitly in your test instrumentation code.

3. Usage Limits on Attestation Providers

Play Integrity and Apple’s App Attest have API quotas.

  • Issue: During heavy load testing or a viral launch, you might hit the quota, causing PERMISSION_DENIED for legitimate users.
  • Fix: Monitor your quotas in Google Cloud Console and the Apple Developer Portal. Request quota increases before marketing pushes.

Summary

The PERMISSION_DENIED error in App Check contexts is rarely a server-side permission issue (like IAM rules) and almost always a client-side attestation failure.

  1. Identify the environment: Is it failing locally? It's missing a Debug Provider.
  2. Implement the factory: Use DebugAppCheckProviderFactory for debug builds and the platform provider for release builds.
  3. Whitelist the Secret: The local SDK generates a UUID; the Firebase Console must know about it.
  4. Check Launch Arguments: particularly for iOS (-FIRDebugEnabled).

By strictly separating debug and release logic, you ensure developers retain access without compromising the security integrity of your production application.

Labels: