Firebase ti offre diversi strumenti per gestire il tuo Rules, ognuno utile in casi particolari e ognuno che utilizza la stessa API di gestione delle regole di sicurezza di Firebase di backend.
Indipendentemente dallo strumento utilizzato per richiamarla, l'API Management:
- Inserisce un'origine di regole: un insieme di regole, in genere un file di codice contenente istruzioni Firebase Security Rules.
- Archivia l'origine inserita come ruleset immutabile.
- Monitora il deployment di ogni insieme di regole in una release. I servizi abilitati alle regole di sicurezza di Firebase cercano la release di un progetto per valutare ogni richiesta di una risorsa protetta.
- Fornisce la possibilità di eseguire test sintattici e semantici di un insieme di regole.
Utilizza l'interfaccia a riga di comando Firebase
Con la Firebase CLI, puoi caricare origini locali ed eseguire il deployment delle release. L'interfaccia a riga di comando Firebase Local Emulator Suite ti consente di eseguire test locali completi delle origini.
L'utilizzo della CLI ti consente di mantenere le regole sotto il controllo della versione con il codice dell'applicazione e di eseguire il deployment delle regole nell'ambito del processo di deployment esistente.
Generare un file di configurazione
Quando configuri il progetto Firebase utilizzando la CLI Firebase, crei
un file di configurazione .rules nella directory del progetto. Utilizza il seguente comando per iniziare a configurare il progetto Firebase:
Cloud Firestore
// Set up Firestore in your project directory, creates a .rules file firebase init firestore
Realtime Database
// Set up Realtime Database in your project directory, creates a .rules file firebase init database
Cloud Storage
// Set up Storage in your project directory, creates a .rules file firebase init storage
Modificare e aggiornare le regole
Modifica l'origine delle regole direttamente nel file di configurazione .rules.
Assicurati che le modifiche apportate nella CLI Firebase vengano riflesse nella console Firebase oppure che gli aggiornamenti vengano eseguiti in modo coerente utilizzando la console Firebase o Firebase CLI. In caso contrario, potresti sovrascrivere gli aggiornamenti apportati nella console Firebase.
Testare gli aggiornamenti
Local Emulator Suite fornisce emulatori per tutti i prodotti abilitati alle regole di sicurezza. Il motore delle regole di sicurezza per ogni emulatore esegue la valutazione sintattica e semantica delle regole, superando così il test sintattico offerto dall'API di gestione delle regole di sicurezza.
Se utilizzi la CLI, Suite è uno strumento eccellente per i Firebase Security Rules test. Utilizza Local Emulator Suite per testare gli aggiornamenti in locale e verificare che Rules della tua app si comportino come desideri.
Esegui il deployment degli aggiornamenti
Dopo aver aggiornato e testato il Rules, implementa le origini in produzione.
Per Cloud Firestore Security Rules, associa i file .rules ai database denominati predefiniti e aggiuntivi esaminando e aggiornando il file firebase.json.
Utilizza i seguenti comandi per eseguire il deployment selettivo dei tuoi Rules singolarmente o come parte della normale procedura di deployment.
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>
Realtime Database
// Deploy your .rules file firebase deploy --only database
Cloud Storage
// Deploy your .rules file firebase deploy --only storage
Utilizzare la console Firebase
Puoi anche modificare le origini Rules e implementarle come release dalla console Firebase. I test sintattici vengono eseguiti durante la modifica nell'interfaccia utente della console Firebase, mentre i test semantici sono disponibili utilizzando il playground Rules.
Modificare e aggiornare le regole
- Apri la console Firebase e seleziona il tuo progetto.
- Quindi, seleziona Realtime Database, Cloud Firestore o Archiviazione dalla navigazione dei prodotti, quindi fai clic su Regole per accedere all'editor Rules.
- Modifica le regole direttamente nell'editor.
Testare gli aggiornamenti
Oltre a testare la sintassi nell'interfaccia utente dell'editor, puoi testare il comportamento semantico Rules utilizzando le risorse di database e archiviazione del progetto direttamente nella console Firebase, utilizzando il Rules Playground. Apri la schermata Rules Playground nell'editor Rules, modifica le impostazioni e fai clic su Esegui. Cerca il messaggio di conferma nella parte superiore dell'editor.
Esegui il deployment degli aggiornamenti
Quando hai verificato che gli aggiornamenti sono quelli che ti aspetti, fai clic su Pubblica.
Utilizzare l'SDK Admin
Puoi utilizzare i Admin SDK per i set di regole Node.js. Con questo accesso programmatico, puoi:
- Implementa strumenti, script, dashboard e pipeline CI/CD personalizzati per la gestione delle regole.
- Gestisci più facilmente le regole in più progetti Firebase.
Quando aggiorni le regole in modo programmatico, è molto importante evitare di apportare modifiche non intenzionali al controllo dell'accesso per la tua app. Scrivi il tuo codice Admin SDK tenendo presente soprattutto la sicurezza, in particolare quando aggiorni o implementi le regole.
Un altro aspetto importante da tenere presente è che le release Firebase Security Rules richiedono diversi minuti per la propagazione completa. Quando utilizzi Admin SDK per il deployment delle regole, assicurati di evitare condizioni di competizione in cui la tua app si basa immediatamente su regole il cui deployment non è ancora completato. Se il tuo caso d'uso richiede aggiornamenti frequenti delle regole di controllo dell'accesso, valuta soluzioni che utilizzano Cloud Firestore, progettato per ridurre le race condition nonostante gli aggiornamenti frequenti.
Tieni presente anche questi limiti:
- Le regole devono avere una dimensione inferiore a 256 KiB di testo codificato in UTF-8 quando vengono serializzate.
- Un progetto può avere al massimo 2500 ruleset totali di cui è stato eseguito il deployment. Una volta raggiunto questo limite, devi eliminare alcuni insiemi di regole precedenti prima di crearne di nuovi.
Creare ed eseguire il deployment di set di regole Cloud Storage o Cloud Firestore
Un workflow tipico per la gestione delle regole di sicurezza con Admin SDK potrebbe includere tre passaggi distinti:
- Creare un'origine file di regole (facoltativo)
- Creare un set di regole
- Rilascia o esegui il deployment del nuovo set di regole
L'SDK fornisce un metodo per combinare questi passaggi in una singola chiamata API per le regole di sicurezza di Cloud Storage e Cloud Firestore. Ad 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);
Lo stesso pattern funziona per le regole Cloud Storage con releaseFirestoreRulesetFromSource().
In alternativa, puoi creare il file delle regole come oggetto in memoria, creare il ruleset e implementarlo separatamente per un controllo più preciso di questi eventi. Ad 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 di Realtime Database
Per aggiornare i set di regole Realtime Database con Admin SDK, utilizza i metodi getRules() e
setRules() di admin.database. Puoi recuperare i set di regole in formato JSON o come stringa con i commenti inclusi.
Per aggiornare un insieme di regole:
const source = `{
"rules": {
"scores": {
".indexOn": "score",
"$uid": {
".read": "$uid == auth.uid",
".write": "$uid == auth.uid"
}
}
}
}`;
await admin.database().setRules(source);
Gestire i set di regole
Per gestire meglio i set di regole di grandi dimensioni, Admin SDK ti consente di elencare tutte le regole esistenti
con admin.securityRules().listRulesetMetadata. Ad 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 le implementazioni molto grandi che raggiungono il limite di 2500 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 di cui è stato eseguito il deployment 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.`);
Utilizzo dell'API REST
Gli strumenti descritti sopra sono adatti a vari flussi di lavoro, tra cui la gestione di più database Cloud Firestore nel tuo progetto, Firebase Security Rules ma potresti voler gestire e implementare Firebase Security Rules utilizzando l'API di gestione stessa. L'API di gestione offre la massima flessibilità.
Tieni presente anche questi limiti:
- Le regole devono avere una dimensione inferiore a 256 KiB di testo codificato in UTF-8 quando vengono serializzate.
- Un progetto può avere al massimo 2500 ruleset totali di cui è stato eseguito il deployment. Una volta raggiunto questo limite, devi eliminare alcuni insiemi di regole precedenti prima di crearne di nuovi.
Creare ed eseguire il deployment di set di regole Cloud Firestore o Cloud Storage con REST
Gli esempi in questa sezione utilizzano Firestore Rules, ma si applicano anche a Cloud Storage Rules.
Gli esempi utilizzano anche cURL per effettuare chiamate API. I passaggi per configurare e superare i token di autenticazione vengono omessi. Puoi sperimentare questa API utilizzando Explorer API integrato nella documentazione di riferimento.
I passaggi tipici per creare e implementare un insieme di regole utilizzando l'API di gestione sono:
- Creare origini file di regole
- Creare un set di regole
- Rilascia (esegui il deployment) il nuovo insieme di regole.
Crea un'origine
Supponiamo che tu stia lavorando al tuo progetto Firebase secure_commerce e voglia
eseguire il deployment di Cloud Firestore Rules bloccato in un database del 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;
}
}
}
Creare un set di regole
Ora genera un'impronta con codifica base64 per questo file. Puoi quindi utilizzare l'origine in questo file per compilare il payload necessario per creare un ruleset con la chiamata REST projects.rulesets.create. Qui, utilizza il comando cat per inserire
i contenuti di firestore.rules nel payload REST.
Per il monitoraggio, per associare questo valore 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 (eseguire il deployment) un set di regole
Se il set di regole è valido, l'ultimo passaggio consiste nell'implementare il nuovo set di regole in una release 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 release di Firebase Security Rules richiedono diversi minuti per essere propagate completamente. Quando utilizzi l'API REST di gestione per il deployment, assicurati di evitare condizioni di competizione in cui la tua app si basa immediatamente su regole il cui deployment non è ancora completato.
Aggiorna i set di regole Realtime Database con REST
Realtime Database fornisce la propria interfaccia REST per la gestione di Rules. Consulta Gestione di Firebase Realtime Database Rules tramite REST.
Gestire i set di regole con REST
Per facilitare la gestione delle implementazioni di regole di grandi dimensioni, oltre a un metodo REST per la creazione di regole e release, l'API di gestione fornisce metodi per:
- elencare, recuperare ed eliminare ruleset
- elencare, recuperare ed eliminare le regole releases
Per le implementazioni molto grandi che raggiungono il limite di 2500 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 di cui è stato eseguito il deployment per più di 30 giorni, puoi chiamare il metodo projects.rulesets.list, analizzare l'elenco JSON degli oggetti Ruleset nelle relative chiavi createTime, quindi chiamare project.rulesets.delete sui set di regole corrispondenti per ruleset_id.
Testare gli aggiornamenti con REST
Infine, l'API Management consente di eseguire test sintattici e semantici sulle risorse Cloud Firestore e Cloud Storage nei progetti di produzione.
Il test con questo componente dell'API consiste in:
- Definizione di un oggetto JSON
TestSuiteper rappresentare un insieme di oggettiTestCase - Invio di
TestSuitein corso - Analisi degli oggetti
TestResultrestituiti
Definiamo un oggetto TestSuite con un singolo TestCase in un
file testcase.json. In questo esempio, trasmettiamo l'origine della lingua Rules
in linea con il payload REST, insieme alla suite di test da eseguire
su queste regole. Specifichiamo un'aspettativa di valutazione delle regole e la richiesta del client rispetto alla quale deve essere testato il set di regole. Puoi anche specificare il livello di completezza del report di test utilizzando il valore "FULL" per indicare che nel report devono essere incluse le espressioni linguistiche di Rules, comprese quelle che non corrispondono 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 questo 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'L'oggetto TestReport restituito (contenente lo stato di riuscita/errore del test, elenchi di
messaggi di debug, elenchi di espressioni di regole visitate e i relativi report di valutazione)
conferma con lo stato SUCCESS che l'accesso è consentito correttamente.
Gestisci le autorizzazioni per Cloud Storage Security Rules cross-service
Se crei Cloud Storage Security Rules che utilizzano i contenuti dei documenti Cloud Firestore per valutare le condizioni di sicurezza, ti verrà chiesto nella console Firebase o nell'interfaccia a riga di comando Firebase di attivare le autorizzazioni per connettere i due prodotti.
Se decidi di disattivare questa sicurezza cross-service:
Prima di disattivare la funzionalità, modifica le regole rimuovendo tutte le istruzioni che utilizzano le funzioni Rules per accedere a Cloud Firestore. In caso contrario, dopo la disattivazione della funzionalità, le valutazioni Rules causeranno l'esito negativo delle richieste di archiviazione.
Utilizza la pagina IAM nella console Google Cloud per eliminare il ruolo "Agente di servizio Firebase Rules Firestore" seguendo la guida di Cloud per la revoca dei ruoli.
Ti verrà chiesto di riattivare la funzionalità la prossima volta che salvi le regole tra servizi diversi dalla CLI Firebase o dalla console Firebase.