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 işlevinin birincil yapı taşı koşul bağımsız değişkenidir. Koşul, belirli bir işleme izin verilmesi veya reddedilmesi gerektiğ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 taleplerine göre ayrıntılı erişim kontrolü 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 gizli: request.auth değerinin null olmadığından emin olun
  • Kullanıcı gizli: request.auth.uid değerinin uid yolu ile aynı olup olmadığını kontrol edin
  • Grup gizli: Özel jetonun iddialarını, seçilen 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

Aynı şekilde yaygın olarak kullanılan bir diğer kullanım alanı da birkaç ekip üyesinin paylaşılan bir belge üzerinde ortak çalışmasına olanak tanımak gibi bir nesne üzerinde grup izinlerine izin vermektir. Bunu yapmanın birkaç yolu vardır:

  • Bir grup üyesi hakkında ek bilgiler (grup kimliği gibi) içeren bir Firebase Authentication özel jetonu girin
  • 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 İsteme

Yüklemeler, indirmeler, meta veri değişiklikleri ve silme işlemleri, Cloud Storage hizmetine 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 eşleme<dize, dize> Bir kullanıcı giriş yaptığında uid, kullanıcının benzersiz kimliği ve Firebase Authentication JWT hak taleplerinin haritası olan token değerini sağlar. Aksi takdirde null olur.
params map<string, string> İsteğin sorgu parametrelerini içeren eşleme.
path yol İsteğin gerçekleştirildiği yolu temsil eden bir path.
resource map<string, string> Yeni kaynak değeri (yalnızca write isteklerinde bulunur).
time zaman damgası İsteğin değerlendirildiği sunucu zamanını temsil eden 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 nesnesindeki ö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ı Nesnenin oluşturulduğu zamanı temsil eden bir 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şkilendirilen içerik dili.
contentType dize Bu nesneyle ilişkili içerik türü.
metadata map<string, string> Geliştirici tarafından belirtilen ek 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 içindeki 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ştururken değişkenler kullanırken $(variable) söz dizimini kullanarak değişkenlerden açıkça çıkmanı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, iki ürünü bağlama izinlerini etkinleştirmek için Firebase konsolunda veya Firebase CLI'de sizden izin istenir.

Bu özelliği, Firebase Security Rules yönetme ve dağıtma bölümünde açıklandığı gibi bir IAM rolünü kaldırarak 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 izin bağlamasına sahip olabilir ancak bir döndürme ifadesiyle bitmelidir.

Bir işlev, 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: