Why does my PHP Firestore Client return a PERMISSION_DENIED error with service account credentials?

Below is one explanation many have encountered when using Firestore with a PHP backend:

---

The Issue

Your Firestore security rule is written to allow reads/writes only when “request.auth” is not null (or when “request.auth.uid” is set). This works well for client SDKs where the Firebase Authentication token is automatically attached to the request. However, when you use the PHP library with a service account (via keyfile), the authentication context provided by a Firebase user isn’t available—the call is made with service account credentials, and Firestore still applies your security rules. In other words, the call is being treated as if no Firebase user is signed in, so “request.auth” is null, which is why you see:

  PERMISSION_DENIED: Missing or insufficient permissions.

---

Why Your Change Didn’t Help

Changing your rule from checking request.auth != null to request.auth.uid != null makes no difference because in both cases the server call made via your service account lacks the Firebase user token. The keyfile credentials do not add a user UID to the request; they just authenticate the caller as a service account. Unlike the Firebase Admin SDK, which bypasses security rules in trusted environments, the code in your PHP library (google/cloud-firestore) still enforces the rules you set.

---

Options for a Resolution

You have two main choices:

1. Utilize Trusted Environment (Bypass Security Rules):

   If you’re running in a trusted backend, you might consider using the Firebase Admin SDK. Admin SDK calls bypass the Firestore security rules entirely. Unfortunately, the official Firebase Admin SDK for PHP is not available, which is why some opt for alternative solutions.

2. Adjust Your Security Rules for Service Account Requests:

   You could modify your rules to grant your server (service account) access. For example, if you’re comfortable that calls from your server are trusted, you might add a condition to allow access to requests issued with your service account. One way is to use a custom claim (such as an “admin” claim) in your authentication token. For example:

   FIREBASECopied
   rules_version = '2';
   
   service cloud.firestore {
     match /databases/{database}/documents {
       // Allow access if the request is authenticated as a normal user,
       // or if the request comes with a valid custom claim (e.g., admin == true)
       match /{document=**} {
         allow read, write: if request.auth != null ||
           (request.auth.token.admin == true);
       }
     }
   }

   To use this, you’d need to create a custom token with the admin claim on your service account side and then attach it to your Firestore requests. This approach can work if you encrypt and sign these tokens properly.

   Note: Be very cautious with expanding rules. If you allow too much with a custom claim, you could expose your data inadvertently.

---

Recommended Best Practices

• On Trusted Backends: Use an SDK or mechanism that bypasses or is exempt from security rules. In Node.js or Java, the Admin SDK automatically bypasses rules. For PHP, you may consider using a trusted proxy service if available.

• On Client-Side Calls: Use Firebase client libraries so that the authenticated user’s ID token is attached to each request, satisfying your rules.

• Testing: Always test your rules using the Firestore emulator before deploying them.

---

Summary

Your error occurs because your PHP backend’s calls with a service account do not have a Firebase user ID. Therefore, the condition (request.auth != null or request.auth.uid != null) fails, and the rules block access. Depending on your use case, either adjust your security rules (with caution) to allow trusted service account calls or use an Admin SDK that bypasses these rules from your backend.