Grundlegende Syntax der Firebase-Sicherheitsregeln für Cloud Storage

Mit Firebase Security Rules für Cloud Storage können Sie den Zugriff auf Objekte steuern, die in Cloud Storage-Buckets gespeichert sind. Mit der flexiblen Regelsyntax können Sie Regeln erstellen, um jeden Vorgang zu steuern, von allen Schreibvorgängen in Ihrem Cloud Storage-Bucket bis hin zu Vorgängen für eine bestimmte Datei.

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.

In diesem Leitfaden werden die grundlegende Syntax und Struktur von Cloud Storage Security Rules zum Erstellen vollständiger Regelsätze beschrieben.

Dienste und Datenbanken deklarieren

Firebase Security Rules für Cloud Storage beginnen immer mit der folgenden Deklaration:

service firebase.storage {
    // ...
}

Mit der Deklaration service firebase.storage werden die Regeln auf Cloud Storage beschränkt, um Konflikte zwischen Cloud Storage Security Rules und Regeln für andere Produkte wie Cloud Firestore zu vermeiden.

Grundlegende Lese-/Schreibregeln

Grundlegende Regeln bestehen aus einer match-Anweisung, die Cloud Storage-Buckets identifiziert, einer Match-Anweisung, die einen Dateinamen angibt, und einem allow-Ausdruck, der festlegt, wann das Lesen der angegebenen Daten erlaubt ist. allow-Ausdrücke geben die beteiligten Zugriffsmethoden (z.B. Lesen, Schreiben) und die Bedingungen an, unter denen der Zugriff entweder zugelassen oder abgelehnt wird.

Im Standardregelsatz wird in der ersten match-Anweisung ein {bucket}-Platzhalterausdruck verwendet, um anzugeben, dass die Regeln für alle Buckets in Ihrem Projekt gelten. Im nächsten Abschnitt gehen wir näher auf das Konzept von Platzhalterübereinstimmungen ein.

service firebase.storage {
  // The {bucket} wildcard indicates we match files in all Cloud Storage buckets
  match /b/{bucket}/o {
    // Match filename
    match /filename {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

Alle match-Anweisungen verweisen auf Dateien. Eine Match-Anweisung kann auf eine bestimmte Datei verweisen, z. B. match /images/profilePhoto.png.

Platzhalter abgleichen

Security Rules kann nicht nur auf eine einzelne Datei verweisen, sondern auch Platzhalter verwenden, um auf eine beliebige Datei mit einem bestimmten Stringpräfix im Namen zu verweisen, einschließlich Schrägstrichen, wie in match /images/{imageId}.

In dem Beispiel oben verwendet die Match-Anweisung die Platzhaltersyntax {imageId}. Das bedeutet, dass die Regel für alle Dateien gilt, deren Name mit /images/ beginnt, z. B. /images/profilePhoto.png oder /images/croppedProfilePhoto.png. Wenn die allow-Ausdrücke in der Match-Anweisung ausgewertet werden, wird die Variable imageId in den Dateinamen des Images aufgelöst, z. B. profilePhoto.png oder croppedProfilePhoto.png.

Eine Platzhaltervariable kann innerhalb von match referenziert werden, um eine Autorisierung für Dateinamen oder Pfade zu ermöglichen:

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

Hierarchische Daten

Wie bereits erwähnt, gibt es in einem Cloud Storage-Bucket keine hierarchische Struktur. Wenn Sie jedoch eine Dateinamenskonvention verwenden, die oft Schrägstriche in Dateinamen enthält, können Sie eine Struktur nachahmen, die wie eine verschachtelte Reihe von Verzeichnissen und Unterverzeichnissen aussieht. Es ist wichtig zu verstehen, wie Firebase Security Rules mit diesen Dateinamen interagieren.

Angenommen, Sie haben eine Reihe von Dateien, deren Namen alle mit dem Stamm /images/ beginnen. Firebase Security Rules gilt nur für den übereinstimmenden Dateinamen. Die für den Stamm /images/ definierten Zugriffssteuerungen gelten also nicht für den Stamm /mp3s/. Schreiben Sie stattdessen explizite Regeln, die mit verschiedenen Dateinamensmustern übereinstimmen:

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      allow read, write: if <condition>;
    }

    // Explicitly define rules for the 'mp3s' pattern
    match /mp3s/{mp3Id} {
      allow read, write: if <condition>;
    }
  }
}

Wenn Sie match-Anweisungen verschachteln, wird der Pfad der inneren match-Anweisung immer an den Pfad der äußeren match-Anweisung angehängt. Die folgenden beiden Regelsätze sind daher äquivalent:

service firebase.storage {
  match /b/{bucket}/o {
    match /images {
      // Exact match for "images/profilePhoto.png"
      match /profilePhoto.png {
        allow write: if <condition>;
      }
    }
  }
}

service firebase.storage {
  match /b/{bucket}/o {
    // Exact match for "images/profilePhoto.png"
    match /images/profilePhoto.png {
      allow write: if <condition>;
      }
  }
}

Platzhalter für rekursive Übereinstimmungen

Zusätzlich zu Platzhaltern, die Strings am Ende eines Dateinamens abgleichen und zurückgeben, kann ein Platzhalter mit mehreren Segmenten für komplexere Abgleiche deklariert werden. Dazu wird =** an den Platzhalternamen angehängt, z. B. {path=**}:

// Partial match for files that start with "images"
match /images {

  // Exact match for "images/**"
  // e.g. images/users/user:12345/profilePhoto.png is matched
  // images/profilePhoto.png is also matched!
  match /{allImages=**} {
    // This rule matches one or more path segments (**)
    // allImages is a path that contains all segments matched
    allow read: if <other_condition>;
  }
}

Wenn mehrere Regeln auf eine Datei zutreffen, ist das Ergebnis das OR des Ergebnisses aller Regelbewertungen. Wenn also eine Regel, die auf die Datei zutrifft, als true ausgewertet wird, ist das Ergebnis true.

In den obigen Regeln kann die Datei „images/profilePhoto.png“ gelesen werden, wenn entweder condition oder other_condition als „true“ ausgewertet wird. Die Datei „images/users/user:12345/profilePhoto.png“ unterliegt dagegen nur dem Ergebnis von other_condition.

Cloud Storage Security Rules werden nicht kaskadiert und Regeln werden nur ausgewertet, wenn der Anfragepfad mit einem Pfad übereinstimmt, für den Regeln angegeben sind.

rules_version = '2';
service cloud.storage {
  match /b/{bucket}/o {
   ...
 }
}

rules_version = '2';
service firebase.storage {
 match /b/{bucket}/o {
   // Matches any file in a songs "subdirectory" under the
   // top level of your Cloud Storage bucket.
   match /{prefixSegment=**}/songs/{mp3filenames} {
     allow read, write: if <condition>;
   }
  }
}

Detaillierte Vorgänge

In manchen Fällen ist es sinnvoll, read und write in detailliertere Vorgänge zu untergliedern. Beispielsweise kann es sein, dass Ihre Anwendung für die Erstellung von Dateien andere Bedingungen erzwingen möchte als für das Löschen von Dateien.

Ein read-Vorgang kann in get und list unterteilt werden.

Eine write-Regel kann in create, update und delete unterteilt werden:

service firebase.storage {
  match /b/{bucket}/o {
    // A read rule can be divided into read and list rules
    match /images/{imageId} {
      // Applies to single file read requests
      allow get: if <condition>;
      // Applies to list and listAll requests (Security Rules Version 2)
      allow list: if <condition>;

    // A write rule can be divided into create, update, and delete rules
    match /images/{imageId} {
      // Applies to writes to file contents
      allow create: if <condition>;

      // Applies to updates to (pre-existing) file metadata
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
 }
}

Überlappende Match-Anweisungen

Ein Dateiname kann mit mehr als einer match-Anweisung übereinstimmen. Falls mehrere allow-Ausdrücke mit einer Anfrage übereinstimmen, wird der Zugriff erlaubt, wenneine der Bedingungen true ist:

service firebase.storage {
  match b/{bucket}/o {
    // Matches file names directly inside of '/images/'.
    match /images/{imageId} {
      allow read, write: if false;
    }

    // Matches file names anywhere under `/images/`
    match /images/{imageId=**} {
      allow read, write: if true;
    }
  }
}

Im obigen Beispiel sind alle Lese- und Schreibvorgänge für Dateien zulässig, deren Name mit /images/ beginnt, da die zweite Regel immer true ist, auch wenn die erste Regel false ist.

Regeln sind keine Filter

Nachdem Sie Ihre Daten gesichert haben und mit Dateioperationen beginnen, sollten Sie beachten, dass Sicherheitsregeln keine Filter sind. Sie können keine Vorgänge für eine Gruppe von Dateien ausführen, die einem Dateinamensmuster entsprechen, und erwarten, dass Cloud Storage nur auf die Dateien zugreift, für die der aktuelle Client Zugriffsberechtigungen hat.

Ein Beispiel ist die folgende Sicherheitsregel:

service firebase.storage {
  match /b/{bucket}/o {
    // Allow the client to read files with contentType 'image/png'
    match /aFileNamePrefix/{aFileName} {
      allow read: if resource.contentType == 'image/png';
    }
  }
}

Abgelehnt: Diese Regel lehnt die folgende Anfrage ab, da die Ergebnismenge Dateien enthalten kann, bei denen contentType nicht image/png ist:

filesRef = storage.ref().child("aFilenamePrefix");

filesRef.listAll()
    .then(function(result) {
      console.log("Success: ", result.items);
    })
});

Regeln in Cloud Storage Security Rules werten jede Abfrage anhand ihres potenziellen Ergebnisses aus und schlagen fehl, wenn eine Datei zurückgegeben werden könnte, für die der Client keine Leseberechtigung hat. Zugriffsanfragen müssen den Einschränkungen entsprechen, die durch Ihre Regeln festgelegt sind.

Nächste Schritte

So können Sie Ihr Verständnis von Firebase Security Rules für Cloud Storage vertiefen:

• Lernen Sie das nächste wichtige Konzept der Regelsprache kennen: dynamische Bedingungen. Damit können Sie in Ihren Regeln die Nutzerautorisierung prüfen, vorhandene und eingehende Daten vergleichen, eingehende Daten validieren und vieles mehr.

• Sehen Sie sich typische Sicherheitsanwendungsfälle und die Firebase Security Rules-Definitionen an, die sie behandeln.

Sie können Firebase Security Rules-Anwendungsfälle speziell für Cloud Storage ansehen: