Korzystanie z warunków w regułach zabezpieczeń Cloud Storage Firebase

Ten przewodnik rozszerza informacje z artykułu poznaj podstawową składnię języka Firebase Security Rules i pokazuje, jak dodać warunki do kodu Firebase Security Rules na potrzeby Cloud Storage.

Podstawowym elementem składowym Cloud Storage Security Rules jest warunek. Warunek to wyrażenie logiczne, które określa, czy dana operacja powinna być dozwolona czy zabroniona. W przypadku podstawowych reguł używanie literałów true i false jako warunków sprawdza się doskonale. Jednak Firebase Security Rules w przypadku Cloud Storage języka umożliwia pisanie bardziej złożonych warunków, które mogą:

• Sprawdzanie uwierzytelniania użytkownika
• Weryfikowanie danych przychodzących

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.

Uwierzytelnianie

Firebase Security Rules w przypadku Cloud Storage integruje się z Firebase Authentication, aby zapewnić Cloud Storage zaawansowane uwierzytelnianie oparte na użytkownikach. Umożliwia to szczegółową kontrolę dostępu na podstawie roszczeń tokena Firebase Authentication.

Gdy uwierzytelniony użytkownik wyśle żądanie do Cloud Storage, zmienna request.auth zostanie wypełniona uid użytkownika (request.auth.uid) oraz deklaracjami tokena JWT Firebase Authentication (request.auth.token).

Dodatkowo w przypadku korzystania z uwierzytelniania niestandardowego w polu request.auth.token pojawiają się dodatkowe roszczenia.

Gdy nieuwierzytelniony użytkownik wysyła żądanie, zmienna request.auth ma wartość null.

Na podstawie tych danych można zabezpieczyć pliki na kilka sposobów przy użyciu uwierzytelniania:

• Publiczne: ignoruj request.auth
• Uwierzytelnione prywatne: sprawdź, czy request.auth nie jest null.
• Prywatne dane użytkownika: sprawdź, czy request.auth.uid jest równe ścieżce uid
• Grupa prywatna: sprawdź roszczenia tokena niestandardowego, aby dopasować je do wybranego roszczenia, lub odczytaj metadane pliku, aby sprawdzić, czy istnieje pole metadanych.

Publiczny

Każda reguła, która nie uwzględnia request.authkontekstu, może być uznana za regułę public, ponieważ nie uwzględnia kontekstu uwierzytelniania użytkownika. Te reguły mogą być przydatne do udostępniania danych publicznych, takich jak zasoby gier, pliki dźwiękowe lub inne treści statyczne.

// 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");
}

Uwierzytelniony prywatny

W niektórych przypadkach możesz chcieć, aby dane były widoczne dla wszystkich uwierzytelnionych użytkowników aplikacji, ale nie dla użytkowników nieuwierzytelnionych. Ponieważ zmienna request.auth ma wartość null w przypadku wszystkich nieuwierzytelnionych użytkowników, wystarczy sprawdzić, czy zmienna request.auth istnieje, aby wymagać uwierzytelniania:

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

Użytkownicy w trybie prywatnym

Zdecydowanie najczęstszym zastosowaniem request.auth będzie przyznawanie poszczególnym użytkownikom szczegółowych uprawnień do plików: od przesyłania zdjęć profilowych po odczytywanie prywatnych dokumentów.

Ponieważ pliki w Cloud Storage mają pełną „ścieżkę” do pliku, aby plik był kontrolowany przez użytkownika, wystarczy umieścić w prefiksie nazwy pliku unikalne informacje identyfikujące użytkownika (np. uid użytkownika), które można sprawdzić podczas oceny reguły:

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

Grupa prywatna

Innym równie częstym przypadkiem użycia jest zezwolenie na uprawnienia grupy do obiektu, np. zezwolenie kilku członkom zespołu na współpracę nad udostępnionym dokumentem. Możesz to zrobić na kilka sposobów:

• wygenerować Firebase Authentication token niestandardowy zawierający dodatkowe informacje o członku grupy (np. identyfikator grupy);
• Do metadanych pliku dołącz informacje o grupie (np. identyfikator grupy lub listę autoryzowanych uid).

Gdy te dane zostaną zapisane w metadanych tokena lub pliku, można się do nich odwoływać w regule:

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

Poproś o ocenę

Przesyłanie, pobieranie, zmiany metadanych i usuwanie są oceniane na podstawie request wysyłanych do Cloud Storage. Oprócz unikalnego identyfikatora użytkownika i Firebase Authentication ładunku w obiekcie request.auth, jak opisano powyżej, zmienna request zawiera ścieżkę do pliku, w którym jest wykonywane żądanie, czas otrzymania żądania i nową wartość resource, jeśli żądanie jest żądaniem zapisu.

Obiekt request zawiera też unikalny identyfikator użytkownika i ładunek Firebase Authentication w obiekcie request.auth, co zostanie dokładniej wyjaśnione w sekcji Bezpieczeństwo oparte na użytkownikach w dokumentacji.

Pełną listę właściwości obiektu request znajdziesz poniżej:

Ocena zasobów

Podczas oceny reguł możesz też oceniać metadane pliku przesyłanego, pobieranego, modyfikowanego lub usuwanego. Umożliwia to tworzenie złożonych i zaawansowanych reguł, które pozwalają na przykład zezwalać na przesyłanie tylko plików o określonych typach treści lub usuwać tylko pliki o określonym rozmiarze.

Firebase Security Rules dla Cloud Storage udostępnia metadane pliku w resourceobiekcie, który zawiera pary klucz/wartość metadanych wyświetlanych w obiekcie Cloud Storage. Te właściwości można sprawdzić w żądaniach read lub write, aby zapewnić integralność danych.

W przypadku żądań write (takich jak przesyłanie, aktualizowanie metadanych i usuwanie) oprócz obiektu resource, który zawiera metadane pliku znajdującego się obecnie w ścieżce żądania, możesz też używać obiektu request.resource, który zawiera podzbiór metadanych pliku, które mają zostać zapisane, jeśli zapis jest dozwolony. Możesz użyć tych 2 wartości, aby zapewnić integralność danych lub wymusić ograniczenia aplikacji, takie jak typ lub rozmiar pliku.

Pełną listę właściwości obiektu resource znajdziesz poniżej:

request.resource zawiera wszystkie te elementy z wyjątkiem generation, metageneration, etag, timeCreated i updated.

Ulepsz za pomocą Cloud Firestore

Możesz uzyskać dostęp do dokumentów w Cloud Firestore, aby ocenić inne kryteria autoryzacji.

Za pomocą funkcji firestore.get() i firestore.exists() reguły bezpieczeństwa mogą oceniać przychodzące żądania na podstawie dokumentów w Cloud Firestore. Funkcje firestore.get() i firestore.exists() wymagają w pełni określonych ścieżek do dokumentów. Gdy używasz zmiennych do tworzenia ścieżek dla tagów firestore.get() i firestore.exists(), musisz jawnie wskazać zmianę znaczenia zmiennych za pomocą składni $(variable).

W przykładzie poniżej widzimy regułę, która ogranicza dostęp do plików do odczytu do użytkowników należących do określonych klubów.

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

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

Gdy utworzysz i zapiszesz pierwszy Cloud Storage Security Rules, który korzysta z tych Cloud Firestorefunkcji, w Firebase konsoli lub Firebase interfejsie CLI pojawi się prośba o włączenie uprawnień do połączenia tych 2 usług.

Możesz wyłączyć tę funkcję, usuwając rolę uprawnień zgodnie z instrukcjami w sekcji Zarządzanie i wdrażanieFirebase Security Rules.

Zweryfikuj dane

Firebase Security Rules w przypadku Cloud Storage można też używać do weryfikacji danych, w tym do sprawdzania nazwy i ścieżki pliku oraz właściwości metadanych pliku, takich jak contentType i 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/.*');
    }
  }
}

Funkcje niestandardowe

W miarę jak Firebase Security Rules stają się bardziej złożone, możesz umieszczać zestawy warunków w funkcjach, których możesz używać ponownie w całym zestawie reguł. Reguły zabezpieczeń obsługują funkcje niestandardowe. Składnia funkcji niestandardowych jest podobna do składni JavaScriptu, ale funkcje Firebase Security Rules są pisane w języku specyficznym dla domeny, który ma pewne istotne ograniczenia:

• Funkcje mogą zawierać tylko 1 instrukcję return. Nie mogą one zawierać żadnej dodatkowej logiki. Nie mogą na przykład wykonywać pętli ani wywoływać usług zewnętrznych.
• Funkcje mogą automatycznie uzyskiwać dostęp do funkcji i zmiennych z zakresu, w którym są zdefiniowane. Na przykład funkcja zdefiniowana w zakresie service firebase.storage ma dostęp do zmiennej resource, a w przypadku Cloud Firestore tylko do wbudowanych funkcji, takich jak get() i exists().
• Funkcje mogą wywoływać inne funkcje, ale nie mogą być rekurencyjne. Łączna głębokość stosu wywołań jest ograniczona do 10.
• W wersji rules2 funkcje mogą definiować zmienne za pomocą słowa kluczowego let. Funkcje mogą mieć dowolną liczbę powiązań let, ale muszą kończyć się instrukcją return.

Funkcja jest definiowana za pomocą słowa kluczowego function i może przyjmować zero lub więcej argumentów. Możesz na przykład połączyć 2 rodzaje warunków użytych w przykładach powyżej w jedną funkcję:

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

Używanie funkcji w Firebase Security Rules sprawia, że są one łatwiejsze w utrzymaniu, gdy złożoność reguł rośnie.

Dalsze kroki

Po omówieniu warunków masz już bardziej zaawansowaną wiedzę o regułach i możesz:

Dowiedz się, jak obsługiwać podstawowe przypadki użycia, oraz poznaj przepływ pracy związany z opracowywaniem, testowaniem i wdrażaniem reguł:

• Twórz reguły, które uwzględniają typowe scenariusze.
• Poszerz swoją wiedzę, zapoznając się z sytuacjami, w których musisz wykrywać i unikać niezabezpieczonych reguł.
• Testuj reguły za pomocą Cloud Storage emulatora i specjalnej biblioteki testowej reguł zabezpieczeń.
• Sprawdź metody dostępne w przypadku wdrażania Security Rules.