Bedingungen in Firebase Cloud Storage-Sicherheitsregeln verwenden

Dieser Leitfaden baut auf dem Leitfaden Grundlegende Syntax der Firebase Security Rules-Sprache lernen 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. Bei einfachen Regeln eignen sich true- und false-Literale als Bedingungen hervorragend. Mit der Firebase Security Rules für Cloud Storage-Sprache 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 ist in Firebase Authentication eingebunden und bietet Cloud Storage eine leistungsstarke nutzerbasierte Authentifizierung. So ist eine detaillierte Zugriffssteuerung basierend auf den Berechtigungen eines Firebase Authentication-Tokens möglich.

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) ausgefü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 stellt, hat die Variable request.auth den Wert null.

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

  • Öffentlich: ignorieren request.auth
  • Authentifiziert privat: Prüfen Sie, ob request.auth nicht null ist.
  • Nutzerprivat: Prüfen Sie, ob request.auth.uid einem Pfad uid entspricht.
  • Gruppe privat: Prüfen, ob die Behauptungen des benutzerdefinierten Tokens mit einer ausgewählten Behauptung übereinstimmen, oder die Dateimetadaten lesen, um zu prüfen, 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 Game-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, aber nicht 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 die Authentifizierung zu erzwingen:

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

Nur für Nutzer sichtbar

Der mit Abstand häufigste Anwendungsfall für request.auth besteht darin, einzelnen Nutzern detaillierte Berechtigungen für ihre Dateien zuzuweisen, vom Hochladen von Profilbildern bis zum Lesen privater Dokumente.

Da Dateien in Cloud Storage einen vollständigen Pfad zur Datei haben, ist für die Steuerung einer Datei durch einen Nutzer nur eine eindeutige, den Nutzer identifizierende Information im Dateinamenspräfix erforderlich (z. B. die uid des Nutzers), 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 häufig vorkommender Anwendungsfall ist die Zuweisung von Gruppenberechtigungen für ein Objekt, z. B. wenn mehrere Teammitglieder an einem freigegebenen Dokument zusammenarbeiten sollen. Dazu gibt es mehrere Möglichkeiten:

  • Erstelle ein Firebase Authentication benutzerdefiniertes Token, das zusätzliche Informationen zu einem Gruppenmitglied enthält (z. B. eine Gruppen-ID).
  • Füge den Dateimetadaten Gruppeninformationen wie einer Gruppen-ID oder einer Liste der autorisierten uids hinzu.

Sobald diese Daten in den Token- oder Dateimetadaten gespeichert sind, können sie in einer Regel referenziert 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 beantragen

Uploads, Downloads, Metadatenänderungen und Löschungen werden anhand der request bewertet, die an Cloud Storage gesendet wird. Zusätzlich zur eindeutigen ID des Nutzers und der Firebase Authentication-Nutzlast im request.auth-Objekt wie oben beschrieben enthält die Variable request den Dateipfad, unter dem die Anfrage ausgeführt wird, die Uhrzeit, zu der die Anfrage empfangen wird, und den neuen resource-Wert, falls es sich um eine Schreibanfrage handelt.

Das request-Objekt enthält außerdem die eindeutige ID des Nutzers und die Firebase Authentication-Nutzlast im request.auth-Objekt. Weitere Informationen dazu findest du im Abschnitt Nutzerbasierte Sicherheit der Dokumentation.

Unten finden Sie eine vollständige Liste der Attribute im request-Objekt:

Attribut Typ Beschreibung
auth map<string, string> Wenn ein Nutzer angemeldet ist, gibt er uid, die eindeutige ID des Nutzers, und token, eine Zuordnung von Firebase Authentication JWT-Ansprüchen, an. Andernfalls ist es null.
params map<string, string> Ein Dictionary mit den Abfrageparametern der Anfrage.
path Pfad Ein path, das den Pfad angibt, unter dem 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 können Sie auch die Metadaten der hochgeladenen, heruntergeladenen, geänderten oder gelöschten Dateien berücksichtigen. 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 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 zusätzlich zum resource-Objekt, das Dateimetadaten für die Datei enthält, die sich derzeit am Anfragepfad befindet, auch das request.resource-Objekt verwenden. Dieses enthält einen Teil der Dateimetadaten, die geschrieben werden sollen, sofern das Schreiben zulässig ist. Mit diesen beiden Werten können Sie die Datenintegrität gewährleisten oder Anwendungseinschränkungen wie Dateityp oder -größe erzwingen.

Unten finden Sie eine vollständige Liste der Attribute im resource-Objekt:

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-Objektmetagenerierung 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 Einen MD5-Hash des Objekts.
crc32c String Ein CRC32C-Hash des Objekts.
etag String Der mit diesem Objekt verknüpfte Etag.
contentDisposition String Die mit diesem Objekt verknüpfte Inhaltsdisposition.
contentEncoding String Die Inhaltscodierung, die mit diesem Objekt verknüpft ist.
contentLanguage String Die Sprache der Inhalte, die mit diesem Objekt verknüpft sind.
contentType String Der Inhaltstyp, der mit diesem Objekt verknüpft ist.
metadata map<string, string> Schlüssel/Wert-Paare für zusätzliche, vom Entwickler angegebene benutzerdefinierte Metadaten.

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

Mit Cloud Firestore optimieren

Sie können auf Dokumente in Cloud Firestore 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 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))
    }
  }
}

Nachdem Sie Ihre erste Cloud Storage Security Rules mit diesen Cloud Firestore-Funktionen erstellt und gespeichert haben, werden Sie in der Firebase Console oder in der 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 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 Dateinamen und Pfaden 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 und 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 Version rules2 können Funktionen Variablen mithilfe des Schlüsselworts let definieren. Funktionen können beliebig viele LET-Bindungen haben, müssen aber mit einer RETURN-Anweisung 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 Diskussion über Bedingungen haben Sie ein besseres Verständnis von Regeln und können Folgendes tun:

Weitere Informationen zum Umgang mit wichtigen Anwendungsfällen und zum Workflow für die Entwicklung, Prüfung und Bereitstellung von Regeln: