Sicherheitsregeln für Pipelinevorgänge

Sicherheitsregeln für Pipelinevorgänge

Mit Pipelinevorgangsregeln können Sie die Filterfunktionen der vorhandenen Regel-Engine nutzen. Pipeline-Vorgänge bieten zwar eine Vielzahl von Funktionen, die Regel-Engine ist jedoch auf die Erkennung einfacher Filter beschränkt, um die Erfüllbarkeit und Sicherheit von Abfragen zu gewährleisten.

Anforderungen an Version und Modus

Dieses Dokument gilt für die Firestore Enterprise-Version im nativen Modus.

Unterstützte Filterausdrücke

Damit eine Abfrage durch Ihre Regeln eingeschränkt wird, müssen Standardvergleichsoperatoren für Konstanten verwendet werden. Die folgenden Filtertypen werden von der Regel-Engine erkannt:

• Gleichheit und Ungleichheit: eq, neq.
• Vergleiche: gt, gte, lt, lte.
• Mitgliedschaft: in, arrayContains.

Hier sind einige Beispiele:

• where(eq("foo", 2))
• where(lt("foo", 2))
• documents("/user/1", "/user/2").where(...)

Hinweis: Komplexe Ausdrücke wie Arithmetik innerhalb eines Filters (z. B. where(eq("foo" * 2, 10))) oder Stringfunktionen wie strContains werden für die Einschränkung von Abfragen nicht erkannt.

Anfrageattribute

Sie können das Objekt request weiterhin verwenden, um die Authentifizierung und den Abfragekontext zu validieren. Einige Attribute, die in Standardabfragen verfügbar sind, werden jedoch in Pipelines nicht unterstützt.

Unterstützte Properties

Die neue Engine unterstützt weiterhin die folgenden Properties:

• request.auth: Zugriff auf UID- und Token-Daten des Nutzers.
• request.method: Identifiziert den Vorgang (z. B. get, list).
• request.path: Der Pfad der Ressource, auf die zugegriffen wird.
• request.time: Der serverseitige Zeitstempel der Anfrage.

Nicht unterstützte Properties

Die request.query-Attribute wie limit, offset und orderBy werden für Pipelines-Regelprüfungen nicht unterstützt, da es komplex ist, diese Werte in mehrstufigen Abfragen zu bestimmen.

Verarbeitung und Berechtigungen für Pipelinephasen

Es gibt verschiedene Pipelinephasen, die bestimmten detaillierten Vorgängen in Sicherheitsregeln zugeordnet sind:

• allow list-Berechtigungen: Werden durch die Phasen collection(), collectionGroup() und database() ausgelöst.
• allow get-Berechtigungen: Werden durch die Phase documents() ausgelöst, die ähnlich wie ein get-Batchvorgang behandelt wird.
• allow create-Berechtigungen: Werden durch insert()-Phasen und upsert()-Phasen beim Erstellen neuer Dokumente ausgelöst.
• allow update-Berechtigungen: Werden durch update()-Phasen und upsert()-Phasen ausgelöst, wenn vorhandene Dokumente aktualisiert werden.
• allow delete-Berechtigungen: Ausgelöst durch delete()-Phasen.
• allow write-Berechtigungen: Gilt für alle DML-Vorgänge (insert(), update(), upsert() und delete()).
• Phasen der Feldänderung: Regeln werden nur auf gespeicherte Daten und nicht auf abgeleitete Werte angewendet. Wenn eine Pipeline Phasen enthält, die Felder ändern (z. B. AddFields, ReplaceWith, Select), wendet die Regel-Engine nach dieser Phase keine Filtereinschränkungen mehr an.
• Literale-Phase: In der Phase literals() wird nicht aus der Datenbank gelesen, es können jedoch Kosten anfallen. Um Missbrauch zu verhindern, muss sie mit einer anderen Phase (z. B. collection()) kombiniert werden, die durch Regeln überprüft werden kann.

Phasen der Datenbearbeitungssprache (DML) und Sicherheitsregeln

Beim Ausführen von DML-Phasen (Datenbearbeitungssprache) (insert(), update(), upsert() und delete()) werden Berechtigungen von Sicherheitsregeln anders bewertet als bei Leseabfragen:

• Regelbewertung pro Dokument: Im Gegensatz zu Lesepipelines, die Filterausdrücke im Voraus erfordern, um die Abfrage bei der Planung einzuschränken, werden bei DML-Vorgängen Sicherheitsregeln für jede einzelne Dokumentänderung ausgewertet.
• Regelvariablen:
  • request.resource: Enthält die vorgeschlagenen Dokumentdaten für die Vorgänge insert(), update() und upsert().
  • resource: Enthält die aktuellen Dokumentdaten, die vor der Änderung im Datenspeicher gespeichert wurden (verfügbar für update(), delete() und upsert() vorhandener Dokumente).

Systemlimits und Ausführungsverhalten mit DML

Beachten Sie beim Ausführen von DML-Vorgängen mit Sicherheitsregeln die folgenden Systemlimits und Ausführungsverhaltensweisen:

Das Limit von 20 Suchvorgängen für get() und exists()

Firebase-Sicherheitsregeln erlauben maximal 20 Dokumentabfragen (get() oder exists()) pro Anfrage.

Wenn eine DML-Pipeline außerhalb einer expliziten Transaktion ausgeführt wird, werden Dokumente in Batches verarbeitet. Da jeder Batch in einer eigenen Transaktion ausgeführt wird und Dokumente zwischen Batches gleichzeitig geändert werden können, werden Sicherheitsregeln und Dokumentabfragen für jeden Schreib-Batch neu ausgewertet.

Auch wenn Ihre Sicherheitsregeln anhand eines einzelnen statischen Dokuments ausgewertet werden, z. B. um zu prüfen, ob ein Nutzer ein Administrator ist:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /posts/{postId} {
      allow write: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.isAdmin == true;
    }
  }
}

Für jeden Schreib-Batch von Dokumenten wird ein Lookup durchgeführt. Nachdem alle möglichen Dokumente geschrieben wurden, ist das Limit von 20 Suchvorgängen für die Anfrage erreicht und die Pipeline schlägt mit dem Fehler PERMISSION_DENIED fehl. Darüber hinaus wird jede Suche, die pro Schreib-Batch ausgeführt wird, separat abgerechnet.

Tipp: Um das Limit von 20 Suchvorgängen bei Bulk-DML-Vorgängen nicht zu überschreiten, verwenden Sie benutzerdefinierte Anforderungen für Firebase Authentication-Tokens (z. B. request.auth.token.isAdmin == true) anstelle von get()- oder exists()-Suchvorgängen. Benutzerdefinierte Anforderungen werden im Arbeitsspeicher direkt aus dem Authentifizierungstoken validiert, wodurch Dokumentlesevorgänge und Suchlimits vollständig vermieden werden.

Teilweise erfolgreich und PERMISSION_DENIED

Wenn DML-Vorgänge außerhalb einer Transaktion ausgeführt werden, werden Schreibvorgänge in sequenziellen Batches festgeschrieben. Wenn ein Batch fehlschlägt, weil ein Dokument eine Regelbedingung nicht erfüllt oder das Limit von 20 Suchvorgängen überschritten wird, wird die Pipeline angehalten und ein PERMISSION_DENIED-Fehler zurückgegeben.

Batches, die bereits festgeschrieben wurden, werden jedoch nicht zurückgesetzt. Die Datenbank bleibt in einem teilweise aktualisierten Zustand. Da der Client einen Fehler ohne eine Liste der geänderten Dokumente erhält, müssen Sie Ihre Daten abfragen, um zu prüfen, welche Schreibvorgänge erfolgreich waren.

Tipp: Wenn Ihre Arbeitslast eine Alles-oder-Nichts-Ausführung erfordert, führen Sie die DML-Pipeline innerhalb einer expliziten Nutzertransaktion aus (z. B. mit runTransaction und transaction.execute(pipeline)). In einer Transaktion werden alle Vorgänge entweder zusammen committet oder bei einem Fehler vollständig zurückgesetzt. Beachten Sie, dass Transaktionen den Transaktionslimits der Firestore Enterprise-Version unterliegen.

Regelfehler mit Cloud-Audit-Logs diagnostizieren

Aus Sicherheitsgründen wird bei clientseitigen PERMISSION_DENIED-Fehlern nicht offengelegt, welche Sicherheitsregelbedingung fehlgeschlagen ist oder ob das Limit von 20 Suchvorgängen erreicht wurde.

Um Fehler bei der Regelauswertung zu diagnostizieren, können Projektadministratoren Cloud-Audit-Logs in der Google Cloud Console (unter Firestore > Monitoring oder im Log-Explorer) prüfen, um detaillierte EvaluationError-Einträge aufzurufen.