Understand the request.auth object

When a user is authenticated, request.auth contains their info:

// request.auth structure
{
  uid: "user123",           // Unique user ID
  token: {
    email: "user@example.com",
    email_verified: true,
    name: "John Doe",
    // Custom claims you've set
    admin: true,
    role: "premium"
  }
}

If the user is not authenticated, request.auth is null.

Require authentication for all access

Start by locking down everything to authenticated users only:

// Firestore rules
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Default: deny all
    match /{document=**} {
      allow read, write: if false;
    }

    // Require authentication for specific collections
    match /posts/{postId} {
      allow read: if request.auth != null;
      allow write: if request.auth != null;
    }
  }
}

Implement user-owned data rules

Ensure users can only access their own data:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // User profiles - users can only read/write their own
    match /users/{userId} {
      allow read, write: if request.auth != null
                         && request.auth.uid == userId;
    }

    // User's private data
    match /users/{userId}/private/{document} {
      allow read, write: if request.auth != null
                         && request.auth.uid == userId;
    }

    // Orders - users can only see their own orders
    match /orders/{orderId} {
      allow read: if request.auth != null
                  && request.auth.uid == resource.data.userId;
      allow create: if request.auth != null
                    && request.auth.uid == request.resource.data.userId;
    }
  }
}

Add role-based access with custom claims

First, set custom claims in your backend:

// Node.js Admin SDK - set user as admin
const admin = require('firebase-admin');

async function setAdminRole(uid) {
  await admin.auth().setCustomUserClaims(uid, { admin: true });
}

// Set premium role
async function setPremiumRole(uid) {
  await admin.auth().setCustomUserClaims(uid, { role: 'premium' });
}

Then check claims in your rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Admin-only collection
    match /admin/{document=**} {
      allow read, write: if request.auth != null
                         && request.auth.token.admin == true;
    }

    // Premium content
    match /premium-content/{docId} {
      allow read: if request.auth != null
                  && request.auth.token.role == 'premium';
    }

    // Public content anyone authenticated can read
    match /public/{docId} {
      allow read: if request.auth != null;
      allow write: if request.auth != null
                   && request.auth.token.admin == true;
    }
  }
}

Alternative: Store roles in Firestore

If you can't use custom claims, store roles in a collection:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Helper function to check admin status
    function isAdmin() {
      return get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin';
    }

    // Helper function to check any role
    function hasRole(role) {
      return get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == role;
    }

    match /admin-settings/{docId} {
      allow read, write: if request.auth != null && isAdmin();
    }

    match /premium/{docId} {
      allow read: if request.auth != null && hasRole('premium');
    }
  }
}

Test your rules with the Emulator

Use the Firebase Emulator Suite to test rules locally:

# Install and start emulators
firebase emulators:start

# Run rules tests
firebase emulators:exec "npm test"

Write unit tests for your rules:

// rules.test.js
const { assertSucceeds, assertFails } = require('@firebase/rules-unit-testing');

describe('Firestore rules', () => {
  it('allows users to read their own data', async () => {
    const db = getFirestore({ uid: 'user123' });
    await assertSucceeds(db.collection('users').doc('user123').get());
  });

  it('denies users from reading other users data', async () => {
    const db = getFirestore({ uid: 'user123' });
    await assertFails(db.collection('users').doc('other-user').get());
  });

  it('denies unauthenticated access', async () => {
    const db = getFirestore(null); // No auth
    await assertFails(db.collection('users').doc('anyone').get());
  });
});