Utiliser des conditions dans les règles de sécurité Firebase Cloud Storage

Ce guide s'appuie sur le guide Apprendre la syntaxe de base du langage Firebase Security Rules pour vous montrer comment ajouter des conditions à votre Firebase Security Rules pour Cloud Storage.

La condition est le composant principal de Cloud Storage Security Rules. Une condition est une expression booléenne qui détermine si une opération spécifique doit être autorisée ou refusée. Pour les règles de base, l'utilisation de littéraux true et false comme conditions fonctionne parfaitement. Toutefois, le langage Firebase Security Rules pour Cloud Storage vous permet d'écrire des conditions plus complexes qui peuvent:

  • Vérifier l'authentification des utilisateurs
  • Valider les données entrantes

Authentification

Firebase Security Rules pour Cloud Storage s'intègre à Firebase Authentication pour fournir une authentification basée sur l'utilisateur puissante à Cloud Storage. Cela permet un contrôle granulaire des accès en fonction des revendications d'un jeton Firebase Authentication.

Lorsqu'un utilisateur authentifié effectue une requête auprès de Cloud Storage, la variable request.auth est renseignée avec le uid (request.auth.uid) de l'utilisateur, ainsi que les revendications du jeton JWT Firebase Authentication (request.auth.token).

De plus, lorsque vous utilisez une authentification personnalisée, des revendications supplémentaires s'affichent dans le champ request.auth.token.

Lorsqu'un utilisateur non authentifié effectue une requête, la variable request.auth est null.

À l'aide de ces données, il existe plusieurs méthodes courantes d'authentification pour sécuriser les fichiers:

  • Public: ignorer request.auth
  • Privé authentifié: vérifiez que request.auth n'est pas null
  • Privé de l'utilisateur: vérifiez que request.auth.uid est égal à un chemin uid
  • Groupe privé: vérifiez que les revendications du jeton personnalisé correspondent à une revendication choisie ou lisez les métadonnées du fichier pour voir si un champ de métadonnées existe.

Public

Toute règle qui ne tient pas compte du contexte request.auth peut être considérée comme une règle public, car elle ne tient pas compte du contexte d'authentification de l'utilisateur. Ces règles peuvent être utiles pour afficher des données publiques telles que des éléments de jeu, des fichiers audio ou d'autres contenus statiques.

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

Privé authentifié

Dans certains cas, vous pouvez souhaiter que les données soient visibles par tous les utilisateurs authentifiés de votre application, mais pas par les utilisateurs non authentifiés. Étant donné que la variable request.auth est null pour tous les utilisateurs non authentifiés, il vous suffit de vérifier que la variable request.auth existe pour exiger l'authentification:

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

Privé de l'utilisateur

Le cas d'utilisation le plus courant de request.auth consiste à fournir aux utilisateurs individuels des autorisations précises sur leurs fichiers, de l'importation de photos de profil à la lecture de documents privés.

Étant donné que les fichiers de Cloud Storage disposent d'un "chemin d'accès" complet, il suffit d'ajouter une information unique permettant d'identifier l'utilisateur dans le préfixe du nom de fichier (par exemple, le uid de l'utilisateur) pour que le fichier soit contrôlé par un utilisateur et puisse être vérifié lors de l'évaluation de la règle:

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

Groupe privé

Un autre cas d'utilisation tout aussi courant consiste à autoriser des autorisations de groupe sur un objet, par exemple pour autoriser plusieurs membres d'une équipe à collaborer sur un document partagé. Plusieurs approches sont possibles:

  • Créer un jeton personnalisé Firebase Authentication contenant des informations supplémentaires sur un membre de groupe (comme un ID de groupe)
  • Incluez des informations sur le groupe (telles qu'un ID de groupe ou une liste de uid autorisés) dans les métadonnées de fichier.

Une fois ces données stockées dans les métadonnées du jeton ou du fichier, elles peuvent être référencées dans une règle:

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

Demander une évaluation

Les importations, les téléchargements, les modifications de métadonnées et les suppressions sont évalués à l'aide de l'request envoyé à Cloud Storage. En plus de l'ID unique de l'utilisateur et de la charge utile Firebase Authentication dans l'objet request.auth, comme décrit ci-dessus, la variable request contient le chemin d'accès au fichier où la requête est effectuée, l'heure à laquelle la requête est reçue et la nouvelle valeur resource si la requête est une écriture.

L'objet request contient également l'ID unique de l'utilisateur et la charge utile Firebase Authentication dans l'objet request.auth, qui sera expliquée plus en détail dans la section Sécurité basée sur l'utilisateur de la documentation.

Vous trouverez ci-dessous la liste complète des propriétés de l'objet request:

Propriété Type Description
auth map<chaîne, chaîne> Lorsqu'un utilisateur est connecté, fournit uid, l'ID unique de l'utilisateur, et token, une carte des revendications JWT Firebase Authentication. Sinon, il est défini sur null.
params map<chaîne, chaîne> Carte contenant les paramètres de requête de la requête.
path chemin d'accès path représentant le chemin d'accès de la requête.
resource map<chaîne, chaîne> Nouvelle valeur de la ressource, présente uniquement dans les requêtes write.
time timestamp Code temporel représentant l'heure du serveur à laquelle la requête est évaluée.

Évaluation des ressources

Lorsque vous évaluez des règles, vous pouvez également évaluer les métadonnées du fichier importé, téléchargé, modifié ou supprimé. Vous pouvez ainsi créer des règles complexes et puissantes qui, par exemple, n'autorisent que les fichiers de certains types de contenu à être importés ou ne permettent de supprimer que les fichiers de plus d'une certaine taille.

Firebase Security Rules pour Cloud Storage fournit des métadonnées de fichier dans l'objet resource, qui contient des paires clé/valeur des métadonnées affichées dans un objet Cloud Storage. Ces propriétés peuvent être inspectées sur les requêtes read ou write pour garantir l'intégrité des données.

Pour les requêtes write (telles que les importations, les mises à jour de métadonnées et les suppressions), en plus de l'objet resource, qui contient les métadonnées du fichier existant actuellement dans le chemin de la requête, vous pouvez également utiliser l'objet request.resource, qui contient un sous-ensemble des métadonnées du fichier à écrire si l'écriture est autorisée. Vous pouvez utiliser ces deux valeurs pour garantir l'intégrité des données ou appliquer des contraintes d'application telles que le type ou la taille de fichier.

Vous trouverez ci-dessous la liste complète des propriétés de l'objet resource:

Propriété Type Description
name chaîne Nom complet de l'objet
bucket chaîne Nom du bucket dans lequel se trouve cet objet.
generation int Génération de l'objet Google Cloud Storage de cet objet.
metageneration int Métagénération de l'objet Google Cloud Storage de cet objet.
size int La taille de l'objet en octets.
timeCreated timestamp Code temporel représentant l'heure de création d'un objet.
updated timestamp Code temporel représentant l'heure à laquelle un objet a été mis à jour pour la dernière fois.
md5Hash chaîne Hachage MD5 de l'objet.
crc32c chaîne Un hachage CRC32C de l'objet.
etag chaîne Etag associé à cet objet.
contentDisposition chaîne Disposition du contenu associée à cet objet.
contentEncoding chaîne Encodage de contenu associé à cet objet.
contentLanguage chaîne Langue du contenu associé à cet objet.
contentType chaîne Type de contenu associé à cet objet.
metadata map<chaîne, chaîne> Paires clé/valeur de métadonnées personnalisées supplémentaires spécifiées par le développeur.

request.resource contient tous ces éléments, à l'exception de generation, metageneration, etag, timeCreated et updated.

Améliorer avec Cloud Firestore

Vous pouvez accéder aux documents dans Cloud Firestore pour évaluer d'autres critères d'autorisation.

Grâce aux fonctions firestore.get() et firestore.exists(), vos règles de sécurité peuvent évaluer les requêtes entrantes par rapport aux documents de Cloud Firestore. Les fonctions firestore.get() et firestore.exists() exigent des chemins d'accès de document complets. Lorsque vous utilisez des variables pour créer des chemins d'accès pour firestore.get() et firestore.exists(), vous devez explicitement échapper les variables à l'aide de la syntaxe $(variable).

Dans l'exemple ci-dessous, nous voyons une règle qui limite l'accès en lecture aux fichiers aux utilisateurs membres de clubs spécifiques.

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)).memberships
    }
  }
}
Dans l'exemple suivant, seuls les amis d'un utilisateur peuvent voir ses photos. 
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))
    }
  }
}

Une fois que vous avez créé et enregistré votre premier Cloud Storage Security Rules qui utilise ces fonctions Cloud Firestore, vous êtes invité dans la console Firebase ou la CLI Firebase à activer les autorisations permettant de connecter les deux produits.

Vous pouvez désactiver la fonctionnalité en supprimant un rôle IAM, comme décrit dans la section Gérer et déployer Firebase Security Rules.

Valider les données

Firebase Security Rules pour Cloud Storage peut également être utilisé pour la validation des données, y compris pour valider le nom et le chemin d'accès du fichier, ainsi que les propriétés de métadonnées du fichier telles que contentType et 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/.*');
    }
  }
}

Fonctions personnalisées

À mesure que vos Firebase Security Rules deviennent plus complexes, vous voudrez peut-être regrouper des ensembles de conditions dans des fonctions réutilisables dans votre ensemble de règles. Les règles de sécurité sont compatibles avec les fonctions personnalisées. La syntaxe des fonctions personnalisées ressemble à JavaScript ; cependant, les fonctions Firebase Security Rules sont écrites dans un langage propre au domaine, qui présente certaines limitations importantes:

  • Les fonctions ne peuvent contenir qu'une seule instruction return. Elles ne peuvent pas contenir de logique supplémentaire. Par exemple, ils ne peuvent pas exécuter de boucles ni appeler de services externes.
  • Les fonctions peuvent accéder automatiquement aux fonctions et aux variables du champ d'application dans lequel elles sont définies. Par exemple, une fonction définie dans le champ d'application service firebase.storage a accès à la variable resource et aux fonctions intégrées telles que get() et exists(), uniquement pour Cloud Firestore.
  • Les fonctions peuvent appeler d'autres fonctions, mais peuvent ne pas les inclure. La profondeur totale de la pile d'appel est limitée à 10.
  • Dans la version rules2, les fonctions peuvent définir des variables à l'aide du mot clé let. Les fonctions peuvent avoir un nombre illimité de liaisons "let", mais elles doivent se terminer par une instruction "return".

Une fonction est définie avec le mot clé function et accepte zéro ou plusieurs arguments. Par exemple, vous pouvez combiner les deux types de conditions utilisés dans les exemples ci-dessus en une seule fonction :

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

L'utilisation de fonctions dans votre Firebase Security Rules les rend plus faciles à gérer à mesure que la complexité de vos règles augmente.

Étapes suivantes

Après cette discussion sur les conditions, vous avez une compréhension plus sophistiquée des règles et vous êtes prêt à:

Découvrez comment gérer les principaux cas d'utilisation et le workflow de développement, de test et de déploiement des règles: