Poznaj podstawową składnię reguł zabezpieczeń Firebase dla Cloud Storage

Firebase Security Rules w domenie Cloud Storage pozwala kontrolować dostęp do przechowywanych obiektów w Cloud Storage zasobnikach. Elastyczna składnia reguł umożliwia tworzenie reguł, które kontrolują każdą operację, od wszystkich zapisów w Twoim zbiorniku Cloud Storage po operacje na określonym pliku.

Uwaga: zasobniki w tabeli Cloud Storage zawierają tylko pliki i nie zawierają i katalogów. Na tej stronie nazwy plików będą zawierać ukośniki /, takie jak /images/profilePhoto.png, który sugeruje istnienie hierarchii katalogów. i podkatalogi w zasobniku. Nazwy plików mogą jednak zawierać prefiksy ze ukośnikami, co umożliwia definiowanie unikalnych nazw plików, które wyglądają jak pełne ścieżki katalogów, jakie zwykle widzimy w systemach plików.

W tym przewodniku opisano podstawową składnię i strukturę komponentów Cloud Storage Security Rules w aby utworzyć kompletne zestawy reguł.

Deklaracja dotycząca usługi i bazy danych

Firebase Security Rules w przypadku elementu Cloud Storage zawsze zaczyna się od tej deklaracji:

service firebase.storage {
    // ...
}

Deklaracja service firebase.storage ogranicza zakres reguł do Cloud Storage, zapobiegając konfliktom między Cloud Storage Security Rules a regułami dotyczącymi innych usług, takich jak Cloud Firestore.

Podstawowe reguły odczytu/zapisu

Reguły podstawowe składają się z instrukcji match identyfikującej Cloud Storage zasobnika, instrukcję dopasowania określającą nazwę pliku oraz wyrażenie allow przy odczytywaniu określonych danych. Wyrażenia allow określają metody dostępu (np. odczyt, zapis) oraz warunki, na jakich dostęp jest dozwolony lub odmówiony.

W domyślnym zestawie reguł pierwsza instrukcja match używa symbolu wieloznacznego {bucket} wskazuje, że reguły mają zastosowanie do wszystkich zasobników w projekcie. Na Omówimy koncepcję dopasowań z symbolami wieloznacznymi w następnej sekcji.

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

Wszystkie instrukcje dopasowania wskazują pliki. Wyrażenie dopasowania może wskazywać określony element, taki jak match /images/profilePhoto.png.

Dopasuj symbole wieloznaczne

Oprócz wskazywania pojedynczego pliku pole Rules może używać symboli wieloznacznych, aby wskazywać dowolny plik z danym ciągiem znaków w nazwie, w tym z ukośnikami, jak w przypadku match /images/{imageId}.

W powyższym przykładzie instrukcja dopasowania używa składni zastępnika {imageId}. Oznacza to, że reguła dotyczy każdego pliku, którego nazwa zaczyna się od /images/, na przykład /images/profilePhoto.png lub /images/croppedProfilePhoto.png. Gdy wyrażenia allow w oświadczeniu dopasowania zostaną ocenione, zmienna imageId zostanie zastąpiona nazwą pliku obrazu, np. profilePhoto.png lub croppedProfilePhoto.png.

W match można się odwoływać do zmiennej z symbolem wieloznacznym, aby dostarczyć plik autoryzacja nazwy lub ścieżki:

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

Uwaga: użytkownicy mają dostęp tylko do plików, na które zezwala Twoja aplikacja Firebase Security Rules dostęp. Na przykład reguły pokazane powyżej zezwalają na dostęp tylko do plików z /images/ na początku nazwy, a co za tym idzie, blokują dostęp do plików z innymi prefiksami nazw.

Dane hierarchiczne

Jak już wspomnieliśmy, w zasośniku Cloud Storage nie ma struktury hierarchicznej. Ale dzięki zastosowaniu konwencji nazewnictwa plików, która często obejmuje ukośniki w nazwach plików, możemy odwzorować strukturę przypominającą wbudowany ciąg katalogów i podkatalogów. Musisz wiedzieć, jak Firebase Security Rules działa z tymi nazwami plików.

Rozważ sytuację, w której masz zestaw plików o nazwach zaczynających się od /images/. Firebase Security Rules mają zastosowanie tylko do dopasowanego pliku, więc kontrola dostępu zdefiniowana w podstwie /images/ nie ma zastosowania do podrzędnego elementu /mp3s/. Zamiast tego utwórz jawne reguły, które pasują do różnych wzorców nazw plików:

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

Gdy zagnieżdżasz instrukcje match, ścieżka wewnętrznej instrukcji match jest zawsze dołączana do ścieżki zewnętrznej instrukcji match. Dlatego te 2 zestawy reguł są równoważne:

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

Symbole wieloznaczne dopasowania rekurencyjnego

Oprócz symboli wieloznacznych, które dopasowują i zwracają ciągi znaków na końcu nazwy pliku, możesz zadeklarować symbol wieloznaczny z wieloma segmentami, aby uzyskać bardziej złożone dopasowanie. W tym celu dodaj do nazwy symbolu wieloznacznego znak =**, np. {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>;
  }
}

Jeśli do pliku pasuje wiele reguł, wynik to OR wszystkich reguł weryfikacji reguł. Oznacza to, że jeśli dowolna reguła pasująca do pliku zwraca wartość true, wynik to true.

W powyżej podanych regułach plik „images/profilePhoto.png” może być odczytywany, jeśli albo condition, albo other_condition zwraca wartość „prawda”. Plik „images/users/user:12345/profilePhoto.png” jest natomiast odczytywany tylko wtedy, gdy other_condition zwraca wartość „prawda”.

Cloud Storage Security Rules nie są stosowane kaskadowo, a reguły są oceniane tylko wtedy, gdy ścieżka żądania pasuje do ścieżki ze zdefiniowanymi regułami.

Wersja 1

Firebase Security Rules domyślnie używa wersji 1. W wersji 1 rekurencyjne symbole wieloznaczne dopasowują co najmniej 1 element nazwy pliku, a nie 0 lub więcej elementów. W związku z tym: match /images/{filenamePrefixWildcard}/{imageFilename=**} pasuje do nazwy pliku np. /images/profilePics/profile.png, ale nie /images/badge.png. Użyj /images/{imagePrefixorFilename=**}.

Rekurencyjne symbole wieloznaczne muszą znajdować się na końcu oświadczenia o dopasowaniu.

Zalecamy korzystanie z wersji 2 ze względu na jej bardziej zaawansowane funkcje.

Wersja 2

W wersji 2 systemu Firebase Security Rules rekurencyjne symbole wieloznaczne pasują do 0 lub większej liczby ścieżek elementy(ów). Tyle wyników pasuje do: /images/{filenamePrefixWildcard}/{imageFilename=**} nazwy plików /images/profilePics/profile.png i /images/badge.png.

Musisz wyrazić zgodę na wersję 2, dodając rules_version = '2'; na początku swoich reguł zabezpieczeń:

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

W każdym elemencie dopasowania może występować maksymalnie 1 rekursywny symbol wieloznaczny, ale w wersji 2 możesz umieścić go w dowolnym miejscu elementu dopasowania. Przykład:

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

Operacje szczegółowe

W niektórych sytuacjach warto podzielić operacje read i write na bardziej szczegółowe operacje. Aplikacja może na przykład wymuszać w aplikacji różne warunki tworzenia pliku niż przy jego usunięciu.

Operacja read można podzielić na get i list.

Uwaga: operacje list Rules, a więc interfejs API listy Cloud Storage, są dostępne tylko w projektach, które korzystają z wersji Rules 2.

Regułę write można podzielić na create, update i delete:

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

Nakładające się instrukcje dopasowania

Może się zdarzyć, że nazwa pliku będzie pasowała do więcej niż jednej instrukcji match. W jeśli do żądania pasuje wiele wyrażeń allow, dostęp jest dozwolony jeśli którykolwiek z warunków jest true:

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

W podanym przykładzie wszystkie operacje odczytu i zapisu dotyczące plików, których nazwa zaczyna się od /images/, są dozwolone, ponieważ druga reguła jest zawsze true, nawet gdy pierwsza reguła jest false.

Reguły nie są filtrami

Gdy zabezpieczysz dane i zaczniesz wykonywać operacje na plikach, pamiętaj o tych kwestiach: że reguły zabezpieczeń nie są filtrami. Nie można wykonać operacji na zbiorze pliki pasujące do wzorca nazwy pliku i oczekują, że program Cloud Storage będzie miał dostęp tylko które pliki są dostępne dla bieżącego klienta.

Na przykład taka reguła zabezpieczeń:

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

Odmowa: ta reguła odrzuca tę prośbę, ponieważ zbiór wyników może zawierać pliki, w których contentType nie jest image/png:

Sieć

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

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

Reguły w Cloud Storage Security Rules sprawdzają każde zapytanie pod kątem potencjalnego wyniku i odrzucają żądanie, jeśli może ono zwrócić plik, do którego klient nie ma uprawnień do odczytu. Prośby o dostęp muszą być zgodne z ograniczeniami ustawionymi przez swoje reguły.

Dalsze kroki

Możesz poszerzyć swoją wiedzę na temat Firebase Security Rules w Cloud Storage:

• Poznaj kolejną ważną koncepcję języka reguł, dynamiczne warunki, które umożliwiają regułom sprawdzanie autoryzacji użytkownika, porównywanie istniejących i przychodzących danych oraz ich weryfikowanie.

• Zapoznaj się z typowymi przypadkami użycia zabezpieczeń oraz Firebase Security Rules definicji dotyczących tych kwestii.

Możesz zapoznać się z Firebase Security Rules przypadkami użycia charakterystycznymi dla platformy Cloud Storage: