How to Keep Your Custom Claims in Sync with Roles Stored in Firestore

A common question I often encounter, is how to maintain consistency between custom claims in Firebase Auth and role assignments stored in Firestore.

It is common in applications to have role-based authentication, where the access to resources is determined by a given role and where there are admin users have the authority to assign or revoke roles.

While Firestore provides an excellent backend to manage such information, it's crucial that this role data also be useful in authorization logic. In Firebase this is by best practice implemented in Firestore rules and Storage rules to declare resource access for database and files.

One of the ways to implement this is to only keep the data in Firestore, and another way to do it is to maintain the information in auth custom claims.

Both solutions has a few considerations to keep in mind.

Considering Your Options

As an illustration of the considerations, consider these security rules that are implementing each solution for two separate areas of the database and storage.

firestore.rules

service cloud.firestore {
  match /databases/{database}/documents {

    // Alt A: Using roles stored in Firestore user documents to determine access
    match /collection-a/{document} {
      allow read: if 'admin' in getUserRoles();
    }

    // Alt B: Using auth claims (role as an array) to determine access
    match /collection-b/{document} {
      allow read: if request.auth != null && 'admin' in request.auth.token.roles;
    }    

    // Function to get user roles from Firestore document
    function getUserRoles() {
      return get(/databases/$(database)/documents/users/$(request.auth.uid)).data.roles;
    }
  }
}

storage.rules

service firebase.storage {
  match /b/{bucket}/o {

    // Alt A: Using roles in user documents to determine access
    match /folder-a/{allPaths=**} {
      allow read: if 'admin' in getUserRoles();
    }

    // Alt B: Using auth claims to determine access
    match /folder-b/{allPaths=**} {
      allow read: if request.auth != null && 'admin' in request.auth.token.roles;
    }

    // Function to get user role from Firestore document
    function getRoleFromFirestore() {
      return get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role;
    }
  }
}

Option A: Firestore Document Lookups

If you choose to use Firestore document lookups for role-based access control, you're leveraging a straightforward method that works well with Firestore and Cloud Storage.

The primary drawback of this approach is its applicability is limited to just Firestore and Cloud Storage; it doesn't extend to Firebase's Realtime Database or other services that might benefit from integrated role-based access control.

It is also important to note that using Firestore documents to check authorization rules in both Firestore and Cloud Storage incurs additional document read costs each time an access check is performed.

Option B: Using Firebase Auth Custom Claims

The alternative involves replicating role information in Firebase Auth custom claims. This method offers broader integration across various services, including the Realtime Database and external API integrations where authentication data might be accessed via OAuth.

To implement this, a dedicated cloud function is essential for synchronizing role updates from Firestore documents to Firebase Auth custom claims. This function ensures that any changes in user roles within Firestore are promptly reflected in Firebase Auth.

Implementing the Cloud Function

The cloud function required for this task should:

• Trigger on updates to the user document specifically related to role changes.
• Update Firebase Auth custom claims to reflect these changes.
• Maintain any other existing custom claims in the user's auth object.

Here’s a simple example of such a cloud function:

export const updateUserRoles = functions.firestore
  .document('/users/{userId}')
  .onUpdate(async (change, context) => {
    const beforeData = change.before.data();
    const afterData = change.after.data();

    // Check if roles have changed
    if (JSON.stringify(beforeData.roles) === JSON.stringify(afterData.roles)) {
      functions.logger.info('Roles are unchanged. Do nothing.');
      return null;
    }

    const uid = context.params.userId;
    const newRoles = afterData.roles;

    // Get the current auth user and merge the new roles into the claims
    const user = await admin.auth().getUser(uid);
    const newClaims = { ...user.customClaims, roles: newRoles };
    return admin.auth().setCustomUserClaims(uid, newClaims);
});

Conclusion

Both approaches offer distinct advantages depending on your application's specific needs. Whether you prioritize broader service integration or a more focused, cost-effective solution within Firestore and Cloud Storage, understanding these options will empower you to make informed decisions about implementing role-based access control in your Firebase environment.