Bedingungen in Firebase Cloud Storage-Sicherheitsregeln verwenden

Dieser Leitfaden baut auf dem Leitfaden Firebase Security Rules-Kernsyntax auf und zeigt, wie Sie Bedingungen für Firebase Security Rules für Cloud Storage 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 ist es völlig ausreichend, die Literale true und false als Bedingungen zu verwenden. Mit der Firebase Security Rules für die Sprache Cloud Storage können Sie jedoch komplexere Bedingungen schreiben, die Folgendes ermöglichen:

• 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 wird in Firebase Authentication integriert, um eine leistungsstarke nutzerbasierte Authentifizierung für Cloud Storage zu ermöglichen. Dies ermöglicht eine detaillierte Zugriffssteuerung basierend auf Ansprüchen eines Firebase Authentication-Tokens.

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

Wenn Sie die benutzerdefinierte Authentifizierung verwenden, werden außerdem zusätzliche Behauptungen im Feld request.auth.token angezeigt.

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

Mit diesen Daten gibt es mehrere gängige Möglichkeiten, Dateien durch Authentifizierung zu schützen:

• Öffentlich: Ignoriere request.auth
• Authentifiziert privat: Prüfen Sie, ob request.auth nicht null ist.
• Nutzer privat: Prüfen Sie, ob request.auth.uid einem Pfad uid entspricht.
• Gruppenprivat: Die Ansprüche des benutzerdefinierten Tokens werden mit einem ausgewählten Anspruch abgeglichen oder die Dateimetadaten werden gelesen, um festzustellen, ob ein Metadatenfeld vorhanden ist.

Öffentlich

Jede Regel, bei der der request.auth-Kontext nicht berücksichtigt wird, kann als public-Regel betrachtet werden, da der Authentifizierungskontext des Nutzers nicht berücksichtigt wird. Diese Regeln können nützlich sein, um öffentliche Daten wie Spiel-Assets, Audiodateien oder andere statische Inhalte zu präsentieren.

// 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, aber nicht für nicht authentifizierte Nutzer sichtbar sind. 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 eine 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 ist die Bereitstellung detaillierter Berechtigungen für einzelne Nutzer für ihre Dateien, vom Hochladen von Profilbildern bis zum Lesen privater Dokumente.

Da Dateien in Cloud Storage einen vollständigen „Pfad“ zur Datei haben, ist nur eine eindeutige, nutzeridentifizierende Information im Dateinamenpräfix (z. B. die uid des Nutzers) erforderlich, um eine Datei einem Nutzer zuzuordnen. Diese Information kann bei der Auswertung der Regel geprüft werden:

// 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;
}

Gruppe privat

Ein weiterer ebenso häufiger Anwendungsfall ist das Zulassen von Gruppenberechtigungen für ein Objekt, z. B. wenn mehrere Teammitglieder an einem freigegebenen Dokument zusammenarbeiten sollen. Dafür gibt es mehrere Ansätze:

• Erstellen Sie ein Firebase Authentication benutzerdefiniertes Token, 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

Hochladen, Herunterladen, Metadatenänderungen und Löschvorgänge werden anhand der request bewertet, die an Cloud Storage gesendet werden. Zusätzlich zur eindeutigen ID des Nutzers und zur 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 es sich bei der Anfrage um einen Schreibvorgang handelt.

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

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

Ressourcenbewertung

Beim Auswerten von Regeln sollten Sie auch die Metadaten der Datei berücksichtigen, die hochgeladen, heruntergeladen, geändert oder gelöscht wird. So können Sie komplexe und leistungsstarke Regeln erstellen, mit denen beispielsweise nur Dateien mit bestimmten Inhaltstypen hochgeladen oder nur Dateien mit einer bestimmten Größe gelöscht werden dürfen.

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 Eigenschaften können in read- oder write-Anfragen geprüft werden, um die Datenintegrität sicherzustellen.

Bei write-Anfragen (z. B. Uploads, Metadatenaktualisierungen und Löschvorgänge) haben Sie zusätzlich zum resource-Objekt, das Dateimetadaten für die Datei enthält, die sich derzeit im Anfragepfad befindet, auch die Möglichkeit, das request.resource-Objekt zu 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 Anwendungsbeschränkungen wie Dateityp oder ‑größe erzwingen.

Eine vollständige Liste der Attribute im Objekt resource 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 in Cloud Firestore auf Dokumente zugreifen, um andere Autorisierungskriterien zu prüfen.

Mit den Funktionen firestore.get() und firestore.exists() können Ihre Sicherheitsregeln eingehende Anfragen anhand von Dokumenten in Cloud Firestore auswerten. Für die Funktionen firestore.get() und firestore.exists() sind jeweils vollständig angegebene Dokumentpfade erforderlich. Wenn Sie Variablen verwenden, um Pfade für firestore.get() und firestore.exists() zu erstellen, müssen Sie Variablen explizit mit der $(variable)-Syntax 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))
    }
  }
}

Wenn Sie Ihre erste Cloud Storage Security Rules erstellen und speichern, in der diese Cloud Firestore-Funktionen verwendet werden, werden Sie in der Firebase-Konsole oder der Firebase-CLI 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, sollten Sie Gruppen von Bedingungen in Funktionen einbinden, 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. Beispielsweise können damit keine Schleifen ausgeführt und keine externen Dienste aufgerufen werden.
• Funktionen bieten die Möglichkeit, automatisch auf Funktionen und Variablen aus dem Bereich zuzugreifen, in dem sie definiert sind. Eine Funktion, die im service firebase.storage-Bereich definiert ist, hat beispielsweise Zugriff auf die Variable resource und für Cloud Firestore nur 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 Keyword let definieren. Für Funktionen ist eine beliebige Anzahl von LET-Bindungen zulässig. Diese müssen aber mit einer Rückgabeanweisung 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 Ihren Firebase Security Rules verwenden, sind sie leichter zu verwalten, wenn die Komplexität Ihrer Regeln zunimmt.

Nächste Schritte

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

Informationen zur Behandlung von wichtigen Anwendungsfällen und zum Workflow für die Entwicklung, das Testen und die Bereitstellung von Regeln:

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