Neden yerel bir C# IIS arka plan işçisi geliştirdik

Her sertifika otomasyonu platformu er ya da geç aynı mimari kararla karşılaşır: Müşterinin sunucusunda tam olarak ne çalışacak? ACME ekosistemindeki varsayılan cevap, her ana bilgisayara tam donanımlı bir ACME istemcisi kurmaktır. Biz bunu bilinçli olarak yapmadık. Bunun yerine; iş yoklayan, işi yerelde yürüten ve yapılandırılmış sonuç bildiren küçük bir .NET işçisi geliştirdik. Tüm orkestrasyon ise kontrol düzleminde kaldı.

Bu yazıda bu kararın nedenini ve ajanın gerçekte nasıl çalıştığını anlatıyoruz.

Her sunucuda tam ACME istemcisi çalıştırmanın sorunu

Her kenar sunucusunda eksiksiz bir ACME istemcisi çalıştırmak, bir filoyu işletmeye başlayana kadar basit görünür.

Yapılandırma sapması (drift). Her ana bilgisayar kendi hesap anahtarını, kendi yenileme yapılandırmasını ve kendi zamanlanmış görevini tutar. Üç yıl sonra hiçbir iki sunucu tam olarak aynı şekilde yapılandırılmış olmaz ve bunu öğrenmenin tek yolu tek tek bağlanıp bakmaktır.

Yetki yüzeyi. Tam bir istemcinin CA ile görüşmesi, doğrulamaları çözmesi, dosya sistemine yazması ve web sunucusu yapılandırmasını değiştirmesi gerekir. Bu, envanterdeki her makineye verilmesi gereken oldukça geniş bir yetki kümesidir.

Filo görünürlüğünün olmaması. Yenileme başarısız olduğunda yerelde başarısız olur. Her ana bilgisayardan log toplayan bir sistem yoksa ilk belirti, canlı ortamda görülen bir tarayıcı uyarısı olur.

Değişikliğin etki alanı. Yeni bir CA uç noktası, değişen bir doğrulama gereksinimi veya ACME istemcisinde çıkan bir güvenlik açığı; tek bir servise değil, her sunucuya dokunmak anlamına gelir.

Sorunun kökeni şu: Bu tasarım karar verme yetkisini kenara taşır. Biz ise kenarın hiçbir karar vermemesini istedik.

Ayrım: Orkestrasyon merkezde, yürütme yerelde

Certinite yaşam döngüsünü net biçimde ayrılmış iki yarıya böler.

Kontrol düzlemi, muhakeme gerektiren her şeyin sahibidir: ACME hesap ve sipariş yönetimi, doğrulama yönteminin seçilmesi, sertifika durumu ve süre takibi, yenilemenin ne zaman gerektiğine karar verilmesi ve ticari CA iş akışlarının yürütülmesi. Bunların tamamı API katmanında, her kiracı için tek bir yerde gerçekleşir.

Ajan ise yalnızca gerçekten makinede bulunmayı gerektiren işlerin sahibidir: IIS'in sunacağı doğrulama dosyasını yazmak, sertifikayı Windows sertifika deposuna aktarmak ve doğru site bağlamasına iliştirmek.

Ajanın kendine ait bir zamanlaması, bir ACME uygulaması, sertifika otoriteleri hakkında bilgisi veya herhangi bir şeyin ne zaman yapılması gerektiğine dair bir görüşü yoktur. API'ye "bana iş var mı?" diye sorar, kendisine söyleneni birebir yapar ve sonucu bildirir. Yeni bir CA eklemek veya doğrulama mantığını değiştirmek bir kontrol düzlemi değişikliğidir; ajanlar hiç dokunulmadan çalışmaya devam eder.

Tasarım gereği yalnızca dışa doğru bağlantı

Ajan yaklaşık her on saniyede bir API'ye dışa doğru bir HTTPS bağlantısı açar ve sıradaki işini ister. Ağ modelinin tamamı bundan ibarettir.

Dinleyen bir servis, açık bir port veya güvenlik duvarı istisnası yoktur. Ne internetten ne de iç ağdan hiçbir şey ajana bağlantı başlatamaz. DMZ'deki veya katı çıkış politikaları olan sunucularda bu, çoğu zaman onaylanan bir kurulum ile reddedilen bir kurulum arasındaki farktır; çünkü güvenlik incelemesi tek bir dışa HTTPS hedefine indirgenir.

Kimlik doğrulama, her istekte gönderilen ajana özel bir gizli anahtarla yapılır. Ajan bu anahtarı yalnızca bir kez, bir operatör kuruluma kısa bir etkinleştirme kodu yapıştırdığında alır; API ise anahtarın kendisini değil, yalnızca SHA-256 özetini saklar.

Bilinçli olarak küçük tutulmuş bir iş sözlüğü

Ajan, her biri somut bir yerel işleme karşılık gelen birkaç iş türü tanır:

Bu sözlüğü küçük tutmak işin özüdür. Her iş; kendi içinde bütün, tekrarlanabilir ve yapılandırılmış bir başarı/hata sonucu üreten bir işlemdir. Bu sayede kontrol düzlemi her ana bilgisayarın gerçek durumunu loglardan çıkarım yaparak değil, doğrudan bilir.

Komut çağırmak yerine yerel Windows API'leri

Ajan Windows tarafında, platformun kendi yönetim API'lerini komut satırı üzerinden dolaşmak yerine doğrudan kullanır.

Sertifikalar, bir yöneticinin de kullanacağı yer olan LocalMachine\My deposuna MachineKeySet ve PersistKeySet seçenekleriyle aktarılır; böylece özel anahtar yeniden başlatmalardan sağ çıkar ve IIS çalışan sürecine erişilebilir kalır.

Bağlamalar, IIS'in desteklenen yönetim API'si olan Microsoft.Web.Administration üzerinden yönetilir. Ajan, bağlaması alan adıyla eşleşen siteyi bulur; ardından mevcut HTTPS bağlamasını günceller veya 443 portunda SNI etkin yeni bir bağlama oluşturur. Böylece tek bir IP üzerinde birden çok alan adı bir arada çalışabilir.

Bunun önemi şurada: Yaygın alternatif, PowerShell veya netsh komut metinleri üretip çıktılarını ayrıştırmaktır. Bu yaklaşım Windows Server sürümleri arasında kırılgandır, anlamlı hata yönetimi yapmayı zorlaştırır ve birim testini fiilen imkânsız kılar. ServerManager'ı doğrudan çağırmak bize tipli nesneler, gerçek istisnalar ve IIS Manager'ın kendi davranışıyla tutarlı bir sonuç verir.

HTTP-01 yolu da aynı şekilde IIS'e duyarlıdır. ACME token'larının dosya uzantısı yoktur ve IIS varsayılan olarak bu dosyaları sunmayı reddeder. Bu yüzden ajan, uzantısız dosyaları text/plain olarak eşleyen kapsamı sınırlı bir web.config yazar ve IIS_IUSRS ile IUSR için okuma izni verir. Ardından token'ı doğru Host başlığıyla loopback üzerinden çeker ve API'ye "doğrulama hazır" demeden önce yanıt gövdesini karşılaştırır. CA'dan doğrulama yapması yalnızca ajan dosyanın gerçekten erişilebilir olduğunu kanıtladıktan sonra istenir — bu da geniş bir sessiz doğrulama hatası sınıfını, açık ve üzerine gidilebilir bir hataya dönüştürür.

Ticari sertifikalarda özel anahtar sunucudan çıkmaz

Ticari sertifikalarda ajan, RSA anahtar çiftini makinenin kendisinde üretir ve geriye yalnızca CSR'ı gönderir. Özel anahtar yerele yazılır ve hiçbir zaman iletilmez. CA sertifikayı ürettiğinde API sertifika PEM'ini gönderir, ajan bunu hiç dışarı çıkmamış anahtarla eşleştirir, sonucu kurar ve geçici anahtar dosyasını siler.

Böylece API, tüm satın alma ve üretim iş akışını yönetirken siteyi koruyan anahtarı görebilecek bir konumda hiç bulunmaz.

Tek kod tabanı, Windows ve Linux

Aynı proje hem net8.0-windows hem net8.0 hedefler. Platforma özgü kod tek bir IServerManagerService soyutlamasının arkasındadır; bu sayede işçi döngüsünün kendisinde hiçbir platform dallanması yoktur.

Windows'ta bu soyutlama yukarıda anlatılan IIS uygulamasına çözümlenir. Linux'ta ise aynı ikili dosya systemd altında arayüzsüz çalışır ve yapılandırmaya göre nginx, Apache, Tomcat veya IBM HTTP Server'a çözümlenir. İş yönetimi, yoklama, kimlik doğrulama ve sonuç bildirimi her platformda birebir aynı koddur — yalnızca "şu dosyayı yaz, şu sertifikayı kur" adımı değişir.

Kopyalamanızı önereceğimiz kararlar

Benzer bir şey geliştiriyorsanız, üç karar kendini defalarca amorti etti:

1. Her kararı kontrol düzlemine koyun. Hiçbir karar vermeyen bir ajan sapamaz. Güncellemeler, yeni CA'lar ve değişen politikalar yüzlerce değil, tek bir dağıtım işine dönüşür.
2. Ajanı yalnızca dışa doğru bağlantı kuracak şekilde tasarlayın. Bu, koca bir saldırı yüzeyini ortadan kaldırır ve en az onun kadar önemlisi, güvenlik incelemesindeki tartışmayı da bitirir.
3. Platformun gerçek API'lerini kullanın. Windows'ta Microsoft.Web.Administration ve X509Store, komut çağırmaya kıyasla başlangıçta daha fazla emek ister ama uzun vadede çok daha iyi davranır.

Her kurulumun bir ajana ihtiyacı yoktur. cPanel, Plesk, F5 BIG-IP ve FortiGate gibi hosting panelleri ve donanım cihazları, kendi yönetim arayüzleri üzerinden doğrudan API'den ajansız olarak sürülür — aynı kontrol düzlemi, hedefe hiçbir şey kurmadan.

Çalışırken görmek ister misiniz? Ücretsiz hesap oluşturun ve bir test sunucusunda tam bir üretim döngüsü çalıştırın; ya da Windows Server ve IIS'te Let's Encrypt otomasyonu yazımızı okuyun.