Geçen hafta bir ekiple oturdum, ellerinde düzgün sayılabilecek bir .NET API vardı, Azure’a deploy etmişlerdi, lokalde de gayet sakin çalışıyordu. Tek dertleri şuydu: Cosmos DB’ye bağlanırken hâlâ connection string’i App Settings’e gömüyorlardı. “Aşkın hocam, yıllardır böyle yapıyoruz, ne olacak ki?” dediler.
📋 İçindekiler
Olan şu: Bir gün biri repo’ya o connection string’i yanlışlıkla commit’liyor. Ya da bir junior dev local.settings.json’ı paylaşıyor. Sonrası malum. Kısa versiyon bu.
İşin aslı şu ki, Cosmos DB tarafında key tabanlı kimlik doğrulama dönemi çoktan geride kalmış olmalıydı. Microsoft yıllardır managed identity ve RBAC tarafını toparlıyor, iyice de olgunlaştırıyor. Ama sahada hâlâ %70 civarı key kullanıldığını görüyorum; şaşırdım açıkçası. Bu yazıda — lafı dolandırmadan — uygulamanızın Cosmos DB’ye nasıl, hangi rolle, hangi kimlikle bağlanması gerektiğini anlatacağım.
Önce Kafa Karıştıran O Ayrımı Netleştirelim
Ne yalan söyleyeyim, Cosmos DB’nın iki ayrı izin sistemi var, işte mesele burada başlıyor. Bunu anlamadan yola çıkarsanız rol atarken neden çalışmadığını saatlerce kurcalarsınız; ben ilk başladığımda bu tuzağa düşmüştüm, sonra aynı kafa karışıklığını çok ekipte daha gördüm. Neyse uzatmayalım.
Çok konuştum, örnekle göstereyim.
Bakın şöyle:
| Özellik | Control Plane | Data Plane |
|---|---|---|
| Ne yönetir? | Hesap yönetimi: DB/container oluşturma, throughput değiştirme, anahtar okuma, network ayarları | Asıl veri: doküman okuma/yazma, sorgular, stored procedure çalıştırma |
| Roller nerede? | Azure RBAC (standart Microsoft.Authorization rolleri) | Cosmos DB’nın kendi data plane RBAC sistemi |
| Örnek rol | Cosmos DB Account Reader, Contributor | Cosmos DB Built-in Data Reader, Data Contributor |
Şimdi en sık gördüğüm hata şu: Birisi geliyor, “Ben uygulamama Contributor rolü verdim ama doküman okuyamıyor” diyor. Çünkü Contributor dediğiniz şey control plane rolü; hesap üzerinde işlem yaptırıyor ama veriye dokundurmuyor. Tam tersi de geçerli: Data (belki yanılıyorum ama) Contributor verirseniz bu kez kullanıcı throughput değiştiremez. Garip gibi duruyor ama öyle.
İki sistem birbirinden bağımsız. Portal’dan Cosmos DB’nın “Access Control (IAM)” sekmesinde rol verirken control plane rolleri görürsünüz. Data plane rolleri işe sadece CLI veya ARM/Bicep ile atanabilir. Bu da Microsoft’un bilinçli tasarımı; yetkisiz birinin yanlışlıkla veri yetkisi vermesini istemiyorlar.
Üç Soru Sorun Kendinize
Erişim mimarisi kurarken kafamda hep üç soru olur:
- Kim erişim istiyor? (uygulamanızın kimliği)
- Ne yapabilecek? (rol)
- Nerede geçerli? (kapsam — account, database ya da container seviyesi)
Bak şimdi, Bunlar oturunca gerisi baya mekanik ilerliyor. Şimdi tek tek gidelim; çünkü işin tadı orada çıkıyor.
1. Kim: Managed Identity (gerçekten başka yere bakmayın)
Uygulamanızın Azure’ın tanıdığı bir kimliği olmalı. Pratikte iki seçenek var:
Managed Identity: Azure sizin için credential işini yönetiyor. Secret yok, rotasyon yok, config dosyasında saklanacak bir şey yok; kulağa fazla temiz geliyor ama işe yarıyor işte. Mantıklı değil mi? App Service, Functions, Container Apps, AKS veya VM üzerinde çalışıyorsanız bunu kullanın.
Service Principal: Manuel kaydedilen bir app identity; client secret ya da sertifika ile yürür. Bunu sadece managed identity’nın mümkün olmadığı yerlerde kullanın (Azure dışı kodlar, on-prem entegrasyonu falan). Yani mecbursanız.
az webapp identity assign \
--name my-app \
--resource-group my-rg
Aslında, Komutun döndürdüğü principalId değerini bir kenara not edin. Rol atamasındaki “kim” tam olarak bu oluyor.
2. Ne: Built-in Veri Rolleri
Tekerleği yeniden icat etmeyin derim. Cosmos DB iki tane hazır data plane rolü sunuyor. Uygulamaların belki %95’i bunlarla rahatça çıkıyor; fazlasına çoğu zaman gerek bile kalmıyor:
| Rol | ID | Yetkiler |
|---|---|---|
| Cosmos DB Built-in Data Reader | 00000000-0000-0000-0000-000000000001 | Doküman okuma, sorgu çalıştırma, change feed okuma |
| Cosmos DB Built-in Data Contributor | 00000000-0000-0000-0000-000000000002 | Data Reader yetkileri + create, replace, upsert, delete |
Veri yazan uygulamalar Data Contributor ister. Sadece okuyan bir raporlama servisi ya da cache ısıtma job’ı için Data Reader yeterli. Burada altın kural: uygulamaya işini görecek en dar rolü verin.
3. Nerede: Kapsam (Scope)
Rol atamasını üç seviyede yapabilirsiniz:
- Account seviyesi (
/): hesaptaki tüm veritabanları ve container’lar. - Database seviyesi (
/dbs/ordersdb): tek bir veritabanı. - Container seviyesi (
/dbs/ordersdb/colls/orders): tek bir container.
Container seviyesine inmek en dar, dolayısıyla en güvenli seçeneklerden biri. Account geneli yetki vermek isterseniz scope’u / yaparsınız, ama açık konuşayım, ben bunu prod’da mümkün olduğunca kaçınırım. Bu noktada iyi olan şey şu: “least privilege” kuralını bozmadığınız sürece geri kalan her şey yoluna giriyor.
Kodda Nasıl Görünüyor?
SDK tarafında değişiklik küçük gibi duruyor, ama etkisi büyük oluyor. DefaultAzureCredential‘a geçiyorsunuz, connection string işi kapanıyor:
// C# — Azure.Identity ve Microsoft.Azure.Cosmos paketleri
var credential = new DefaultAzureCredential();
var client = new CosmosClient(
accountEndpoint: "https://my-cosmos-account.documents.azure.com:443/",
tokenCredential: credential
);
var container = client.GetContainer("ordersdb", "orders");
await container.CreateItemAsync(newOrder);
“Hepsi bu” demek kolay geliyor ama burada güzel olan şey lokal ile prod arasındaki farkın neredeyse kaybolması. Lokalde geliştirirken DefaultAzureCredential sizin Azure CLI oturumunuzu kullanır, deploy ettiğinizde ise Azure’daki managed identity’yi otomatik yakalar. Aynı kod, sıfır config farkı. Eskiden bunun için ayrı yol yazmak gerekiyordu; şimdi gerek kalmıyor. Fena değil.
Türkiye’deki Kurumlar İçin Pratik Notlar
Sahada gözlemlediğim kadarıyla Türkiye’deki finans ve telekom tarafı RBAC adaptasyonunda biraz ağır gidiyor. Sebep teknik değil, daha çok alışkanlık meselesi. Geliştirici ekipler “key ile çalışıyordu zaten” diyor, güvenlik ekipleri “anahtar rotasyonu yapıyoruz, yeterli” diyor. Oysa gerçek biraz sert: anahtar rotasyonu manuel ve maliyetli bir iş. Managed identity ile bu dert ciddi biçimde azalıyor.
Kurumsal müşterilerin sık takıldığı başka bir nokta daha var: custom rol yok sanıyorlar. Aslında var. Built-in iki rol işinizi görmüyorsa (mesela “yazsın ama silmesin” gibi ince senaryolar), kendi rolünüzü tanımlayabiliyorsunuz. JSON ile role definition oluşturup atıyorsunuz. Şöyle düşünün:
{
"RoleName": "OrderWriterNoDelete",
"Type": "CustomRole",
"AssignableScopes": ["/"],
"Permissions": [{
"DataActions": [
"Microsoft.DocumentDB/databaseAccounts/readMetadata",
"Microsoft.DocumentDB/.../items/create",
"Microsoft.DocumentDB/.../items/read",
"Microsoft.DocumentDB/.../items/replace"
]
}]
}
Bu yaklaşım özellikle PCI-DSS veya KVKK kapsamındaki uygulamalarda işe yarıyor. Audit ekibi geldiğinde “biz sadece bu işlemlere izin veriyoruz” demek, “Contributor verdik” demekten epey farklı duruyor.
Küçük Ekip misiniz, Enterprise mı?
2-3 servisli bir mimariye sahip küçük bir ekipseniz system-assigned managed identity + Data Contributor + database seviyesinde scope mantıklı bir başlangıç.
Enterprise tarafındaysanız hikaye biraz değişiyor: user-assigned managed identity tercih edin (birden fazla servis aynı kimliği paylaşabilsin), custom roller tanımlayın, scope’u mutlaka container seviyesine indirin ve hepsini Bicep/Terraform ile IaC altında yönetin. Manuel birkaç CLI komutu dışında elle işlem bırakmayın; denetlenebilirlik için bu önemli.
Sık Yapılan Hatalar ve Çözümleri
Bu konuda en sık karşılaştığım sorunlar şunlar:
- “Forbidden” hatası alıyorum: %90 ihtimalle yanlış rolü atamışsınızdır.
- Lokalde çalışıyor, Azure’da çalışmıyor: Managed identity Azure’da açılmamış olabilir.
az webapp identity showile kontrol edin. - readMetadata yetkisi unutuluyor: Custom rol yazarken bu permission’ı eklemezseniz SDK ilk bağlantıda hata verir.
- Rol ataması “anında” çalışmıyor: 5 dakika bekleyin. Token cache’in yenilenmesi lazım.
Operasyonel veride agent kullanımı arayanlar için Deep Agents + Cosmos DB: Operasyonel Veride Plan-Eylem-Doğrulama yazısına da göz atabilirsiniz. Java tarafında vektör araması üzerine çalışıyorsanız Spring AI 2.0 GA: Cosmos DB ile Java Tarafında Vektör Devri faydalı olur.
Maliyet Tarafı: RBAC Bedava mı?
Evet, RBAC kullanmak ekstra ücret getirmiyor. Cosmos DB tarafında RU bazlı faturalandırma değişmiyor. Ama Entra ID (eski adıyla Azure AD) tarafında token alma işlemi var ve bunun network latency olarak küçük bir maliyeti oluyor. SDK token’ı zaten cache’lediği için gerçek dünyada ölçülebilir büyük bir fark çıkarmıyor.
Asıl “maliyet” kazancı başka yerde: Bir secret leak vakası yaşadığınızda anahtar rotasyonu için harcayacağınız mühendislik saatleri ve downtime riski azalıyor. Orta ölçekli bir kurumda bunun faturası rahatlıkla 200-300 saate çıkabiliyor. Managed identity ile risk ciddi biçimde düşüyor.
Key Tabanlı Erişimden Geçiş: Üç Adım
Şu an key ile çalışıyorsanız ve geçiş yapmak istiyorsanız ilk adımlar şunlar:
- Envanter çıkarın: Hangi uygulama, hangi Cosmos hesabına, hangi yetkilerle bağlanıyor? Bu listeyi yapmadan başlamayın.
- Önce non-prod’da deneyin: Dev veya staging ortamında managed identity + Data Contributor ile test edin. SDK versiyonunuzun güncel olduğundan emin olun (.NET için Microsoft.Azure.Cosmos 3.32+ tavsiye edilir).
- Paralel çalıştırıp sonra key’i çekin: Bir süre hem RBAC hem key aktif kalsın. Loglarda hata görmediğinizden emin olduktan sonra key authentication’ı Cosmos hesabı seviyesinde devre dışı bırakın (
disableLocalAuth: true).
Sıkça Sorulan Sorular
Managed identity ile bağlanınca connection string’i tamamen silebilir miyim?
Araya gireyim: Evet, silebilirsin. SDK’ya sadece account endpoint URL’ini (https://...documents.azure.com:443/) ve TokenCredential nesnesini vermen yeterli, yani key’e hiç gerek kalmıyor. Hatta bir adım daha ileri gidip Cosmos hesabında disableLocalAuth ayarını açarsan key kullanımını tamamen yasaklayabilirsin. Bence bu en temiz yol.
System-assigned ile user-assigned managed identity arasındaki fark ne?
System-assigned, hani tek bir kaynağa (mesela tek bir App Service’e) bağlı olan türdür — o kaynak silinince o da gidiyor. User-assigned ise bağımsız bir kaynak olarak duruyor ve birden fazla servis aynı identity’yi paylaşabiliyor. Açıkçası, birden fazla uygulamanın aynı veriye erişmesi gerekiyorsa user-assigned çok daha pratik.
Data plane rolünü portal’dan atayamıyor muyum?
Bakın, Atayamıyorsun, maalesef. Şu an için Azure CLI, PowerShell, ARM template ya da Bicep kullanman gerekiyor. Aslında bu Microsoft’un bilinçli bir güvenlik kararı — yanlışlıkla geniş veri erişimi vermemek için böyle tasarlamışlar.
Custom rol oluşturmak gerçekten gerekli mi?
Çoğu durumda hayır. Built-in Data Reader ve Data Contributor rolleri uygulamaların %95’ini karşılıyor. Custom rolü ancak çok özel bir kısıtlamaya ihtiyacın varsa düşün, mesela “sadece okuma + güncelleme, ama silme yok” gibi bir senaryoda. Tecrübeme göre gereksiz yere custom rol açmak sadece karmaşıklık ekliyor.
RBAC kullanmak performansı etkiler mi?
Pratikte etkilemiyor. SDK aldığı access token’ı cache’liyor ve süresi dolana kadar tekrar istek atmıyor. Siz ne dersiniz? Aslında sadece ilk bağlantıda birkaç yüz milisaniyelik bir token alma maliyeti oluyor, ondan sonrası key kullanımıyla aynı performansta devam ediyor.
Kaynaklar ve İleri Okuma
Which Azure Cosmos DB Role Does My App Need? (Orijinal makale — Microsoft DevBlogs)
Configure role-based access control with Microsoft Entra ID for Azure Cosmos DB (Microsoft Learn)
Yani, Managed Identities for Azure Resources Overview (Microsoft Learn)
Azure Identity client library for .NET
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için YouTube ve GitHub hesaplarımı takip edin.





Cosmos DB’de data plane vs control plane ayrımını hep kafam karışıyordu, en azından key tabanlı kimlik doğrulamanın neden riskli olduğu kısmı artık daha net. Peki Managed Identity kullanımına da değindiniz mi yazıda, onu merak ettim aslında.
Cosmos DB’ye geçişte role-based access konusunda epey vakit harcamıştım, key tabanlı kimlik doğrulamanın risklerini genelde hafife alıyoruz ama production ortamında ciddi sorun çıkarabiliyor. Data plane izinlerini Azure RBAC ile karıştırmak da çok yaygın bir hata, güzel özetlemişsiniz.
Cosmos DB’de data plane ile control plane arasındaki farkı tam kavramak zaman almıştı benim için. Key tabanlı kimlik doğrulamanın risklerini daha önce görmezden geliyordum ama production ortamında başımız bir kez yandıktan sonra managed identity’ye geçtik ve pişman olmadık.