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 diline nasıl koşul ekleyeceğinizi gösterir.

Cloud Storage Security Rules aracının temel yapı taşı koşuldur. Koşul, belirli bir işleme izin verilip verilmeyeceğini belirleyen bir boole ifadesidir. Temel kurallar için koşul olarak true ve false değişmezlerini kullanmak son derece uygundur. 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

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Cloud Storage data.

Doğrulama

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

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

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

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

Bu veriler kullanılarak, dosyaların güvenliğini sağlamak için kimlik doğrulamanın kullanıldığı birkaç yaygın yöntem vardır:

• Herkese açık: request.auth yoksayılıyor
• Kimliği doğrulanmış özel: request.auth değerinin null olmadığını kontrol edin
• Kullanıcıya özel: request.auth.uid değerinin uid yoluna eşit olup olmadığını kontrol edin
• Grup gizli: Özel jetonun hak taleplerini kontrol ederek seçilen bir hak talebiyle eşleşip eşleşmediğini kontrol edin veya dosya meta verilerini okuyarak bir meta veri alanının mevcut olup olmadığını kontrol edin.

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

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 mevcut 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ı, bireysel kullanıcılara dosyaları üzerinde ayrıntılı izinler sağlamaktır. Bu izinler, profil resimleri yüklemekten özel belgeleri okumaya kadar çeşitlilik gösterir.

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ı ön ekinde, kural değerlendirilirken kontrol edilebilecek benzersiz ve kullanıcıyı tanımlayan bir bilgi (ör. kullanıcının uid) bulunması 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;
}

Grup gizli

Bir diğer yaygın kullanım alanı da bir nesne üzerinde grup izinlerine izin vermektir. Örneğin, birkaç ekip üyesinin paylaşılan bir doküman üzerinde ortak çalışmasına izin vermek. Bunu yapmanın birkaç yolu vardır:

• Grup üyeleri hakkında ek bilgiler (ör. grup kimliği) içeren Firebase Authentication özel jeton oluşturma
• 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 isteğinde bulunma

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ği ve yukarıda açıklandığı gibi request.auth nesnesindeki 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 nesnesindeki Firebase Authentication yükünü de içerir. Bu konu, belgelerin 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 veren 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 incelenebilir.

write isteklerinde (yüklemeler, meta veri güncellemeleri ve silme işlemleri gibi), 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ç bunların tümünü içerir.

Cloud Firestore ile iyileştirin

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

firestore.get() ve firestore.exists() işlevlerini kullanarak güvenlik kurallarınız, gelen istekleri Cloud Firestore içindeki belgelere göre değerlendirebilir. firestore.get() ve firestore.exists() işlevleri, tam olarak belirtilmiş belge yolları bekler. firestore.get() ve firestore.exists() için yol oluşturmak üzere değişkenleri kullanırken $(variable) söz dizimini kullanarak değişkenleri açıkça kodlamanız gerekir.

Aşağıdaki örnekte, dosyalara okuma erişimini belirli kulüplerin üyesi olan kullanıcılarla 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)).data.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şlevlerini kullanan ilk Cloud Storage Security Rules öğenizi oluşturup kaydettikten sonra Firebase konsolunda veya Firebase CLI'da iki ürünü bağlama izinlerini etkinleştirmeniz istenir.

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

Verileri doğrulama

Cloud Storage için Firebase Security Rules, dosya adı ve yolunun yanı sıra contentType ve size gibi dosya meta veri özelliklerini doğrulamak 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 daha karmaşık hale geldikçe koşul gruplarını, kural grubunuzda yeniden kullanabileceğiniz işlevlere sarmak isteyebilirsiniz. Güvenlik kuralları, özel işlevleri destekler. Özel işlevlerin söz dizimi 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 bir mantık içeremezler. Ö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 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şkenleri tanımlayabilir. İşlevler, dilediğiniz sayıda let bağlaması içerebilir ancak bir dönüş 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 içinde işlevleri kullanmak, kurallarınızın karmaşıklığı arttıkça kurallarınızı daha kolay yönetmenizi sağlar.

Sonraki adımlar

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

Temel kullanım alanlarını nasıl ele alacağınızı ve kural 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 edip bunlardan kaçınmanız gereken durumları inceleyerek bilgilerinizi pekiştirin.
• Cloud Storage emülatörünü ve özel Güvenlik Kuralları test kitaplığını kullanarak kuralları test edin.
• Security Rules dağıtımı için kullanılabilen yöntemleri inceleyin.