Bedingungen in Firebase Cloud Storage-Sicherheitsregeln verwenden

Dieser Leitfaden baut auf dem Leitfaden Informationen zur Kernsyntax der Sprache Firebase Security Rules auf, um zu zeigen, wie du Bedingungen zu Firebase Security Rules für Cloud Storage hinzufügen kannst.

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 Sprache Firebase Security Rules für die Sprache 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 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 für Cloud Storage ausführt, wird die Variable request.auth mit dem uid (request.auth.uid) des Nutzers und den Anforderungen des Firebase Authentication-JWT (request.auth.token) ausgefüllt.

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

Wenn ein nicht authentifizierter Nutzer eine Anfrage ausführt, lautet die Variable request.auth null.

Es gibt mehrere gängige Möglichkeiten, diese Daten zu verwenden, um Dateien zu sichern:

  • Öffentlich: ignorieren request.auth
  • Privat authentifiziert: 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 Berechtigungen des benutzerdefinierten Tokens mit einer ausgewählten Berechtigung ü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 Gewährung 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).
  • Gruppeninformationen (z. B. eine Gruppen-ID oder eine Liste autorisierter uids) in die Dateimetadaten aufnehmen.

Nachdem 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;
}

Bewertung anfordern

Uploads, Downloads sowie Änderungen und Löschungen von Metadaten werden mithilfe der an Cloud Storage gesendeten request ausgewertet. 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, den Zeitpunkt, zu dem die Anfrage empfangen wurde, und den neuen resource-Wert, wenn die Anfrage ein Schreibvorgang ist.

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.

Eine vollständige Liste der Eigenschaften im Objekt request findest du unten:

Attribut Typ Beschreibung
auth map<string, string> Wenn ein Nutzer angemeldet ist, stellt er uid, die eindeutige ID des Nutzers und token, eine Zuordnung der Firebase Authentication-JWT-Anforderungen, bereit. Andernfalls ist es null.
params map<string, string> Ein Dictionary mit den Abfrageparametern der Anfrage.
path Pfad Ein path, der den Pfad darstellt, unter 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 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 in einem Cloud Storage-Objekt angezeigten Metadaten enthält. 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 Metageneration für das Google Cloud Storage-Objekt dieses Objekts.
size int Größe des Objekts in Byte.
timeCreated timestamp Ein Zeitstempel, der den Zeitpunkt angibt, zu dem 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 Der mit diesem Objekt verknüpfte Etag.
contentDisposition String Die mit diesem Objekt verknüpfte Inhaltsdisposition.
contentEncoding String Die Inhaltscodierung, die diesem Objekt zugeordnet 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 Parameter 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 bewerten.

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 erstellt und gespeichert haben, die diese Cloud Firestore-Funktionen verwenden, werden Sie in der Firebase-Konsole oder der Firebase-Befehlszeile aufgefordert, die Berechtigungen zum Verbinden der beiden Produkte zu aktivieren.

Sie können das Feature 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 ein wenig JavaScript, allerdings sind Firebase Security Rules-Funktionen 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: