Bedingungen in Firebase Cloud Storage-Sicherheitsregeln verwenden

Dieser Leitfaden baut auf dem Leitfaden Firebase Security Rules-Kernsyntax auf. Sie erfahren hier, wie Sie Ihren Firebase Security Rules-Regeln für Cloud Storage Bedingungen hinzufügen.

Der primäre 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 können Sie die Literale true und false als Bedingungen verwenden. Mit der Firebase Security Rules-Sprache für Cloud Storage können Sie jedoch komplexere Bedingungen schreiben, die Folgendes ermöglichen:

  • Nutzerauthentifizierung prüfen
  • Eingehende Daten validieren

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 den 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 Ansprüche 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: request.auth ignorieren
  • Authentifiziert privat: Prüfen Sie, ob request.auth nicht null ist.
  • Nutzer privat: Prüfen Sie, ob request.auth.uid einem Pfad uid entspricht.
  • Gruppe „Privat“: 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 zu erstellen, die von einem Nutzer gesteuert wird. 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 Erlauben von Gruppenberechtigungen für ein Objekt, z. B. wenn mehrere Teammitglieder an einem freigegebenen Dokument zusammenarbeiten sollen. Dafür gibt es mehrere Möglichkeiten:

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

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 (siehe oben) 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 außerdem 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 request-Objekt finden Sie unten:

Attribut Typ Beschreibung
auth map<string, string> Wenn ein Nutzer angemeldet ist, werden uid, die eindeutige ID des Nutzers, und token, eine Karte mit Firebase Authentication-JWT-Anforderungen, bereitgestellt. Andernfalls ist es null.
params map<string, string> Map mit den Abfrageparametern der Anfrage.
path Pfad Ein path, das den Pfad darstellt, für den die Anfrage ausgeführt wird.
resource map<string, string> Der neue Ressourcenwert, der nur in write-Anfragen vorhanden ist.
time timestamp Ein Zeitstempel, der die Serverzeit angibt, zu der die Anfrage ausgewertet wird.

Ressourcenbewertung

Bei der Auswertung 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 Sie beispielsweise nur Dateien mit bestimmten Inhaltstypen hochladen oder nur Dateien löschen lassen, 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 Eigenschaften können in read- oder write-Anfragen geprüft werden, um die Datenintegrität zu gewährleisten.

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 derzeit unter dem Anfragepfad vorhanden ist, 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 resource-Objekt finden Sie unten:

Attribut Typ Beschreibung
name String Der vollständige Name des Objekts
bucket String Der Name des Buckets, in dem sich dieses Objekt befindet.
generation int Die Google Cloud Storage-Objektgenerierung dieses Objekts.
metageneration int Die Google Cloud Storage-Objekt-Metagenerierung dieses Objekts.
size int Größe des Objekts in Byte.
timeCreated timestamp Ein Zeitstempel, der angibt, wann ein Objekt erstellt wurde.
updated timestamp Ein Zeitstempel, der angibt, wann ein Objekt zuletzt aktualisiert wurde.
md5Hash String Ein MD5-Hash des Objekts.
crc32c String Ein CRC32C-Hash des Objekts.
etag String Das ETag, das diesem Objekt zugeordnet ist.
contentDisposition String Die Inhaltsdisposition, die diesem Objekt zugeordnet ist.
contentEncoding String Die mit diesem Objekt verknüpfte Inhaltscodierung.
contentLanguage String Die mit diesem Objekt verknüpfte Sprache des Inhalts.
contentType String Der Inhaltstyp, der diesem Objekt zugeordnet ist.
metadata map<string, string> Schlüssel/Wert-Paare für zusätzliche, vom Entwickler angegebene benutzerdefinierte Metadaten.

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. 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 mithilfe der $(variable)-Syntax explizit ausschließen.

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)).memberships
    }
  }
}
 Im nächsten Beispiel können nur die Freunde eines Nutzers seine Fotos sehen. 
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))
    }
  }
}

Sobald 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 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 Dateimetadateneigenschaften 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 Gruppen von Bedingungen in Funktionen verpacken, die Sie in Ihrem Regelsatz wiederverwenden können. Sicherheitsregeln unterstützen benutzerdefinierte Funktionen. Die Syntax für benutzerdefinierte Funktionen ähnelt in etwa JavaScript, die Firebase Security Rules-Funktionen sind jedoch in einer domainspezifischen Sprache geschrieben, die einige wichtige Einschränkungen aufweist:

  • 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. Beispiel: Eine Funktion, die im Bereich service firebase.storage definiert ist, hat Zugriff auf die resource-Variable sowie auf integrierte Funktionen wie get() und exists() (nur für Cloud Firestore).
  • 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 mithilfe des Schlüsselworts let definieren. Für Funktionen sind beliebig viele 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();
    }
  }
}

Die Verwendung von Funktionen in Ihrem Firebase Security Rules sorgt dafür, dass sie besser gepflegt werden können, da 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 zum Umgang mit wichtigen Anwendungsfällen und zum Workflow für die Entwicklung, das Testen und die Bereitstellung von Regeln: