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

Bu kılavuz, Firebase Security Rules dilinin temel söz dizimini öğrenme kılavuzunu temel alarak Cloud Storage için Firebase Security Rules kodunuza koşulları nasıl ekleyeceğinizi gösterir.

Cloud Storage Security Rules'nın temel yapı taşı koşuldur. Koşul, belirli bir işlemin izin verilip verilmeyeceğini belirleyen bir boole ifadesidir. Temel kurallar için koşul olarak true ve false değişmezlerini kullanmak mükemmel bir şekilde işe yarar. Ancak Cloud Storage dili için Firebase Security Rules, aşağıdakileri yapabilen daha karmaşık koşullar yazmanıza olanak tanır:

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

Doğrulama

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

Kimliği doğrulanmış bir kullanıcı Cloud Storage ile ilgili bir istekte bulunduğunda request.auth değişkeni, kullanıcının uid (request.auth.uid) ile Firebase Authentication JWT'nin (request.auth.token) talepleriyle doldurulur.

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

Kimliği doğrulanmamış bir kullanıcı istekte bulunduğunda request.auth değişkeni null olur.

Bu verileri kullanarak dosyaları güvenli hale getirmek için kimlik doğrulama işlemini kullanmanın yaygın olarak kullanılan birkaç yolu vardır:

• Herkese açık: yoksay request.auth
• Kimliği doğrulanmış özel: request.auth değerinin null olmadığını kontrol edin.
• User private: request.auth.uid değerinin bir yola uid eşit olup olmadığını kontrol edin.
• Gruba özel: Özel jetonun taleplerini kontrol ederek seçilen bir taleple eşleşip eşleşmediğini doğrulayın veya bir meta veri alanının mevcut 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 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ış özel

Bazı durumlarda, verilerin uygulamanızın kimliği doğrulanmış tüm kullanıcıları tarafından görüntülenebilmesini ancak kimliği doğrulanmamış kullanıcılar tarafından görüntülenememesini isteyebilirsiniz. request.auth değişkeni, kimliği doğrulanmamış tüm kullanıcılar için null olduğundan kimlik doğrulama gerektirmek için request.auth değişkeninin var olup olmadığını kontrol etmeniz yeterlidir:

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

Kullanıcı özel

request.auth için en yaygın kullanım alanı, kullanıcılara dosyalarıyla ilgili ayrıntılı izinler vermek olacaktır. Bu izinler, profil resmi yüklemekten özel belgeleri okumaya kadar değişebilir.

Cloud Storage içindeki dosyaların tam "yolu" olduğundan, bir dosyanın kullanıcı tarafından kontrol edilmesini sağlamak için dosya adı önekinde (ör. kullanıcının uid) kural değerlendirilirken kontrol edilebilecek benzersiz, kullanıcıyı tanımlayan bir bilgi yeterlidir:

// 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 yapma

Bir nesnede grup izinlerine izin vermek de aynı derecede yaygın bir kullanım alanıdır. Örneğin, birkaç ekip üyesinin paylaşılan bir doküman üzerinde birlikte çalışmasına izin verilebilir. Bunu yapmanın birkaç yolu vardır:

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

Bu veriler jeton 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ği

Yüklemeler, indirmeler, meta veri değişiklikleri ve silme işlemleri, Cloud Storage adresine gönderilen request kullanılarak değerlendirilir. Kullanıcının benzersiz kimliğine ve yukarıda açıklandığı gibi request.auth nesnesindeki 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 bir yazma işlemiyse yeni resource değerini içerir.

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

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

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şlemler yapan karmaşık ve güçlü kurallar oluşturabilirsiniz.

Firebase Security Rules için Cloud Storage, 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 incelenebilir.

write isteklerinde (ör. yüklemeler, meta veri güncellemeleri ve silme işlemleri), istek yolunda mevcut olan dosyanın dosya 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 boyutu gibi uygulama kısıtlamalarını zorunlu kılmak için bu iki değeri kullanabilirsiniz.

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

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

Cloud Firestore ile geliştirme

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

firestore.get() ve firestore.exists() işlevlerini kullanarak güvenlik kurallarınız, gelen istekleri Cloud Firestore içindeki dokümanlara göre değerlendirebilir. firestore.get() ve firestore.exists() işlevleri, tamamen belirtilmiş belge yolları bekler. firestore.get() ve firestore.exists() için yollar oluşturmak üzere değişkenleri kullanırken $(variable) söz dizimini kullanarak değişkenlerden çıkmanız gerekir.

Aşağıdaki örnekte, dosyalara okuma erişimini belirli kulüplerin üyeleriyle 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
    }
  }
}

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şlevleri kullanan ilk Cloud Storage Security Rules öğenizi oluşturup kaydettikten sonra, Firebase konsolunda veya Firebase KSA'da iki ürünü bağlamak için izinleri etkinleştirmeniz istenir.

Bu özelliği, Yönetme ve dağıtmaFirebase Security Rules bölümünde açıklandığı gibi bir IAM rolünü kaldırarak devre dışı bırakabilirsiniz.

Verileri doğrulama

Firebase Security Rules Cloud Storage için, dosya adı ve yolunun yanı sıra contentType ve size gibi dosya meta veri özelliklerinin doğrulanması da dahil olmak üzere veri doğrulaması 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 daha karmaşık hale geldikçe koşul kümelerini, kurallarınızda yeniden kullanabileceğiniz işlevlere sarmak isteyebilirsiniz. Güvenlik kuralları özel işlevleri destekler. Özel işlevlerin söz dizimi biraz JavaScript'e 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. Başka mantık içermemelidir. Ö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ı içinde 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 yinelemeli olarak çağrılamaz. 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şkenleri tanımlayabilir. İşlevler herhangi bir sayıda let bağlaması içerebilir ancak bir return ifadesiyle sona ermelidir.

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 içinde işlevleri kullanmak, kurallarınızın karmaşıklığı arttıkça bu kuralların bakımını kolaylaştırır.

Sonraki adımlar

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

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

• Sık karşılaşılan senaryoları ele alan kurallar yazın.
• Güvenli olmayan kuralları tespit etmeniz ve bunlardan kaçınmanız gereken durumları inceleyerek bilginizi artırın.
• Cloud Storage emülatörünü ve özel Güvenlik Kuralları test kitaplığını kullanarak kuralları test edin.
• DağıtımRules için kullanılabilen yöntemleri inceleyin.