Bedingungen in Firebase Cloud Storage-Sicherheitsregeln verwenden

Dieser Leitfaden baut auf dem Leitfaden Grundlegende Syntax der Firebase Security Rules-Sprache erlernen auf und zeigt, wie Sie Ihrer Firebase Security Rules für Cloud Storage Bedingungen hinzufügen.

Der wichtigste Baustein von Cloud Storage Security Rules ist die Bedingung. Eine Bedingung ist ein boolescher Ausdruck, der festlegt, ob ein bestimmter Vorgang zulässig oder nicht zulässig ist. Für einfache Regeln funktioniert die Verwendung von true- und false-Literalen als Bedingungen einwandfrei. Die Firebase Security Rules für die Sprache Cloud Storage bietet Ihnen jedoch die Möglichkeit, komplexere Bedingungen zu schreiben, die Folgendes können:

• Nutzerauthentifizierung prüfen
• Eingehende Daten validieren

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Cloud Storage data.

Authentifizierung

Firebase Security Rules für Cloud Storage lässt sich in Firebase Authentication einbinden, um eine leistungsstarke nutzerbasierte Authentifizierung für Cloud Storage bereitzustellen. Dies ermöglicht eine detaillierte Zugriffssteuerung basierend auf Anforderungen eines Firebase Authentication-Tokens.

Wenn ein authentifizierter Nutzer eine Anfrage an Cloud Storage stellt, wird die Variable request.auth mit der uid (request.auth.uid) des Nutzers sowie den Anforderungen des Firebase Authentication-JWT (request.auth.token) gefüllt.

Außerdem werden bei der Verwendung der benutzerdefinierten Authentifizierung zusätzliche Anforderungen im Feld request.auth.token angezeigt.

Wenn ein nicht authentifizierter Nutzer eine Anfrage stellt, ist die Variable request.auth null.

Anhand dieser Daten gibt es mehrere gängige Möglichkeiten, Dateien mithilfe der Authentifizierung zu schützen:

• Öffentlich: request.auth ignorieren
• Authentifiziert privat: Prüfen Sie, ob request.auth nicht null ist.
• Privat (Nutzer): Prüfen, ob request.auth.uid mit dem Pfad uid übereinstimmt
• Gruppe privat: Prüfen Sie die Anforderungen des benutzerdefinierten Tokens, um eine ausgewählte Anforderung abzugleichen, oder lesen Sie die Dateimetadaten, um zu sehen, ob ein Metadatenfeld vorhanden ist.

Öffentlich

Jede Regel, die den request.auth-Kontext nicht berücksichtigt, kann als public-Regel betrachtet werden, da sie den Authentifizierungskontext des Nutzers nicht berücksichtigt. Diese Regeln können nützlich sein, um öffentliche Daten wie Spiel-Assets, Audiodateien oder andere statische Inhalte bereitzustellen.

// Anyone to read a public image if the file is less than 100kB
// Anyone can upload a public file ending in '.txt'
match /public/{imageId} {
  allow read: if resource.size < 100 * 1024;
  allow write: if imageId.matches(".*\\.txt");
}

Authentifiziert privat

In bestimmten Fällen möchten Sie möglicherweise, dass Daten für alle authentifizierten Nutzer Ihrer Anwendung sichtbar sind, aber nicht für nicht authentifizierte Nutzer. Da die Variable request.auth für alle nicht authentifizierten Nutzer null ist, müssen Sie nur prüfen, ob die Variable request.auth vorhanden ist, um die Authentifizierung zu erzwingen:

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

Nutzer (privat)

Der mit Abstand häufigste Anwendungsfall für request.auth besteht darin, einzelnen Nutzern detaillierte Berechtigungen für ihre Dateien zu gewähren, vom Hochladen von Profilbildern bis zum Lesen privater Dokumente.

Da Dateien in Cloud Storage einen vollständigen „Pfad“ zur Datei haben, ist für die Steuerung einer Datei durch einen Nutzer nur ein eindeutiges, personenidentifizierbares Informationselement im Dateinamenpräfix (z. B. die uid des Nutzers) erforderlich, das bei der Auswertung der Regel geprüft werden kann:

// Only a user can upload their profile picture, but anyone can view it
match /users/{userId}/profilePicture.png {
  allow read;
  allow write: if request.auth.uid == userId;
}

