Bedingungen in Firebase Cloud Storage-Sicherheitsregeln verwenden

Dieser Leitfaden baut auf dem Leitfaden zur Kernsyntax der Firebase Security Rules Sprache auf . Sie erfahren hier, wie Sie Ihren 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 grundlegende Regeln funktionieren die Literale true und false als Bedingungen einwandfrei. Die Firebase Security Rules für Cloud Storage Sprache bietet Ihnen jedoch Möglichkeiten, komplexere Bedingungen zu schreiben, mit denen Sie Folgendes tun können:

  • Nutzerauthentifizierung prüfen
  • Eingehende Daten validieren

Authentifizierung

Firebase Security Rules für Cloud Storage sind 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.

Bei Verwendung der benutzerdefinierten Authentifizierung werden außerdem zusätzliche Ansprüche im Feld request.auth.token angezeigt.

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

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

  • Öffentlich: request.auth ignorieren
  • Authentifiziert (privat): prüfen, ob request.auth nicht null ist
  • Nutzer (privat): prüfen, ob request.auth.uid mit einer uid im Pfad übereinstimmt
  • Gruppe (privat): Ansprüche des benutzerdefinierten Tokens prüfen, um sie mit einem ausgewählten Anspruch abzugleichen, oder Dateimetadaten lesen, um zu prüfen, 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 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 sichtbar sind, nicht aber 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 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 für eine Datei, die von einem Nutzer kontrolliert wird, nur eine eindeutige, nutzeridentifizierende Information im Dateinamenpräfix (z. B. die uid) erforderlich, die 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;
}

Gruppe (privat)

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. Dazu gibt es mehrere Ansätze:

  • Ein Firebase Authentication benutzerdefiniertes Token erstellen, 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 den Dateimetadaten aufnehmen

Sobald diese Daten im Token oder in den 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;
}

Anfrageauswertung

Uploads, Downloads, Metadatenänderungen und Löschvorgänge werden anhand der request an Cloud Storage gesendeten ausgewertet. Neben der 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 es sich um eine Schreibanfrage handelt.

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

Eine vollständige Liste der Attribute im Objekt request 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 Map der Firebase Authentication JWT-Ansprüche) bereitgestellt. Andernfalls ist der Wert null.
params map<string, string> Map mit den Suchparametern der Anfrage.
path path Ein path, der den Pfad darstellt, in dem die Anfrage ausgeführt wird.
resource map<string, string> Der neue Ressourcenwert, der nur bei write-Anfragen vorhanden ist.
time timestamp Ein Zeitstempel, der die Serverzeit darstellt, zu der die Anfrage ausgewertet wird.

Ressourcenauswertung

Bei der Auswertung von Regeln sollten 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 beispielsweise nur Dateien mit bestimmten Inhaltstypen hochgeladen oder nur Dateien mit einer bestimmten Größe gelöscht werden können.

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 zu gewährleisten.

Bei write Anfragen (z. B. Uploads, Metadatenaktualisierungen und Löschvorgänge) können Sie neben dem resource Objekt, das Dateimetadaten für die Datei enthält, die derzeit im Anfragepfad vorhanden ist, 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 gewährleisten oder Anwendungsbeschränkungen wie Dateityp oder -größe erzwingen.

Eine vollständige Liste der Attribute im Objekt resource 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 Integer Die Google Cloud Storage Objektgeneration dieses Objekts.
metageneration Integer Die Google Cloud Storage Objektmetageneration dieses Objekts.
size Integer Die Größe des Objekts in Byte.
timeCreated Zeitstempel Ein Zeitstempel, der die Erstellungszeit eines Objekts darstellt.
updated Zeitstempel Ein Zeitstempel, der die Zeit darstellt, zu der ein Objekt zuletzt aktualisiert wurde.
md5Hash String Ein MD5-Hash des Objekts.
crc32c String Ein CRC32C-Hash des Objekts.
etag String Das mit diesem Objekt verknüpfte ETag.
contentDisposition String Die mit diesem Objekt verknüpfte Inhaltsdisposition.
contentEncoding String Die mit diesem Objekt verknüpfte Inhaltsverschlüsselung.
contentLanguage String Die mit diesem Objekt verknüpfte Inhaltssprache.
contentType String Der mit diesem Objekt verknüpfte Inhaltstyp.
metadata map<string, string> Schlüssel/Wert-Paare zusätzlicher, vom Entwickler angegebener benutzerdefinierter Metadaten.

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

Mit Cloud Firestore optimieren

Sie können auf Dokumente in Cloud Firestore zugreifen, um andere Autorisierung kriterien auszuwerten.

Mit den Funktionen firestore.get() und firestore.exists() können Ihre Sicherheits regeln eingehende Anfragen anhand von Dokumenten in Cloud Firestore auswerten. Die Funktionen firestore.get() und firestore.exists() erwarten 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 Syntax $(variable) 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)).data.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 ersten Cloud Storage Security Rules erstellt und gespeichert haben, die diese Cloud Firestore Funktionen verwenden, werden Sie in der Firebase Console oder Firebase CLI aufgefordert, Berechtigungen zu aktivieren, um die beiden Produkte zu verbinden.

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

Daten validieren

Firebase Security Rules für Cloud Storage können auch zur 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 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 service firebase.storage Bereich definiert ist, hat Zugriff auf die resource Variable sowie (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 der 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 Ihren 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 Folgendes tun:

Informationen zu den wichtigsten Anwendungsfällen und zum Workflow für die Entwicklung, das Testen und die Bereitstellung von Regeln :