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 öğesine nasıl koşul ekleneceğini gösterir.

Cloud Storage Security Rules'nın temel yapı taşı koşuldur. Bir 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 yeterlidir. Ancak Cloud Storage dilindeki 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

Firebase Security Rules, Cloud Storage için Firebase Authentication ile entegre olarak Cloud Storage'ye 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 ile ilgili bir istekte bulunduğunda request.auth değişkeni, kullanıcının uid (request.auth.uid) ile Firebase Authentication JWT'sinin (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 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: yoksay request.auth
• Kimliği doğrulanmış özel: request.auth değerinin null olmadığını kontrol edin.
• Kullanıcı özel: request.auth.uid değerinin bir yola uid eşit olup olmadığını kontrol edin.
• Grup ö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 çeşitli yolları vardır:

• Bir grup üyesi hakkında ek bilgiler (ör. grup kimliği) içeren bir Firebase Authentication özel jeton oluşturma
• Dosya meta verilerine grup bilgilerini (ör. grup kimliği veya yetkili uid'lerin 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

Yüklemeler, indirmeler, meta veri değişiklikleri ve silme işlemleri, Cloud Storage adresine gönderilen request kullanılarak değerlendirilir. Yukarıda açıklandığı gibi, kullanıcının benzersiz kimliğine ve 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.

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. Veri bütünlüğünü sağlamak için bu özellikler read veya write isteklerinde incelenebilir.

write isteklerinde (ör. yüklemeler, meta veri güncellemeleri ve silmeler), 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 iyileş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şlevlerinin her ikisi de tam olarak 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ö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şlevleri kullanan ilk Cloud Storage Security Rules öğenizi oluşturup kaydettikten sonra, Firebase konsolunda veya Firebase CLI'da iki ürünü bağlamak için izinleri etkinleştirmeniz istenir.

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

Verileri doğrulama

Firebase Security Rules Cloud Storage için, dosya adını ve yolunu doğrulamanın yanı sıra contentType ve size gibi dosya meta veri özelliklerini doğrulama 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 kümelerini, kural kümenizde yeniden kullanabileceğiniz işlevlere sarmak 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. 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 olamaz. 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. İşlevlerde herhangi bir sayıda let bağlaması olabilir ancak işlevler 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şlevlerini kullanmak, kurallarınızın karmaşıklığı arttıkça bu kuralların daha kolay sürdürülmesini sağlar.

Sonraki adımlar

Koşullarla ilgili bu tartışmanın ardından, kurallar hakkında daha ayrıntılı bilgi edindiniz ve artık ş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ımSecurity Rules için kullanılabilen yöntemleri inceleyin.