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

Bu kılavuz, Cloud Storage için Firebase Güvenlik Kurallarınıza nasıl koşul ekleyeceğinizi göstermek üzere Firebase Güvenlik Kuralları dilinin temel söz dizimini öğrenme rehberine dayanmaktadır.

Cloud Storage Güvenlik Kurallarının birincil yapı taşı koşul'dur. Koşul, belirli bir işleme izin verilmesi veya reddedilmesi gerektiğini belirleyen bir boole ifadesidir. Temel kurallarda koşullar çok iyi çalıştığı için true ve false değişmez değerlerini kullanmak. Ancak Firebase Security Rules for Cloud Storage dili, aşağıdaki işlemleri gerçekleştirebilecek daha karmaşık koşullar yazmanızı sağlar:

  • Kullanıcı kimlik doğrulamasını kontrol edin
  • Gelen verileri doğrulayın

Doğrulama

Cloud Storage için Firebase Güvenlik Kuralları, Cloud Storage için güçlü kullanıcı tabanlı kimlik doğrulama sağlamak amacıyla 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'a karşı bir istek gerçekleştirdiğinde request.auth değişkeni, kullanıcının uid (request.auth.uid) ve Firebase Authentication JWT (request.auth.token) iddialarıyla doldurulur.

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

Kimliği doğrulanmamış bir kullanıcı istek gerçekleştirdiğinde request.auth değişkeni null olur.

Bu veriler kullanılarak, dosyaların güvenliğini sağlamak için kimlik doğrulamayı kullanmanın yaygın olarak kullanılan birkaç yolu vardır:

  • Herkese açık: request.auth adlı kullanıcıyı yoksay
  • 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, seçilen bir taleple eşleşme taleplerini kontrol edin veya bir meta veri alanı olup olmadığını görmek için dosya meta verilerini okuyun

Herkese açık

Kullanıcının kimlik doğrulama bağlamını dikkate almadığı için request.auth bağlamını hesaba katılmayan tüm kurallar public kuralı olarak kabul edilebilir. Bu kurallar; oyun öğeleri, ses dosyaları veya diğer statik içerikler gibi herkese açık verilerin gösterilmesi 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");
}

Kimliği doğrulanmış gizli

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

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

Kullanıcıya gizli

request.auth için en yaygın kullanım alanı, tek tek kullanıcılara dosyalarıyla ilgili ayrıntılı izinler vermek olacaktır: profil resmi yüklemekten gizli dokümanları okumaya kadar.

Cloud Storage'daki dosyalar, dosyaya giden tam bir"yol" içerdiğinden, bir dosyanın kullanıcı tarafından kontrol edilmesini sağlamak için gereken tek şey, kural değerlendirildiğinde kontrol edilebilen, dosya adı önekindeki (kullanıcının uid kodu gibi) benzersiz, kullanıcıyı tanımlayan bir bilgidir:

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

Grubu 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 yapmak için çeşitli yaklaşımlar vardır:

  • Grup üyesi hakkında ek bilgiler (grup kimliği gibi) içeren bir Firebase Authentication özel jetonu oluşturun
  • Dosya meta verilerine grup bilgilerini (grup kimliği veya yetkili uid listesi gibi) ekleyin

Bu verilere jeton veya dosya meta verilerinde depolandıktan sonra bir kural içinden verilere 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ükleme, indirme, meta veri değişiklikleri ve silme işlemleri, Cloud Storage'a gönderilen request kullanılarak değerlendirilir. Yukarıda açıklandığı gibi request.auth nesnesindeki kullanıcının benzersiz kimliği ve Firebase Authentication yüküne ek olarak request değişkeni, isteğin gerçekleştirildiği dosya yolunu, isteğin alındığı zamanı ve istek yazma işlemiyse yeni resource değerini içerir.

request nesnesi aynı zamanda kullanıcının benzersiz kimliğini ve request.auth nesnesindeki Firebase Authentication yükünü de içerir. Bu veri, belgelerin Kullanıcı Tabanlı Güvenlik bölümünde daha ayrıntılı bir şekilde açıklanacaktır.

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

Özellik Tür Açıklama
auth eşleme<dize, dize> Kullanıcı giriş yaptığında uid adlı kullanıcının benzersiz kimliğini ve Firebase Authentication JWT hak taleplerinin eşlemesini sağlayan token değerini sağlar. Aksi takdirde, null olacaktır.
params eşleme<dize, dize> İsteğin sorgu parametrelerini içeren eşleme.
path yol İsteğin gerçekleştirildiği yolu temsil eden bir path.
resource eşleme<dize, dize> 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ğerlendirme

Kuralları değerlendirirken yüklenen, indirilen, değiştirilen veya silinen dosyanın meta verilerini de değerlendirmek isteyebilirsiniz. Bu, yalnızca belirli içerik türlerine sahip dosyaların yüklenmesine izin verme veya yalnızca belirli bir boyutun üzerindeki dosyaların silinmesine izin verme gibi işlemler yapan karmaşık ve güçlü kurallar oluşturmanıza olanak tanır.

Cloud Storage için Firebase Güvenlik Kuralları, dosya meta verilerini resource nesnesinde sağlar. Bu nesne, Cloud Storage nesnesinde bulunan meta verilerin anahtar/değer çiftlerini içerir. Veri bütünlüğünü sağlamak için bu özellikler read veya write isteklerinde incelenebilir.

write isteklerinde (yüklemeler, meta veri güncellemeleri ve silmeler gibi), istek yolunda mevcut olan dosyanın meta verilerini içeren resource nesnesine ek olarak, request.resource nesnesini de kullanabilirsiniz. Bu nesne, yazmaya izin verildiği takdirde yazılacak dosya meta verilerinin bir alt kümesini içerir. Veri bütünlüğünü sağlamak veya dosya türü ya da boyutu gibi uygulama kısıtlamaları 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 oluşturma işlemi.
metageneration int Bu nesnenin Google Cloud Storage nesne meta oluşturması.
size int Nesnenin bayt cinsinden boyutu.
timeCreated zaman damgası Nesnenin oluşturulduğu zamanı temsil eden bir zaman damgası.
updated zaman damgası Nesnenin en son ne zaman güncellendiğini gösteren bir zaman damgası.
md5Hash dize Nesnenin MD5 karması.
crc32c dize Nesnenin crc32c karması.
etag dize Bu nesneyle ilişkilendirilen etag.
contentDisposition dize Bu nesneyle ilişkilendirilen içerik yapısı.
contentEncoding dize Bu nesneyle ilişkilendirilen içerik kodlaması.
contentLanguage dize Bu nesneyle ilişkilendirilen içerik dili.
contentType dize Bu nesneyle ilişkilendirilen içerik türü.
metadata eşleme<dize, dize> 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ştirin

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

firestore.get() ve firestore.exists() işlevlerini kullanarak güvenlik kurallarınız, gelen istekleri Cloud Firestore'daki belgelerle karşılaştırarak değerlendirebilir. firestore.get() ve firestore.exists() işlevlerinin her ikisi de tam olarak belirtilmiş belge yolları bekler. firestore.get() ve firestore.exists() için yollar oluşturmak amacıyla 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 üyesi olan kullanıcılarla kısıtlayan bir kural gösterilmektedir.

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 kullanıcının 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 Güvenlik Kurallarınızı oluşturup kaydettikten sonra, Firebase konsolunda veya Firebase CLI'da iki ürünü bağlamak için izinleri etkinleştirmeniz istenir.

Bu özelliği, Firebase Güvenlik Kurallarını yönetme ve dağıtma başlıklı makalede açıklandığı şekilde bir IAM rolünü kaldırarak devre dışı bırakabilirsiniz.

Verileri doğrulama

Cloud Storage için Firebase Güvenlik Kuralları, dosya adı ve yolunun yanı sıra contentType ve size gibi dosya meta veri özelliklerini doğrulamak 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 Güvenlik Kurallarınız daha karmaşık hale geldikçe, kural grubunuzda yeniden kullanabileceğiniz işlevlerde koşul gruplarını sarmalamak isteyebilirsiniz. Güvenlik kuralları, özel işlevleri destekler. Özel işlevlerin söz dizimi biraz JavaScript'e benzer ancak Firebase Güvenlik Kuralları işlevleri, bazı önemli sınırlamaları olan, alana özgü bir dilde yazılmıştır:

  • İşlevler yalnızca tek bir return ifadesi içerebilir. Ek mantık içeremez. Örneğin döngüleri yürütemez veya harici hizmetleri çağıramazlar.
  • İş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'da get() ve exists() gibi yerleşik işlevlere erişebilir.
  • İşlevler diğer işlevleri çağırabilir ancak yinelenmeyebilir. Toplam çağrı grubu derinliği 10 ile sınırlıdır.
  • rules2 sürümünde, işlevler let anahtar kelimesini kullanarak değişkenleri tanımlayabilir. İşlevler herhangi bir sayıda izin bağlamasına sahip olabilir ancak bir dönüş 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 Güvenlik Kurallarınızdaki işlevleri kullanmak, kurallarınızın karmaşıklığı arttıkça bunları daha sürdürülebilir hale getirir.

Sonraki adımlar

Koşulları ele aldıktan sonra, artık Kurallar'ı daha iyi anlamış oldunuz ve artık:

Temel kullanım alanlarını nasıl ele alacağınızı öğrenin ve Kural geliştirme, test etme ve dağıtma iş akışını öğrenin: