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

Firebase Security Rules dla Cloud Storage umożliwiają kontrolowanie dostępu do obiektów przechowywanych w zasobnikach Cloud Storage. Elastyczna składnia reguł umożliwia tworzenie reguł do kontrolowania dowolnych operacji – od wszystkich zapisów w zasobniku Cloud Storage po operacje na konkretnym pliku.

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Cloud Storage data.

Ten przewodnik opisuje podstawową składnię i strukturę Cloud Storage Security Rules, które pozwalają tworzyć kompletne zestawy reguł.

Deklaracja usługi i bazy danych

Pliki Firebase Security Rules dla Cloud Storage zawsze zaczynają się od tej deklaracji:

service firebase.storage {
    // ...
}

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

Podstawowe reguły odczytu i zapisu

Reguły podstawowe składają się z instrukcji match identyfikującej zasobniki Cloud Storage, instrukcji dopasowania określającej nazwę pliku oraz wyrażenia allow, które szczegółowo określa, kiedy dozwolony jest odczyt określonych danych. Wyrażenia allow określają metody dostępu (np. odczyt, zapis) oraz warunki, na jakich dostęp jest dozwolony lub zabroniony.

W domyślnym zestawie reguł pierwsza instrukcja match używa wyrażenia wieloznacznego {bucket}, aby wskazać, że reguły mają zastosowanie do wszystkich zasobników w projekcie. Więcej informacji o dopasowaniach wieloznacznych znajdziesz 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. Instrukcja dopasowania może wskazywać konkretny plik, jak w match /images/profilePhoto.png.

Dopasowywanie symboli wieloznacznych

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

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

Do zmiennej wieloznacznej można odwoływać się z poziomu match, aby autoryzować nazwę lub ścieżkę pliku:

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

Dane hierarchiczne

Jak wspomnieliśmy, w zasobniku Cloud Storage nie ma struktury hierarchicznej. Jednak stosując konwencję nazewnictwa plików, często zawierającą ukośniki w nazwach plików, możemy naśladować strukturę, która wygląda jak zagnieżdżona seria katalogów i podkatalogów. Ważne jest, aby zrozumieć, jak Firebase Security Rules współdziała z tymi nazwami plików.

Rozważmy sytuację, w której mamy zestaw plików o nazwach zaczynających się od rdzenia /images/. Firebase Security Rules dotyczy tylko dopasowanej nazwy pliku, więc ustawienia kontroli dostępu zdefiniowane w rdzeniu /images/ nie mają zastosowania do rdzenia /mp3s/. Zamiast tego napisz 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>;
    }
  }
}

W przypadku zagnieżdżania instrukcji match ścieżka wewnętrznej instrukcji match jest zawsze dołączana do ścieżki zewnętrznej instrukcji match. Te 2 zestawy reguł są więc 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żna zadeklarować symbol wieloznaczny dla wielu segmentów, aby uzyskać bardziej złożone dopasowanie, dodając =** do nazwy symbolu wieloznacznego, 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 kilka reguł, wynik jest OR wyników wszystkich ocen reguł. Oznacza to, że jeśli dowolna reguła, do której pasuje plik, zwraca wartość true, wynik to true.

W powyższych regułach plik „images/profilePhoto.png” można odczytać, jeśli reguła condition lub other_condition ma wartość „true”, natomiast plik „images/users/user:12345/profilePhoto.png” podlega tylko wynikowi reguły other_condition.

Reguły Cloud Storage Security Rules nie są stosowane kaskadowo i są oceniane tylko wtedy, gdy ścieżka żądania pasuje do ścieżki z określonymi regułami.

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

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. Na przykład aplikacja może wymagać innych warunków tworzenia plików niż ich usuwania.

Operację read można podzielić na get i list.

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 (Security 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

Nazwa pliku może pasować do więcej niż 1 instrukcji match. Jeśli do żądania pasuje kilka wyrażeń allow, dostęp jest dozwolony, gdy dowolny z warunków ma wartość 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 przykładzie powyżej wszystkie odczyty i zapisy plików, których nazwa zaczyna się od /images/, są dozwolone, ponieważ druga reguła zawsze ma wartość true, nawet gdy pierwsza reguła ma wartość false.

Reguły to nie filtry

Gdy zabezpieczysz dane i zaczniesz wykonywać operacje na plikach, pamiętaj, że reguły zabezpieczeń nie są filtrami. Nie możesz wykonywać operacji na zbiorze plików pasujących do wzorca nazwy pliku i oczekiwać, że Cloud Storage będzie mieć dostęp tylko do plików, do których bieżący klient ma uprawnienia dostępu.

Weźmy na przykład tę regułę 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';
    }
  }
}

Odrzucono: ta reguła odrzuca następujące żądanie, ponieważ zbiór wyników może zawierać pliki, w których contentType nie jest image/png:

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

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

Reguły w Cloud Storage Security Rules oceniają 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 określonymi w Twoich regułach.

Dalsze kroki

Możesz pogłębić swoją wiedzę na temat Firebase Security Rules w przypadku Cloud Storage:

• Poznaj kolejne ważne pojęcie języka reguł, czyli dynamiczne warunki, które umożliwiają regułom sprawdzanie autoryzacji użytkownika, porównywanie istniejących i przychodzących danych, weryfikowanie przychodzących danych i nie tylko.

• Zapoznaj się z typowymi przypadkami użycia zabezpieczeń i definicjami Firebase Security Rules, które ich dotyczą.

Możesz zapoznać się z Firebase Security Rules przypadkami użycia dotyczącymi Cloud Storage: