Catch up on everthing we announced at this year's Firebase Summit. Learn more

Aprenda a sintaxe principal das regras de segurança do Firebase para a linguagem Cloud Storage

As regras de segurança do Firebase para Cloud Storage permitem que você controle o acesso a objetos armazenados em intervalos do Cloud Storage. A sintaxe de regras flexíveis permite que você crie regras para controlar qualquer operação, desde todas as gravações em seu intervalo do Cloud Storage até operações em um arquivo específico.

Este guia descreve a sintaxe básica e a estrutura das regras de segurança do Cloud Storage para criar conjuntos de regras completos.

Declaração de serviço e banco de dados

As regras de segurança do Firebase para Cloud Storage sempre começam com a seguinte declaração:

service firebase.storage {
    // ...
}

O service firebase.storage declaração escopos as regras para Cloud Storage, evitando conflitos entre normas e regras de armazenamento em nuvem de segurança para outros produtos, como Nuvem Firestore.

Regras básicas de leitura / gravação

Regras básicas consistem em um match declaração identificando baldes armazenamento em nuvem, uma declaração jogo especificando um nome de arquivo e uma allow expressão detalhando ao ler os dados especificados é permitido. allow expressões especificar os métodos de acesso (por exemplo, ler, escrever) envolvidos, e as condições sob as quais o acesso é permitido ou negado.

No seu conjunto de regras padrão, o primeiro match instrução utiliza um {bucket} expressão curinga para indicar as regras se aplicam a todos os baldes em seu projeto. Discutiremos a ideia de correspondências de curinga mais na próxima seção.

service firebase.storage {
  // The {bucket} wildcard indicates we match files in all Cloud Storage buckets
  match /b/{bucket}/o {
    // Match filename
    match /filename {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

Todas as instruções de correspondência apontam para arquivos. A instrução de correspondência pode apontar para um arquivo específico, como no match /images/profilePhoto.png .

Corresponder curingas

Em additiont a apontar para um único arquivo, regras pode usar curingas para apontar para qualquer arquivo com um determinado prefixo corda em seu nome, incluindo barras, como no match /images/{imageId} .

No exemplo acima, a declaração jogo usa o {imageId} sintaxe curinga. Isto significa que a regra se aplica a qualquer arquivo com /images/ no início de seu nome, como /images/profilePhoto.png ou /images/croppedProfilePhoto.png . Quando a allow expressões na instrução de correspondência são avaliados, o imageId variável determinará o nome do arquivo de imagem, como profilePhoto.png ou croppedProfilePhoto.png .

Uma variável curinga pode ser referenciada a partir do match de fornecer um nome de arquivo ou autorização caminho:

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

Dados hierárquicos

Como dissemos antes, não há estrutura hierárquica dentro de um intervalo do Cloud Storage. Mas, usando uma convenção de nomenclatura de arquivo, geralmente uma que inclui barras nos nomes de arquivos, podemos imitar uma estrutura que se parece com uma série aninhada de diretórios e subdiretórios. É importante entender como as regras de segurança do Firebase interagem com esses nomes de arquivo.

Considere a situação de um conjunto de arquivos com nomes que começam com as /images/ -tronco. Regras de Segurança Firebase aplicam-se apenas com o nome do arquivo combinado, para que os controles de acesso definidas nas /images/ -tronco não se aplicam à /mp3s/ -tronco. Em vez disso, escreva regras explícitas que correspondam a diferentes padrões de nome de arquivo:

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      allow read, write: if <condition>;
    }

    // Explicitly define rules for the 'mp3s' pattern
    match /mp3s/{mp3Id} {
      allow read, write: if <condition>;
    }
  }
}

Ao aninhar match declarações, o caminho do interior match declaração está sempre anexado ao caminho do exterior match comunicado. Os dois conjuntos de regras a seguir são, portanto, equivalentes:

service firebase.storage {
  match /b/{bucket}/o {
    match /images {
      // Exact match for "images/profilePhoto.png"
      match /profilePhoto.png {
        allow write: if <condition>;
      }
    }
  }
}
service firebase.storage {
  match /b/{bucket}/o {
    // Exact match for "images/profilePhoto.png"
    match /images/profilePhoto.png {
      allow write: if <condition>;
      }
  }
}

Caracteres curinga de correspondência recursiva

Além de curingas que as cordas jogo e retorno no final de um nome de arquivo, um curinga segmento múltipla podem ser declaradas para a correspondência mais complexo, acrescentando =** ao nome curinga, como {path=**} :

// Partial match for files that start with "images"
match /images {

  // Exact match for "images/**"
  // e.g. images/users/user:12345/profilePhoto.png is matched
  // images/profilePhoto.png is also matched!
  match /{allImages=**} {
    // This rule matches one or more path segments (**)
    // allImages is a path that contains all segments matched
    allow read: if <other_condition>;
  }
}

Se várias regras corresponder a um arquivo, o resultado é o OR do resultado de todas as regras avaliações. Ou seja, se qualquer regra do arquivo corresponde resulte em true , o resultado é true .

Nas regras acima, o arquivo "images / profilePhoto.png" pode ser lido se qualquer condition ou other_condition avaliar a verdade, enquanto o arquivo "images / usuários / user: 12345 / profilePhoto.png" apenas está sujeita ao resultado de other_condition .

As regras de segurança do Cloud Storage não se propagam e as regras são avaliadas apenas quando o caminho da solicitação corresponde a um caminho com as regras especificadas.

Versão 1

As regras de segurança do Firebase usam a versão 1 por padrão. Na versão 1, os curingas recursivos correspondem a um ou mais elementos do nome do arquivo, não a zero ou mais elementos. Assim, match /images/{filenamePrefixWildcard}/{imageFilename=**} corresponde a um nome de arquivo como /images/profilePics/profile.png, mas não /images/badge.png. Use /images/{imagePrefixorFilename=**} vez.

Os curingas recursivos devem vir no final de uma instrução de correspondência.

Recomendamos que você use a versão 2 por seus recursos mais poderosos.

Versão 2

Na versão 2 das regras de segurança do Firebase, os caracteres curinga recursivos correspondem a zero ou mais itens de caminho. Assim, /images/{filenamePrefixWildcard}/{imageFilename=**} corresponde nomes de arquivos /images/profilePics/profile.png e /images/badge.png.

Você deve opt-in para a versão 2, adicionando rules_version = '2'; no topo de suas regras de segurança:

rules_version = '2';
service cloud.storage {
  match /b/{bucket}/o {
   ...
 }
}

Você pode ter no máximo um curinga recursivo por instrução de correspondência, mas na versão 2, você pode colocar esse curinga em qualquer lugar da instrução de correspondência. Por exemplo:

rules_version = '2';
service firebase.storage {
 match /b/{bucket}/o {
   // Matches any file in a songs "subdirectory" under the
   // top level of your Cloud Storage bucket.
   match /{prefixSegment=**}/songs/{mp3filenames} {
     allow read, write: if <condition>;
   }
  }
}

Operações granulares

Em algumas situações, é útil para quebrar read e write em operações mais granulares. Por exemplo, seu aplicativo pode querer impor condições diferentes na criação do arquivo e na exclusão do arquivo.

A read operação pode ser dividida em get e list .

A write regra pode ser quebrada em create , update e delete :

service firebase.storage {
  match /b/{bucket}/o {
    // A read rule can be divided into read and list rules
    match /images/{imageId} {
      // Applies to single document read requests
      allow get: if <condition>;
      // Applies to list and listAll requests (Rules Version 2)
      allow list: if <condition>;

    // A write rule can be divided into create, update, and delete rules
    match /images/{imageId} {
      // Applies to writes to nonexistent files
      allow create: if <condition>;

      // Applies to updates to file metadata
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
 }
}

Declarações de correspondência sobrepostas

É possível que um nome de arquivo para combinar mais de um match comunicado. No caso em que múltiplos allow expressões corresponder a um pedido, o acesso é permitido se qualquer uma das condições é true :

service firebase.storage {
  match b/{bucket}/o {
    // Matches any filename containing string '/images/'.
    match /images/{imageId} {
      allow read, write: if false;
    }

    // Matches all filenames containing string `/images/`
    match /images/{imageId=**} {
      allow read, write: if true;
    }
  }
}

No exemplo acima, todos lê e grava em arquivos com a corda /images/ em qualquer lugar em seu nome de arquivo será permitido porque a segunda regra é sempre true , mesmo que a primeira regra é sempre false .

Regras não são filtros

Depois de proteger seus dados e começar a executar operações de arquivo, lembre-se de que as regras de segurança não são filtros. Você não pode realizar operações em um conjunto de arquivos que correspondem a um padrão de nome de arquivo e esperar que o Cloud Storage acesse apenas os arquivos que o cliente atual tem permissão para acessar.

Por exemplo, considere a seguinte regra de segurança:

service firebase.storage {
  match /b/{bucket}/o {
    // Allow the client to read files with contentType 'image/png'
    match /aFileNamePrefix/{aFileName} {
      allow read: if resource.contentType == 'image/png';
    }
  }
}

Negado: Esta regra rejeita o seguinte pedido porque o conjunto de resultados pode incluir arquivos onde contentType não é image/png :

Rede
filesRef = storage.ref().child("aFilenamePrefix");

filesRef.listAll()
    .then(function(result) {
      console.log("Success: ", result.items);
    })
});

As regras no Cloud Storage Security Rules avaliam cada consulta em relação ao seu resultado potencial e falha na solicitação se puder retornar um arquivo que o cliente não tem permissão para ler. As solicitações de acesso devem seguir as restrições definidas por suas regras.

Próximos passos

Você pode aprofundar seu conhecimento sobre as regras de segurança do Firebase para armazenamento em nuvem:

Você pode explorar os casos de uso de regras de segurança do Firebase específicos para o Cloud Storage: