Firebase ti mette a disposizione diversi strumenti per gestire le tue Regole, ognuno utile in casi particolari, e ognuno utilizzando la stessa API di gestione delle Regole di Sicurezza Firebase back-end.
Indipendentemente dallo strumento utilizzato per richiamarlo, l'API di gestione:
- Importa una fonte di regole: un insieme di regole, in genere un file di codice contenente le istruzioni delle regole di sicurezza Firebase.
- Memorizza l'origine acquisita come un set di regole immutabile.
- Tiene traccia della distribuzione di ciascun set di regole in una versione . I servizi abilitati per le regole di sicurezza di Firebase cercano la versione di un progetto per valutare ogni richiesta di una risorsa protetta.
- Fornisce la capacità di eseguire test sintattici e semantici di un set di regole.
Utilizza l'interfaccia a riga di comando di Firebase
Con l' interfaccia a riga di comando di Firebase , puoi caricare fonti locali e distribuire le versioni . La Firebase Local Emulator Suite della CLI ti consente di eseguire test locali completi delle fonti .
L'utilizzo dell'interfaccia a riga di comando consente di mantenere le regole sotto controllo della versione con il codice dell'applicazione e di distribuire le regole come parte del processo di distribuzione esistente.
Genera un file di configurazione
Quando configuri il tuo progetto Firebase utilizzando l'interfaccia a riga di comando di Firebase, crei un file di configurazione .rules nella directory del progetto. Usa il seguente comando per iniziare a configurare il tuo progetto Firebase:
CloudFirestore
// Set up Firestore in your project directory, creates a .rules file firebase init firestore
Database in tempo reale
// Set up Realtime Database in your project directory, creates a .rules file firebase init database
Archiviazione cloud
// Set up Storage in your project directory, creates a .rules file firebase init storage
Modifica e aggiorna le tue regole
Modifica l'origine delle regole direttamente nel file di configurazione .rules .
Assicurati che tutte le modifiche apportate nell'interfaccia a riga di comando di Firebase si riflettano nella console di Firebase o di apportare costantemente aggiornamenti utilizzando la console di Firebase o l'interfaccia a riga di comando di Firebase. In caso contrario, potresti sovrascrivere eventuali aggiornamenti effettuati nella console Firebase.
Metti alla prova i tuoi aggiornamenti
Local Emulator Suite fornisce emulatori per tutti i prodotti abilitati per le regole di sicurezza. Il motore delle regole di sicurezza per ciascun emulatore esegue la valutazione sintattica e semantica delle regole, superando così i test sintattici offerti dall'API di gestione delle regole di sicurezza.
Se lavori con la CLI, la suite è uno strumento eccellente per testare le regole di sicurezza di Firebase. Usa Local Emulator Suite per testare gli aggiornamenti in locale e verificare che le regole della tua app presentino il comportamento desiderato.
Distribuisci i tuoi aggiornamenti
Dopo aver aggiornato e testato le tue regole, distribuisci le fonti alla produzione.
Per le regole di sicurezza di Cloud Firestore, associa i file .rules ai database denominati predefiniti e aggiuntivi rivedendo e aggiornando il file firebase.json .
Utilizza i seguenti comandi per distribuire in modo selettivo le tue regole da solo o distribuirle come parte del normale processo di distribuzione.
CloudFirestore
// 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>
Database in tempo reale
// Deploy your .rules file firebase deploy --only database
Archiviazione cloud
// Deploy your .rules file firebase deploy --only storage
Usa la console Firebase
Puoi anche modificare le origini delle regole e distribuirle come versioni dalla console Firebase. Il test sintattico viene eseguito mentre modifichi nell'interfaccia utente della console Firebase e il test semantico è disponibile utilizzando Rules Playground.
Modifica e aggiorna le tue regole
- Apri la console Firebase e seleziona il tuo progetto.
- Quindi, seleziona Realtime Database , Cloud Firestore o Storage dalla navigazione del prodotto, quindi fai clic su Regole per passare all'editor delle regole.
- Modifica le tue regole direttamente nell'editor.
Metti alla prova i tuoi aggiornamenti
Oltre a testare la sintassi nell'interfaccia utente dell'editor, puoi testare il comportamento delle regole semantiche, utilizzando il database e le risorse di archiviazione del tuo progetto, direttamente nella console di Firebase, utilizzando Rules Playground . Apri la schermata Rules Playground nell'editor delle regole, modifica le impostazioni e fai clic su Esegui . Cerca il messaggio di conferma nella parte superiore dell'editor.
Distribuisci i tuoi aggiornamenti
Una volta verificato che gli aggiornamenti siano quelli previsti, fai clic su Pubblica .
Utilizza l'SDK di amministrazione
Puoi utilizzare Admin SDK per i set di regole Node.js . Con questo accesso programmatico, puoi:
- Implementa strumenti personalizzati, script, dashboard e pipeline CI/CD per la gestione delle regole.
- Gestisci le regole più facilmente su più progetti Firebase.
Quando si aggiornano le regole a livello di programmazione, è molto importante evitare di apportare modifiche indesiderate al controllo degli accessi per l'app. Scrivi il codice dell'SDK Admin tenendo presente la sicurezza, in particolare durante l'aggiornamento o la distribuzione delle regole.
Un'altra cosa importante da tenere a mente è che le versioni delle regole di sicurezza di Firebase impiegano diversi minuti per propagarsi completamente. Quando utilizzi Admin SDK per distribuire le regole, assicurati di evitare race condition in cui la tua app si basa immediatamente su regole la cui distribuzione non è ancora stata completata. Se il tuo caso d'uso richiede aggiornamenti frequenti per le regole di controllo degli accessi, prendi in considerazione soluzioni che utilizzano Cloud Firestore, progettato per ridurre le race condition nonostante i frequenti aggiornamenti.
Si noti inoltre questi limiti:
- Le regole devono essere inferiori a 256 KiB di testo con codifica UTF-8 quando serializzate.
- Un progetto può avere al massimo 2500 set di regole distribuiti in totale. Una volta raggiunto questo limite, è necessario eliminare alcuni vecchi set di regole prima di crearne di nuovi.
Crea e distribuisci i set di regole di Cloud Storage o Cloud Firestore
Un flusso di lavoro tipico per la gestione delle regole di sicurezza con Admin SDK potrebbe includere tre passaggi distinti:
- Creare un'origine del file delle regole (facoltativo)
- Crea un set di regole
- Rilascia o distribuisci il nuovo set di regole
L'SDK fornisce un metodo per combinare questi passaggi in un'unica chiamata API per le regole di sicurezza di Cloud Storage e Cloud Firestore. Per esempio:
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);
Questo stesso modello funziona per le regole di Cloud Storage con releaseFirestoreRulesetFromSource() .
In alternativa, puoi creare il file delle regole come oggetto in memoria, creare il set di regole e distribuire il set di regole separatamente per un controllo più stretto di questi eventi. Per esempio:
const rf = admin.securityRules().createRulesFileFromSource('firestore.rules', source);
const rs = await admin.securityRules().createRuleset(rf);
await admin.securityRules().releaseFirestoreRuleset(rs);
Aggiorna i set di regole del database in tempo reale
Per aggiornare i set di regole di Realtime Database con Admin SDK, utilizzare i metodi getRules() e setRules() di admin.database . Puoi recuperare i set di regole in formato JSON o come stringa con commenti inclusi.
Per aggiornare un set di regole:
const source = `{
"rules": {
"scores": {
".indexOn": "score",
"$uid": {
".read": "$uid == auth.uid",
".write": "$uid == auth.uid"
}
}
}
}`;
await admin.database().setRules(source);
Gestisci set di regole
Per aiutare a gestire set di regole di grandi dimensioni, Admin SDK ti consente di elencare tutte le regole esistenti con admin.securityRules().listRulesetMetadata . Per esempio:
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;
}
}
Per distribuzioni molto grandi che raggiungono il limite di 2500 set di regole nel tempo, puoi creare una logica per eliminare le regole meno recenti in un ciclo di tempo fisso. Ad esempio, per eliminare tutti i set di regole distribuiti per più di 30 giorni:
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.`);
Utilizzare l'API REST
Gli strumenti sopra descritti sono adatti a vari flussi di lavoro, inclusa la gestione delle regole di sicurezza di Firebase per più database Cloud Firestore nel tuo progetto, ma potresti voler gestire e distribuire le regole di sicurezza di Firebase utilizzando l'API di gestione stessa. L'API di gestione offre la massima flessibilità.
Si noti inoltre questi limiti:
- Le regole devono essere inferiori a 256 KiB di testo con codifica UTF-8 quando serializzate.
- Un progetto può avere al massimo 2500 set di regole distribuiti in totale. Una volta raggiunto questo limite, è necessario eliminare alcuni vecchi set di regole prima di crearne di nuovi.
Crea e distribuisci i set di regole di Cloud Firestore o Cloud Storage con REST
Gli esempi in questa sezione utilizzano le regole Firestore, sebbene si applichino anche alle regole di Cloud Storage.
Gli esempi usano anche cURL per effettuare chiamate API. I passaggi per impostare e passare i token di autenticazione sono stati omessi. Puoi sperimentare questa API utilizzando l'API Explorer integrato con la documentazione di riferimento.
I passaggi tipici per la creazione e la distribuzione di un set di regole utilizzando l'API di gestione sono:
- Creare origini file di regole
- Crea un set di regole
- Rilasciare (distribuire) il nuovo set di regole.
Crea una fonte
Supponiamo che tu stia lavorando al tuo progetto Firebase secure_commerce e desideri distribuire regole Cloud Firestore bloccate in un database nel tuo progetto denominato east_store .
Puoi implementare queste regole in un file firestore.rules .
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if false;
}
}
}
Crea un set di regole
Ora, genera un'impronta digitale con codifica Base64 per questo file. Puoi quindi utilizzare l'origine in questo file per popolare il payload necessario per creare un set di regole con la chiamata REST projects.rulesets.create . Qui, utilizza il comando cat per inserire il contenuto di firestore.rules nel payload REST.
Per il monitoraggio, per associarlo al tuo database east_store , imposta attachment_point su 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'
L'API restituisce una risposta di convalida e un nome del set di regole, ad esempio projects/secure_commerce/rulesets/uuid123 .
Rilasciare (distribuire) un set di regole
Se il set di regole è valido, il passaggio finale consiste nel distribuire il nuovo set di regole in una versione denominata.
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'
Tieni presente che le versioni delle regole di sicurezza di Firebase impiegano diversi minuti per propagarsi completamente. Quando utilizzi l'API REST di gestione per la distribuzione, assicurati di evitare race condition in cui l'app si basa immediatamente su regole la cui distribuzione non è ancora stata completata.
Aggiorna i set di regole del database in tempo reale con REST
Realtime Database fornisce la propria interfaccia REST per la gestione delle regole. Consulta Gestione delle regole del database in tempo reale di Firebase tramite REST .
Gestisci i set di regole con REST
Per aiutare a gestire le distribuzioni di regole di grandi dimensioni, oltre a un metodo REST per la creazione di set di regole e rilasci, l'API di gestione fornisce metodi per:
- elencare, ottenere ed eliminare set di regole
- elencare, ottenere ed eliminare i rilasci delle regole
Per distribuzioni molto grandi che raggiungono il limite di 2500 set di regole nel tempo, puoi creare una logica per eliminare le regole meno recenti in un ciclo di tempo fisso. Ad esempio, per eliminare tutti i set di regole distribuiti per più di 30 giorni, puoi chiamare il metodo projects.rulesets.list , analizzare l'elenco JSON degli oggetti del set Ruleset sulle relative chiavi createTime , quindi chiamare project.rulesets.delete sui set di regole corrispondenti tramite ruleset_id .
Testa i tuoi aggiornamenti con REST
Infine, l'API di gestione ti consente di eseguire test sintattici e semantici sulle risorse Cloud Firestore e Cloud Storage nei tuoi progetti di produzione.
Il test con questo componente dell'API consiste in:
- Definizione di un oggetto JSON
TestSuiteper rappresentare un set di oggettiTestCase - Invio della
TestSuite - L'analisi ha restituito gli oggetti
TestResult
Definiamo un oggetto TestSuite con un singolo TestCase in un file testcase.json . In questo esempio, passiamo l'origine del linguaggio Rules in linea con il payload REST, insieme alla suite di test da eseguire su tali regole. Specifichiamo un'aspettativa di valutazione delle regole e la richiesta del client rispetto alla quale deve essere testato il set di regole. È inoltre possibile specificare la completezza del report del test, utilizzando il valore "FULL" per indicare i risultati per tutte le espressioni del linguaggio Rules da includere nel report, comprese le espressioni che non sono state abbinate alla richiesta.
{
"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"}}}
}
]
}
]
}
}
Possiamo quindi inviare questa TestSuite per la valutazione con il metodo projects.test .
curl -X POST -d '{
' $(cat testcase.json) '
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets/uuid123:test'
Il TestReport restituito (contenente lo stato del test SUCCESS/FAILURE, gli elenchi dei messaggi di debug, gli elenchi delle espressioni delle regole visitate ei relativi rapporti di valutazione) confermerebbe con lo stato SUCCESS che l'accesso è consentito correttamente.
Gestisci le autorizzazioni per le regole di sicurezza di Cloud Storage tra servizi
Se crei regole di sicurezza di Cloud Storage che utilizzano i contenuti dei documenti di Cloud Firestore per valutare le condizioni di sicurezza , nella console di Firebase o nella CLI di Firebase ti verrà chiesto di abilitare le autorizzazioni per connettere i due prodotti.
Se decidi di disabilitare tale sicurezza tra servizi:
Innanzitutto, prima di disabilitare la funzione, modifica le tue regole, rimuovendo tutte le istruzioni che utilizzano le funzioni delle regole per accedere a Cloud Firestore. In caso contrario, dopo che la funzione è stata disabilitata, le valutazioni delle regole causeranno il fallimento delle richieste di archiviazione.
Utilizza la pagina IAM in Google Cloud Console per eliminare il ruolo "Firebase Rules Firestore Service Agent" seguendo la guida al cloud per la revoca dei ruoli .
Ti verrà chiesto di riattivare la funzione la prossima volta che salvi le regole cross-service dall'interfaccia a riga di comando di Firebase o dalla console di Firebase.