Firebase zapewnia kilka narzędzi do zarządzania regułami, z których każde jest przydatne w określonych przypadkach i każde korzysta z tego samego interfejsu API zarządzania regułami zabezpieczeń Firebase.
Bez względu na to, które narzędzie jest używane do jego wywołania, interfejs API zarządzania:
- Pozyskuje źródło reguł : zestaw reguł, zazwyczaj plik kodu zawierający instrukcje reguł bezpieczeństwa Firebase.
- Przechowuje przetworzone źródło jako niezmienny zestaw reguł .
- Śledzi wdrażanie każdego zestawu reguł w wydaniu . Usługi obsługujące reguły bezpieczeństwa Firebase wyszukują wydanie projektu, aby ocenić każde żądanie dotyczące zabezpieczonego zasobu.
- Zapewnia możliwość uruchamiania testów składniowych i semantycznych zestawu reguł.
Użyj interfejsu wiersza polecenia Firebase
Za pomocą Firebase CLI możesz przesyłać lokalne źródła i wdrażać wersje . Pakiet Firebase Local Emulator Suite interfejsu CLI umożliwia przeprowadzanie pełnego lokalnego testowania źródeł .
Korzystanie z interfejsu wiersza polecenia umożliwia kontrolowanie wersji reguł za pomocą kodu aplikacji i wdrażanie reguł w ramach istniejącego procesu wdrażania.
Wygeneruj plik konfiguracyjny
Podczas konfigurowania projektu Firebase za pomocą Firebase CLI tworzysz plik konfiguracyjny .rules w katalogu projektu. Użyj następującego polecenia, aby rozpocząć konfigurowanie projektu Firebase:
Cloud Firestore
// Set up Firestore in your project directory, creates a .rules file firebase init firestore
Baza danych czasu rzeczywistego
// Set up Realtime Database in your project directory, creates a .rules file firebase init database
Magazyn w chmurze
// Set up Storage in your project directory, creates a .rules file firebase init storage
Edytuj i aktualizuj swoje reguły
Edytuj źródło reguł bezpośrednio w pliku konfiguracyjnym .rules .
Upewnij się, że wszelkie zmiany wprowadzone w interfejsie CLI Firebase są odzwierciedlane w konsoli Firebase lub że konsekwentnie wprowadzasz aktualizacje za pomocą konsoli Firebase lub interfejsu wiersza polecenia Firebase. W przeciwnym razie możesz nadpisać wszelkie aktualizacje wprowadzone w konsoli Firebase.
Przetestuj swoje aktualizacje
Pakiet Local Emulator Suite zapewnia emulatory dla wszystkich produktów obsługujących reguły bezpieczeństwa. Mechanizm reguł bezpieczeństwa dla każdego emulatora przeprowadza zarówno składniową, jak i semantyczną ocenę reguł, wykraczając tym samym poza testy składniowe oferowane przez interfejs API zarządzania regułami bezpieczeństwa.
Jeśli pracujesz z interfejsem CLI, pakiet jest doskonałym narzędziem do testowania reguł bezpieczeństwa Firebase. Użyj pakietu Local Emulator Suite , aby przetestować aktualizacje lokalnie i potwierdzić, że reguły Twojej aplikacji zachowują się zgodnie z oczekiwaniami.
Wdróż swoje aktualizacje
Po zaktualizowaniu i przetestowaniu reguł wdróż źródła w środowisku produkcyjnym.
W przypadku Reguł bezpieczeństwa Cloud Firestore powiąż pliki .rules z domyślną i dodatkowymi nazwanymi bazami danych, przeglądając i aktualizując plik firebase.json .
Użyj poniższych poleceń, aby selektywnie wdrożyć własne reguły lub wdrożyć je w ramach normalnego procesu wdrażania.
Cloud Firestore
// Deploy rules for all databases configured in your firebase.json firebase deploy --only firestore:rules
// Deploy rules for the specified database configured in your firebase.json firebase deploy --only firestore:<databaseId>
Baza danych czasu rzeczywistego
// Deploy your .rules file firebase deploy --only database
Magazyn w chmurze
// Deploy your .rules file firebase deploy --only storage
Użyj konsoli Firebase
Możesz także edytować źródła reguł i wdrażać je jako wersje z konsoli Firebase. Testy składni są przeprowadzane podczas edytowania w interfejsie konsoli Firebase, a testy semantyczne są dostępne za pomocą Placu zabaw dla reguł.
Edytuj i aktualizuj swoje reguły
- Otwórz konsolę Firebase i wybierz swój projekt.
- Następnie wybierz opcję Baza danych czasu rzeczywistego , Cloud Firestore lub Pamięć masowa z nawigacji produktu, a następnie kliknij Reguły , aby przejść do edytora reguł.
- Edytuj swoje reguły bezpośrednio w edytorze.
Przetestuj swoje aktualizacje
Oprócz testowania składni w interfejsie edytora możesz testować semantyczne zachowanie Reguł, korzystając z bazy danych i zasobów pamięci projektu, bezpośrednio w konsoli Firebase, korzystając z Placu zabaw reguł . Otwórz ekran Rules Playground w edytorze reguł, zmodyfikuj ustawienia i kliknij Uruchom . Poszukaj komunikatu potwierdzającego u góry edytora.
Wdróż swoje aktualizacje
Gdy upewnisz się, że aktualizacje są zgodne z oczekiwaniami, kliknij Publikuj .
Użyj pakietu Admin SDK
Możesz użyć pakietu Admin SDK dla zestawów reguł Node.js . Dzięki temu zautomatyzowanemu dostępowi możesz:
- Implementuj niestandardowe narzędzia, skrypty, pulpity nawigacyjne i potoki CI/CD do zarządzania regułami.
- Łatwiej zarządzaj regułami w wielu projektach Firebase.
Podczas programowego aktualizowania reguł bardzo ważne jest unikanie wprowadzania niezamierzonych zmian w kontroli dostępu do aplikacji. Napisz swój kod Admin SDK z myślą o bezpieczeństwie, zwłaszcza podczas aktualizowania lub wdrażania reguł.
Inną ważną rzeczą, o której należy pamiętać, jest to, że pełne rozpowszechnienie wersji Reguł bezpieczeństwa Firebase zajmuje kilka minut. Używając pakietu Admin SDK do wdrażania reguł, unikaj warunków wyścigu, w których aplikacja natychmiast polega na regułach, których wdrożenie nie zostało jeszcze zakończone. Jeśli Twój przypadek użycia wymaga częstych aktualizacji reguł kontroli dostępu, rozważ rozwiązania wykorzystujące Cloud Firestore, które mają na celu ograniczenie wyścigów pomimo częstych aktualizacji.
Należy również zwrócić uwagę na te ograniczenia:
- Reguły muszą być mniejsze niż 256 KiB tekstu zakodowanego w UTF-8 po serializacji.
- Projekt może mieć maksymalnie 2500 wdrożonych zestawów reguł. Po osiągnięciu tego limitu należy usunąć niektóre stare zestawy reguł przed utworzeniem nowych.
Twórz i wdrażaj zestawy reguł Cloud Storage lub Cloud Firestore
Typowy przepływ pracy związany z zarządzaniem regułami bezpieczeństwa za pomocą pakietu Admin SDK może obejmować trzy oddzielne kroki:
- Utwórz źródło pliku reguł (opcjonalnie)
- Utwórz zestaw reguł
- Zwolnij lub wdróż nowy zestaw reguł
Pakiet SDK zapewnia metodę łączenia tych kroków w jedno wywołanie interfejsu API dla reguł bezpieczeństwa Cloud Storage i Cloud Firestore. Na przykład:
const source = `service cloud.firestore {
match /databases/{database}/documents {
match /carts/{cartID} {
allow create: if request.auth != null && request.auth.uid == request.resource.data.ownerUID;
allow read, update, delete: if request.auth != null && request.auth.uid == resource.data.ownerUID;
}
}
}`;
// Alternatively, load rules from a file
// const fs = require('fs');
// const source = fs.readFileSync('path/to/firestore.rules', 'utf8');
await admin.securityRules().releaseFirestoreRulesetFromSource(source);
Ten sam wzorzec działa w przypadku reguł Cloud Storage z releaseFirestoreRulesetFromSource() .
Alternatywnie możesz utworzyć plik reguł jako obiekt w pamięci, utworzyć zestaw reguł i osobno wdrożyć zestaw reguł, aby uzyskać dokładniejszą kontrolę nad tymi zdarzeniami. Na przykład:
const rf = admin.securityRules().createRulesFileFromSource('firestore.rules', source);
const rs = await admin.securityRules().createRuleset(rf);
await admin.securityRules().releaseFirestoreRuleset(rs);
Zaktualizuj zestawy reguł bazy danych czasu rzeczywistego
Aby zaktualizować zestawy reguł bazy danych czasu rzeczywistego za pomocą pakietu Admin SDK, użyj metod getRules() i setRules() z admin.database . Możesz pobrać zestawy reguł w formacie JSON lub jako ciąg z dołączonymi komentarzami.
Aby zaktualizować zestaw reguł:
const source = `{
"rules": {
"scores": {
".indexOn": "score",
"$uid": {
".read": "$uid == auth.uid",
".write": "$uid == auth.uid"
}
}
}
}`;
await admin.database().setRules(source);
Zarządzaj zestawami reguł
Aby ułatwić zarządzanie dużymi zestawami reguł, pakiet Admin SDK umożliwia wyświetlanie listy wszystkich istniejących reguł za pomocą admin.securityRules().listRulesetMetadata . Na przykład:
const allRulesets = [];
let pageToken = null;
while (true) {
const result = await admin.securityRules().listRulesetMetadata(pageToken: pageToken);
allRulesets.push(...result.rulesets);
pageToken = result.nextPageToken;
if (!pageToken) {
break;
}
}
W przypadku bardzo dużych wdrożeń, które z upływem czasu osiągają limit 2500 zestawów reguł, można utworzyć logikę, aby usunąć najstarsze reguły w ustalonym cyklu czasowym. Na przykład, aby usunąć wszystkie zestawy reguł wdrożone na dłużej niż 30 dni:
const thirtyDays = new Date(Date.now() - THIRTY_DAYS_IN_MILLIS);
const promises = [];
allRulesets.forEach((rs) => {
if (new Date(rs.createTime) < thirtyDays) {
promises.push(admin.securityRules().deleteRuleset(rs.name));
}
});
await Promise.all(promises);
console.log(`Deleted ${promises.length} rulesets.`);
Użyj interfejsu API REST
Opisane powyżej narzędzia dobrze nadają się do różnych przepływów pracy, w tym do zarządzania regułami bezpieczeństwa Firebase dla wielu baz danych Cloud Firestore w Twoim projekcie, ale możesz chcieć zarządzać regułami bezpieczeństwa Firebase i wdrażać je za pomocą samego interfejsu API zarządzania. Interfejs API zarządzania zapewnia największą elastyczność.
Należy również zwrócić uwagę na te ograniczenia:
- Reguły muszą być mniejsze niż 256 KiB tekstu zakodowanego w UTF-8 po serializacji.
- Projekt może mieć maksymalnie 2500 wdrożonych zestawów reguł. Po osiągnięciu tego limitu należy usunąć niektóre stare zestawy reguł przed utworzeniem nowych.
Twórz i wdrażaj zestawy reguł Cloud Firestore lub Cloud Storage za pomocą REST
Przykłady w tej sekcji wykorzystują Reguły Firestore, ale mają również zastosowanie do Reguł Cloud Storage.
Przykłady używają również cURL do wykonywania wywołań API. Kroki konfigurowania i przekazywania tokenów uwierzytelniania są pomijane. Możesz eksperymentować z tym interfejsem API za pomocą Eksploratora interfejsu API zintegrowanego z dokumentacją referencyjną.
Typowe kroki tworzenia i wdrażania zestawu reguł za pomocą interfejsu API zarządzania to:
- Utwórz źródła plików reguł
- Utwórz zestaw reguł
- Zwolnij (wdróż) nowy zestaw reguł.
Utwórz źródło
Załóżmy, że pracujesz nad projektem secure_commerce Firebase i chcesz wdrożyć zablokowane reguły Cloud Firestore w bazie danych w swoim projekcie o nazwie east_store .
Możesz zaimplementować te reguły w pliku firestore.rules .
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if false;
}
}
}
Utwórz zestaw reguł
Teraz wygeneruj odcisk palca zakodowany w base64 dla tego pliku. Następnie można użyć źródła w tym pliku do wypełnienia ładunku potrzebnego do utworzenia zestawu reguł za pomocą wywołania REST projects.rulesets.create . Tutaj użyj polecenia cat , aby wstawić zawartość firestore.rules do ładunku REST.
Aby śledzić, aby powiązać to z bazą danych east_store , ustaw attachment_point na east_store .
curl -X POST -d '{
"source": {
{
"files": [
{
"content": "' $(cat storage.rules) '",
"name": "firestore.rules",
"fingerprint": <sha fingerprint>
},
"attachment_point": "firestore.googleapis.com/databases/east_store"
]
}
}
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets'
Interfejs API zwraca odpowiedź weryfikacyjną i nazwę zestawu reguł, na przykład projects/secure_commerce/rulesets/uuid123 .
Zwolnij (wdróż) zestaw reguł
Jeśli zestaw reguł jest prawidłowy, ostatnim krokiem jest wdrożenie nowego zestawu reguł w nazwanej wersji.
curl -X POST -d '{
"name": "projects/secure_commerce/releases/cloud.firestore.east_store" ,
"rulesetName": "projects/secure_commerce/rulesets/uuid123"
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/releases'
Pamiętaj, że pełne rozpowszechnienie wersji Reguł bezpieczeństwa Firebase zajmuje kilka minut. Podczas wdrażania interfejsu API REST zarządzania należy unikać sytuacji wyścigu, w których aplikacja natychmiast polega na regułach, których wdrożenie nie zostało jeszcze zakończone.
Zaktualizuj zestawy reguł bazy danych czasu rzeczywistego za pomocą REST
Baza danych czasu rzeczywistego zapewnia własny interfejs REST do zarządzania regułami. Zobacz Zarządzanie regułami bazy danych czasu rzeczywistego Firebase przez REST .
Zarządzaj zestawami reguł za pomocą REST
Aby pomóc w zarządzaniu wdrożeniami dużych reguł, oprócz metody REST do tworzenia zestawów reguł i wydań, interfejs API zarządzania zapewnia metody:
- wyświetlać, pobierać i usuwać zestawy reguł
- wyświetlać, pobierać i usuwać wydania reguł
W przypadku bardzo dużych wdrożeń, które z upływem czasu osiągają limit 2500 zestawów reguł, można utworzyć logikę, aby usunąć najstarsze reguły w ustalonym cyklu czasowym. Na przykład, aby usunąć wszystkie zestawy reguł wdrożone na dłużej niż 30 dni, możesz wywołać metodę projects.rulesets.list , przeanalizować listę JSON obiektów Ruleset na ich kluczach createTime , a następnie wywołać project.rulesets.delete na odpowiednich zestawach reguł według ruleset_id .
Przetestuj swoje aktualizacje za pomocą REST
Wreszcie interfejs API do zarządzania umożliwia przeprowadzanie testów składniowych i semantycznych zasobów Cloud Firestore i Cloud Storage w projektach produkcyjnych.
Testowanie za pomocą tego komponentu API polega na:
- Definiowanie obiektu
TestSuiteJSON do reprezentowania zestawu obiektówTestCase - Przesyłanie pakietu
TestSuite - Analizowanie zwróconych obiektów
TestResult
Zdefiniujmy obiekt TestSuite z pojedynczym TestCase w pliku testcase.json . W tym przykładzie przekazujemy źródło języka reguł w linii z ładunkiem REST wraz z zestawem testów do uruchomienia na tych regułach. Określamy oczekiwanie dotyczące oceny Reguł oraz żądanie klienta, względem którego zestaw reguł ma zostać przetestowany. Można również określić stopień kompletności raportu z testu, używając wartości „FULL” w celu wskazania wyników dla wszystkich wyrażeń w języku reguł, które mają zostać uwzględnione w raporcie, w tym wyrażeń, które nie zostały dopasowane do żądania.
{
"source":
{
"files":
[
{
"name": "firestore.rules",
"content": "service cloud.firestore {
match /databases/{database}/documents {
match /users/{userId}{
allow read: if (request.auth.uid == userId);
}
function doc(subpath) {
return get(/databases/$(database)/documents/$(subpath)).data;
}
function isAccountOwner(accountId) {
return request.auth.uid == accountId
|| doc(/users/$(request.auth.uid)).accountId == accountId;
}
match /licenses/{accountId} {
allow read: if isAccountOwner(accountId);
}
}
}"
}
]
},
"testSuite":
{
"testCases":
[
{
"expectation": "ALLOW",
"request": {
"auth": {"uid": "123"},
"path": "/databases/(default)/documents/licenses/abcd",
"method": "get"},
"functionMocks": [
{
"function": "get",
"args": [{"exact_value": "/databases/(default)/documents/users/123"}],
"result": {"value": {"data": {"accountId": "abcd"}}}
}
]
}
]
}
}
Następnie możemy przesłać ten TestSuite do oceny za pomocą metody projects.test .
curl -X POST -d '{
' $(cat testcase.json) '
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets/uuid123:test'
Zwrócony TestReport (zawierający status testu SUCCESS/FAILURE, listy komunikatów debugowania, listy odwiedzonych wyrażeń Reguł i ich raporty z oceny) potwierdzi statusem SUCCESS, że dostęp jest prawidłowy.
Zarządzaj uprawnieniami dla międzyusługowych reguł bezpieczeństwa Cloud Storage
Jeśli utworzysz reguły bezpieczeństwa Cloud Storage, które wykorzystują zawartość dokumentu Cloud Firestore do oceny warunków bezpieczeństwa , w konsoli Firebase lub interfejsie wiersza polecenia Firebase pojawi się prośba o przyznanie uprawnień do połączenia tych dwóch produktów.
Jeśli zdecydujesz się wyłączyć takie zabezpieczenia między usługami:
Najpierw przed wyłączeniem tej funkcji edytuj swoje reguły, usuwając wszystkie instrukcje, które używają funkcji Reguły do uzyskiwania dostępu do Cloud Firestore. W przeciwnym razie po wyłączeniu tej funkcji oceny reguł spowodują niepowodzenie żądań dotyczących miejsca na dane.
Użyj strony IAM w Google Cloud Console, aby usunąć rolę „Firebase Rules Firestore Service Agent”, postępując zgodnie z przewodnikiem Cloud dotyczącym odwoływania ról .
Zostaniesz poproszony o ponowne włączenie tej funkcji przy następnym zapisywaniu Reguł międzyusługowych z Firebase CLI lub konsoli Firebase.