Firebase Cloud Storage Güvenlik Kurallarında koşulları kullanma

Bu kılavuzda, Cloud Storage için Firebase Security Rules'inize nasıl koşul ekleyeceğiniz gösterilmektedir. Bu bilgiler, Firebase Security Rules dilinin temel söz dizimini öğrenme kılavuzundan alınmıştır.

Cloud Storage Security Rules'ün birincil yapı taşı koşuldur. Koşul, belirli bir işleme izin verilip verilmeyeceğini belirleyen bir boole ifadesidir. Temel kurallarda, koşullar olarak true ve false değişmezlerini kullanmak mükemmel şekilde çalışır. Ancak Cloud Storage için Firebase Security Rules dili, daha karmaşık koşullar yazmanızı sağlar. Bu koşullar:

  • Kullanıcı kimlik doğrulamasını kontrol etme
  • Gelen verileri doğrulama

Doğrulama

Cloud Storage için Firebase Security Rules, Cloud Storage'a güçlü kullanıcı tabanlı kimlik doğrulama sağlamak için Firebase Authentication ile entegre olur. Bu, Firebase Authentication jetonunun iddialarına dayalı ayrıntılı erişim denetimi sağlar.

Kimliği doğrulanmış bir kullanıcı Cloud Storage adresine istek gönderdiğinde request.auth değişkeni, kullanıcının uid (request.auth.uid) değerinin yanı sıra Firebase Authentication JWT'sinin (request.auth.token) iddialarıyla doldurulur.

Ayrıca, özel kimlik doğrulama kullanılırken request.auth.token alanında ek iddialar gösterilir.

Kimliği doğrulanmamış bir kullanıcı istek gönderdiğinde request.auth değişkeni null olur.

Bu verileri kullanarak, dosyaları güvence altına almak için kimlik doğrulamayı kullanmanın birkaç yaygın yolu vardır:

  • Herkese açık: yoksay request.auth
  • Kimliği doğrulanmış gizli: request.auth değerinin null olmadığını kontrol edin
  • Kullanıcıya özel: request.auth.uid değerinin bir yol uid değerine eşit olup olmadığını kontrol edin
  • Grup gizli: Özel jetonun iddialarını, seçilen bir iddiayla eşleşip eşleşmediğini kontrol edin veya meta veri alanının olup olmadığını görmek için dosya meta verilerini okuyun

Herkese açık

request.auth bağlamını dikkate almayan tüm kurallar, kullanıcının kimlik doğrulama bağlamını dikkate almadığı için public kuralı olarak kabul edilebilir. Bu kurallar, oyun öğeleri, ses dosyaları veya diğer statik içerikler gibi herkese açık verileri göstermek için yararlı olabilir.

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

Kimlik doğrulaması yapılmış gizli

Belirli durumlarda, verilerin kimliği doğrulanmamış kullanıcılar tarafından değil, uygulamanızın kimliği doğrulanmış tüm kullanıcıları tarafından görüntülenebilmesini isteyebilirsiniz. Kimliği doğrulanmamış tüm kullanıcılar için request.auth değişkeni null olduğundan, kimlik doğrulamayı zorunlu kılmak için tek yapmanız gereken request.auth değişkeninin var olup olmadığını kontrol etmektir:

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

Kullanıcıya özel

request.auth için en yaygın kullanım alanı, bireysel kullanıcılara dosyalarında ayrıntılı izinler (ör. profil resimleri yükleme ve gizli dokümanları okuma) sağlamaktır.

Cloud Storage içindeki dosyaların tam bir "yolu" olduğundan, bir dosyanın kullanıcı tarafından kontrol edilmesi için gereken tek şey, dosya adı ön ekinde bulunan benzersiz, kullanıcıyı tanımlayan bir bilgidir (kullanıcı uid gibi). Bu bilgi, kural değerlendirilirken kontrol edilebilir:

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

Grup gizli

Yine yaygın bir kullanım alanı, bir nesnede grup izinlerine izin vermektir (ör. birkaç ekip üyesinin paylaşılan bir dokümanda ortak çalışmasına izin verme). Bunu yapmanın birkaç yolu vardır:

  • Grup üyeleriyle ilgili ek bilgileri (ör. grup kimliği) içeren bir Firebase Authentication özel jeton oluşturma
  • Grup bilgilerini (ör. grup kimliği veya yetkili uid'lerin listesi) dosya meta verilerine ekleyin.

Bu veriler jetonda veya dosya meta verilerinde depolandıktan sonra bir kuraldan referans verilebilir:

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

Değerlendirme İste

Yüklemeler, indirmeler, meta veri değişiklikleri ve silme işlemleri, Cloud Storage adresine gönderilen request kullanılarak değerlendirilir. request değişkeni, kullanıcının benzersiz kimliğine ve yukarıda açıklandığı gibi request.auth nesnesinde bulunan Firebase Authentication yüküne ek olarak, isteğin gerçekleştirildiği dosya yolunu, isteğin alındığı zamanı ve istek bir yazma işlemiyse yeni resource değerini içerir.

request nesnesi, kullanıcının benzersiz kimliğini ve request.auth nesnesinde Firebase Authentication yükü de içerir. Bu konu, dokümanların Kullanıcı Tabanlı Güvenlik bölümünde daha ayrıntılı olarak açıklanmaktadır.

request nesnesinde bulunan özelliklerin tam listesini aşağıda bulabilirsiniz:

Özellik Tür Açıklama
auth map<string, string> Kullanıcı oturum açtığında uid (kullanıcıya ait benzersiz kimlik) ve token (Firebase Authentication JWT iddialarının haritası) sağlar. Aksi takdirde null olur.
params map<string, string> İsteğin sorgu parametrelerini içeren harita.
path yol İsteğin yapıldığı yolu temsil eden bir path.
resource map<string, string> Yalnızca write isteklerinde bulunan yeni kaynak değeri.
time zaman damgası İsteğin değerlendirildiği sunucu zamanını temsil eden bir zaman damgası.

Kaynak Değerlendirmesi

Kuralları değerlendirirken yüklenen, indirilen, değiştirilen veya silinen dosyanın meta verilerini de değerlendirmek isteyebilirsiniz. Bu sayede, yalnızca belirli içerik türlerine sahip dosyaların yüklenmesine veya yalnızca belirli bir boyuttan büyük dosyaların silinmesine izin verme gibi işlemleri yapan karmaşık ve güçlü kurallar oluşturabilirsiniz.

Cloud Storage için Firebase Security Rules, resource nesnesinde dosya meta verilerini sağlar. Bu nesne, Cloud Storage nesnesinde gösterilen meta verilerin anahtar/değer çiftlerini içerir. Bu özellikler, veri bütünlüğünü sağlamak için read veya write isteklerinde denetlenebilmektedir.

write isteklerinde (yükleme, meta veri güncelleme ve silme gibi), istek yolunda mevcut olan dosyanın meta verilerini içeren resource nesnesine ek olarak, yazma işlemine izin verilirse yazılacak dosya meta verilerinin bir alt kümesini içeren request.resource nesnesini de kullanabilirsiniz. Veri bütünlüğünü sağlamak veya dosya türü ya da boyut gibi uygulama kısıtlamalarını uygulamak için bu iki değeri kullanabilirsiniz.

resource nesnesinde bulunan özelliklerin tam listesini aşağıda bulabilirsiniz:

Özellik Tür Açıklama
name dize Nesnenin tam adı
bucket dize Bu nesnenin bulunduğu paketin adı.
generation int Bu nesnenin Google Cloud Storage nesne nesli.
metageneration int Bu nesnenin Google Cloud Storage nesne meta oluşturma işlemi.
size int Nesnenin bayt cinsinden boyutu.
timeCreated zaman damgası Bir nesnenin oluşturulduğu zamanı gösteren zaman damgası.
updated zaman damgası Bir nesnenin en son güncellendiği zamanı gösteren zaman damgası.
md5Hash dize Nesnenin MD5 karma değeri.
crc32c dize Nesnenin crc32c karması.
etag dize Bu nesneyle ilişkili etag.
contentDisposition dize Bu nesneyle ilişkili içerik gönderme.
contentEncoding dize Bu nesneyle ilişkili içerik kodlaması.
contentLanguage dize Bu nesneyle ilişkili içerik dili.
contentType dize Bu nesneyle ilişkili içerik türü.
metadata map<string, string> Geliştirici tarafından belirtilen ek özel meta verilerin anahtar/değer çiftleri.

request.resource, generation, metageneration, etag, timeCreated ve updated hariç bunların tümünü içerir.

Cloud Firestore ile geliştirme

Diğer yetkilendirme ölçütlerini değerlendirmek için Cloud Firestore'teki belgelere erişebilirsiniz.

Güvenlik kurallarınızda firestore.get() ve firestore.exists() işlevlerini kullanarak gelen istekleri Cloud Firestore içindeki dokümanlarla karşılaştırabilirsiniz. Hem firestore.get() hem de firestore.exists() işlevleri, tamamen belirtilen belge yolları bekler. firestore.get() ve firestore.exists() için yollar oluşturmak üzere değişkenler kullanırken $(variable) söz dizimini kullanarak değişkenlerden açıkça kaçmanız gerekir.

Aşağıdaki örnekte, dosyalara okuma erişimini belirli kulüplerin üyeleriyle kısıtlayan bir kural görüyoruz.

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
    }
  }
}
Sonraki örnekte, kullanıcının fotoğraflarını yalnızca arkadaşları görebilir. 
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))
    }
  }
}

Bu Cloud Firestore işlevlerini kullanan ilk Cloud Storage Security Rules'inizi oluşturup kaydettikten sonra, Firebase konsolunda veya Firebase CLI'sinde iki ürünü bağlama izinlerini etkinleştirmeniz istenir.

Firebase Security Rules'i yönetme ve dağıtma bölümünde açıklandığı gibi bir IAM rolünü kaldırarak bu özelliği devre dışı bırakabilirsiniz.

Verileri doğrulama

Cloud Storage için Firebase Security Rules, dosya adının ve yolunun yanı sıra contentType ve size gibi dosya meta veri özelliklerinin doğrulanması da dahil olmak üzere veri doğrulama için de kullanılabilir.

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/.*');
    }
  }
}

Özel işlevler

Firebase Security Rules'ünüz daha karmaşık hale geldikçe koşul gruplarını kural kümenizde yeniden kullanabileceğiniz işlevlere sarmalamak isteyebilirsiniz. Güvenlik kuralları özel işlevleri destekler. Özel işlevlerin söz dizimi JavaScript'e biraz benzer ancak Firebase Security Rules işlevleri, bazı önemli sınırlamaları olan alana özgü bir dilde yazılır:

  • İşlevler yalnızca tek bir return ifadesi içerebilir. Bu işlevler ek mantık içeremez. Örneğin, döngü yürütemez veya harici hizmetleri çağıramaz.
  • İşlevler, tanımlandıkları kapsamdaki işlevlere ve değişkenlere otomatik olarak erişebilir. Örneğin, service firebase.storage kapsamında tanımlanan bir işlev, resource değişkenine ve yalnızca Cloud Firestore için get() ve exists() gibi yerleşik işlevlere erişebilir.
  • İşlevler diğer işlevleri çağırabilir ancak yineleme yapamaz. Toplam çağrı yığını derinliği 10 ile sınırlıdır.
  • rules2 sürümünde işlevler, let anahtar kelimesini kullanarak değişkenler tanımlayabilir. İşlevler herhangi bir sayıda let bağlaması içerebilir ancak return ifadesiyle bitmelidir.

İşlevler function anahtar kelimesiyle tanımlanır ve sıfır veya daha fazla bağımsız değişken alır. Örneğin, yukarıdaki örneklerde kullanılan iki koşul türünü tek bir işlevde birleştirmek isteyebilirsiniz:

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

Firebase Security Rules'ünüzde işlevler kullandığınızda, kurallarınızın karmaşıklığı arttıkça bu kuralları daha kolay yönetebilirsiniz.

Sonraki adımlar

Koşullarla ilgili bu tartışmadan sonra kurallar hakkında daha ayrıntılı bilgi sahibi oldunuz ve şunları yapmaya hazırsınız:

Temel kullanım alanlarını nasıl yöneteceğinizi ve kuralları geliştirme, test etme ve dağıtma iş akışını öğrenin: