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

Ten przewodnik stanowi uzupełnienie przewodnika Podstawowa składnia języka Firebase Security Rules i pokazuje, jak dodawać warunki do Firebase Security Rules w 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 odrzucona. W przypadku podstawowych reguł używanie literałów true i false jako warunków działa doskonale. Jednak język Firebase Security Rules dla Cloud Storage umożliwia pisanie bardziej złożonych warunków, które mogą:

• Sprawdzanie uwierzytelniania użytkowników
• Weryfikacja 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

Usługa Firebase Security Rules dla Cloud Storage integruje się z Firebase Authentication, aby zapewnić skuteczne uwierzytelnianie użytkowników w Cloud Storage. Umożliwia to szczegółową kontrolę dostępu na podstawie deklaracji tokena Firebase Authentication.

Gdy uwierzytelniony użytkownik wysyła żądanie do Cloud Storage, zmienna request.auth jest wypełniana wartością uid użytkownika (request.auth.uid) oraz deklaracjami tokena JWT Firebase Authentication (request.auth.token).

Dodatkowo, gdy używasz uwierzytelniania niestandardowego, w polu request.auth.token pojawiają się dodatkowe oświadczenia.

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

Korzystając z tych danych, możesz zabezpieczyć pliki za pomocą uwierzytelniania na kilka typowych sposobów:

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

Publiczny

Każdą regułę, która nie uwzględnia kontekstu request.auth, można uznać za regułę public, ponieważ nie uwzględnia ona kontekstu uwierzytelniania użytkownika. Te reguły mogą być przydatne do udostępniania danych publicznych, takich jak zasoby gry, 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 nieuwierzytelnionych. Zmienna request.auth ma wartość null dla wszystkich nieuwierzytelnionych użytkowników, więc aby wymagać uwierzytelniania, wystarczy sprawdzić, czy zmienna request.auth istnieje:

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

Użytkownik w trybie prywatnym

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

Pliki w Cloud Storage mają pełną „ścieżkę”, więc aby plik był kontrolowany przez użytkownika, wystarczy, że w prefiksie nazwy pliku znajdzie się unikalna informacja umożliwiająca identyfikację użytkownika (np. uid), którą 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 zezwalanie na uprawnienia grupowe do obiektu, na przykład umożliwienie kilku członkom zespołu współpracy nad udostępnionym dokumentem. Można to zrobić na kilka sposobów:

• wygenerować Firebase Authentication token niestandardowy, który zawiera dodatkowe informacje o członku grupy (np. identyfikator grupy);
• Uwzględnij informacje o grupie (takie jak identyfikator grupy lub lista uprawnionych uid) w metadanych pliku.

Gdy te dane zostaną zapisane w tokenie lub metadanych 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 za pomocą request wysyłanego do Cloud Storage. Oprócz unikalnego identyfikatora użytkownika i ładunku Firebase Authentication w obiekcie request.auth, jak opisano powyżej, zmienna request zawiera ścieżkę pliku, w której jest wykonywane żądanie, czas odebrania żądania i nową wartość resource, jeśli żądanie jest operacją zapisu.

Obiekt request zawiera też unikalny identyfikator użytkownika i ładunek Firebase Authentication w obiekcie request.auth, który zostanie szczegółowo opisany w sekcji Zabezpieczenia oparte na użytkownikach w dokumentacji.

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

Ocena zasobów

Podczas oceniania reguł możesz też ocenić metadane pliku, który jest przesyłany, pobierany, modyfikowany lub usuwany. Dzięki temu możesz tworzyć złożone i zaawansowane reguły, które pozwalają na przykład na przesyłanie tylko plików o określonych typach treści lub usuwanie tylko plików o określonym rozmiarze.

Firebase Security Rules dla Cloud Storage udostępnia metadane pliku w obiekcie resource, 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 obecnie istniejącego w ścieżce żądania, możesz też użyć obiektu request.resource, który zawiera podzbiór metadanych pliku do zapisania, 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.

Dzięki funkcjom firestore.get() i firestore.exists() reguły zabezpieczeń mogą oceniać przychodzące żądania pod kątem dokumentów w Cloud Firestore. Funkcje firestore.get() i firestore.exists() oczekują pełnych ścieżek dokumentów. Jeśli używasz zmiennych do tworzenia ścieżek dla firestore.get() i firestore.exists(), musisz wyraźnie zmienić znaczenie zmiennych za pomocą składni $(variable).

W przykładzie poniżej widzimy regułę, która ogranicza dostęp do odczytu plików do użytkowników, którzy są członkami 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 pierwszą funkcję Cloud Storage Security Rules, która korzysta z tych funkcji Cloud Firestore, w konsoli Firebase lub interfejsie wiersza poleceń Firebase pojawi się prośba o włączenie uprawnień do połączenia obu usług.

Możesz wyłączyć tę funkcję, usuwając rolę uprawnień, zgodnie z opisem w artykule Zarządzanie i wdrażanie Firebase Security Rules.

Zweryfikuj dane

Firebase Security Rules dla Cloud Storage można też używać do sprawdzania poprawności danych, w tym nazwy i ścieżki pliku, a także 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 chcieć opakować zestawy warunków w funkcje, których możesz używać w całym zestawie reguł. Reguły zabezpieczeń obsługują funkcje niestandardowe. Składnia funkcji niestandardowych przypomina nieco JavaScript, ale funkcje Firebase Security Rules są pisane w języku dziedzinowym, który ma pewne istotne ograniczenia:

• Funkcje mogą zawierać tylko jedną instrukcję return. Nie mogą 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ą powrotu.

Funkcja jest definiowana za pomocą słowa kluczowego function i przyjmuje co najmniej 0 argumentów. Możesz na przykład połączyć 2 typy warunków użytych w powyższych przykładach 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 ułatwia ich utrzymanie w miarę wzrostu złożoności reguł.

Dalsze kroki

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

Dowiedz się, jak obsługiwać podstawowe przypadki użycia oraz jak wygląda proces tworzenia, testowania i wdrażania reguł:

• Twórz reguły, które dotyczą typowych scenariuszy.
• Poszerz swoją wiedzę, analizując sytuacje, w których musisz rozpoznać i unikać niebezpiecznych reguł.
• Przetestuj reguły za pomocą emulatora Cloud Storage i dedykowanej biblioteki testowej reguł zabezpieczeń.
• Sprawdź dostępne metody wdrażania Security Rules.