Private Gruppe

Ein weiterer, ebenso häufiger Anwendungsfall ist das Zulassen von Gruppenberechtigungen für ein Objekt, z. B. um mehreren Teammitgliedern die Zusammenarbeit an einem freigegebenen Dokument zu ermöglichen. Dafür gibt es mehrere Ansätze:

• Erstellen Sie ein benutzerdefiniertes Token vom Typ Firebase Authentication, das zusätzliche Informationen zu einem Gruppenmitglied enthält (z. B. eine Gruppen-ID).
• Gruppeninformationen (z. B. eine Gruppen-ID oder eine Liste autorisierter uids) in die Dateimetadaten aufnehmen

Sobald diese Daten in den Token- oder Dateimetadaten gespeichert sind, kann in einer Regel darauf verwiesen werden:

// Allow reads if the group ID in your token matches the file metadata's `owner` property
// Allow writes if the group ID is in the user's custom token
match /files/{groupId}/{fileName} {
  allow read: if resource.metadata.owner == request.auth.token.groupId;
  allow write: if request.auth.token.groupId == groupId;
}

Bewertung anfordern

Uploads, Downloads, Metadatenänderungen und Löschungen werden anhand der request ausgewertet, die an Cloud Storage gesendet werden. Zusätzlich zur eindeutigen ID des Nutzers und der Firebase Authentication-Nutzlast im request.auth-Objekt, wie oben beschrieben, enthält die Variable request den Dateipfad, in dem die Anfrage ausgeführt wird, die Uhrzeit, zu der die Anfrage empfangen wird, und den neuen resource-Wert, wenn die Anfrage ein Schreibvorgang ist.

Das Objekt request enthält außerdem die eindeutige ID des Nutzers und die Nutzlast Firebase Authentication im Objekt request.auth. Dies wird im Abschnitt Nutzerbasierte Sicherheit der Dokumentation näher erläutert.

Eine vollständige Liste der Properties im request-Objekt finden Sie unten:

Ressourcenbewertung

Beim Auswerten von Regeln können Sie auch die Metadaten der Datei auswerten, die hochgeladen, heruntergeladen, geändert oder gelöscht wird. So können Sie komplexe und leistungsstarke Regeln erstellen, mit denen Sie beispielsweise nur Dateien mit bestimmten Inhaltstypen hochladen oder nur Dateien löschen können, die eine bestimmte Größe überschreiten.

Firebase Security Rules für Cloud Storage stellt Dateimetadaten im resource-Objekt bereit, das Schlüssel/Wert-Paare der Metadaten enthält, die in einem Cloud Storage-Objekt angezeigt werden. Diese Attribute können bei read- oder write-Anfragen geprüft werden, um die Datenintegrität sicherzustellen.

Bei write-Anfragen (z. B. Uploads, Metadatenaktualisierungen und Löschvorgänge) können Sie zusätzlich zum resource-Objekt, das Dateimetadaten für die Datei enthält, die sich derzeit im Anfragepfad befindet, auch das request.resource-Objekt verwenden. Dieses enthält eine Teilmenge der Dateimetadaten, die geschrieben werden sollen, wenn der Schreibvorgang zulässig ist. Mit diesen beiden Werten können Sie die Datenintegrität sicherstellen oder Anwendungseinschränkungen wie Dateityp oder -größe erzwingen.

Eine vollständige Liste der Properties im resource-Objekt finden Sie unten:

request.resource enthält alle diese Elemente mit Ausnahme von generation, metageneration, etag, timeCreated und updated.

Mit Cloud Firestore optimieren

Sie können auf Dokumente in Cloud Firestore zugreifen, um andere Autorisierungskriterien zu bewerten.

Mit den Funktionen firestore.get() und firestore.exists() können Ihre Sicherheitsregeln eingehende Anfragen anhand von Dokumenten in Cloud Firestore bewerten. Die Funktionen firestore.get() und firestore.exists() erwarten beide vollständig angegebene Dokumentpfade. Wenn Sie Variablen verwenden, um Pfade für firestore.get() und firestore.exists() zu erstellen, müssen Sie Variablen explizit mit der Syntax $(variable) maskieren.

Im folgenden Beispiel sehen wir eine Regel, die den Lesezugriff auf Dateien auf Nutzer beschränkt, die Mitglieder bestimmter Clubs sind.

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{club}/files/{fileId} {
      allow read: if club in
        firestore.get(/databases/(default)/documents/users/$(request.auth.id)).data.memberships
    }
  }
}

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{userId}/photos/{fileId} {
      allow read: if
        firestore.exists(/databases/(default)/documents/users/$(userId)/friends/$(request.auth.id))
    }
  }
}

Nachdem Sie die ersten Cloud Storage Security Rules erstellt und gespeichert haben, die diese Cloud Firestore-Funktionen verwenden, werden Sie in der Firebase-Konsole oder der Firebase-Befehlszeile aufgefordert, Berechtigungen zum Verbinden der beiden Produkte zu aktivieren.

Sie können die Funktion deaktivieren, indem Sie eine IAM-Rolle entfernen, wie unter Firebase Security Rules verwalten und bereitstellen beschrieben.

Daten validieren

Firebase Security Rules für Cloud Storage kann auch für die Datenvalidierung verwendet werden, einschließlich der Validierung von Dateiname und -pfad sowie von Dateimetadatenattributen wie contentType und size.

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      // Only allow uploads of any image file that's less than 5MB
      allow write: if request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

Benutzerdefinierte Funktionen

Wenn Ihre Firebase Security Rules komplexer werden, können Sie Bedingungssätze in Funktionen verpacken, die Sie in Ihrem Regelsatz wiederverwenden können. Sicherheitsregeln unterstützen benutzerdefinierte Funktionen. Die Syntax für benutzerdefinierte Funktionen ähnelt JavaScript, aber Firebase Security Rules-Funktionen werden in einer domänenspezifischen Sprache geschrieben, die einige wichtige Einschränkungen hat:

• Funktionen können nur eine einzige return-Anweisung enthalten. Es ist keine zusätzliche Logik möglich. Sie können beispielsweise keine Schleifen ausführen oder externe Dienste aufrufen.
• Funktionen bieten die Möglichkeit, automatisch auf Funktionen und Variablen aus dem Bereich zuzugreifen, in dem sie definiert sind. Eine im service firebase.storage-Bereich definierte Funktion hat beispielsweise Zugriff auf die Variable resource und nur für Cloud Firestore auf integrierte Funktionen wie get() und exists().
• Funktionen können andere Funktionen aufrufen, werden jedoch möglicherweise nicht rekursiv. Die Tiefe des Aufrufstapels ist auf 10 begrenzt.
• In Version rules2 können Funktionen Variablen mit dem Schlüsselwort let definieren. Funktionen können eine beliebige Anzahl von let-Bindungen haben, müssen aber mit einer return-Anweisung enden.

Eine Funktion wird mit dem Keyword function definiert und benötigt null oder mehr Argumente. Beispielsweise können Sie die beiden in den obigen Beispielen verwendeten Bedingungsarten in einer einzigen Funktion kombinieren:

service firebase.storage {
  match /b/{bucket}/o {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }
    match /images/{imageId} {
      allow read, write: if signedInOrPublic();
    }
    match /mp3s/{mp3Ids} {
      allow read: if signedInOrPublic();
    }
  }
}

Wenn Sie Funktionen in Ihrer Firebase Security Rules verwenden, sind sie leichter zu verwalten, wenn die Komplexität Ihrer Regeln zunimmt.

Nächste Schritte

Nach dieser Erläuterung von Bedingungen haben Sie ein besseres Verständnis von Regeln und können Folgendes tun:

Hier erfahren Sie, wie Sie die wichtigsten Anwendungsfälle abdecken und wie der Workflow für die Entwicklung, das Testen und die Bereitstellung von Regeln aussieht:

• Schreiben Sie Regeln für gängige Szenarien.
• Erweitern Sie Ihr Wissen, indem Sie sich Situationen ansehen, in denen Sie unsichere Regeln erkennen und vermeiden müssen.
• Testen Sie Regeln mit dem Cloud Storage-Emulator und der speziellen Testbibliothek für Sicherheitsregeln.
• Sehen Sie sich die verfügbaren Methoden zum Bereitstellen von Security Rules an.