Sonucu açıklayan bir yol oluşturun
Kimlik doğrulama API'si kanıt takibi, başka bir incelemecinin neyin talep edildiğini, neyin iade edildiğini, neyin atlandığını ve uygulamanın sonuca nasıl ulaştığını yeniden yapılandırmasına olanak sağlamalıdır. Başarı rozeti veya büyük bir JSON dosyası yeterli değildir. İz, kaynak gözlemlerini yerel dönüşümlerden ve bunları takip eden insan kararlarından ayırmalıdır.
Bu makalede önerilen bir tasarım açıklanmaktadır. Hiçbir EmailAuth API'si, bağlayıcısı, olay akışı veya denetim özelliği doğrulanmadı. Hiçbir kimlik bilgisi, müşteri hesabı, API çağrısı veya tarama kullanılmadı. Kamu standartları ve sağlayıcı referansları 8 Kasım 2026'da gözden geçirildi. Örnekler, yürütülen demirbaşlar veya operasyonel transkriptler değil, tasarım örnekleridir.
Sözleşmeyi ve tahsilat sınırını sabitleyin
Sağlayıcıyı, uç noktayı, HTTP yöntemini, hesabı veya kiracı kapsamını ve gerekli izni adlandırın. Şema veya belge sürümünü, istemci sürümünü ve koleksiyon yapılandırmasını koruyun. Değişen bir dokümantasyon URL'si, değişmez bir sürüm pini değildir; tarihli bir yakalamayı koruyun ve doğrulanması gerekenleri kaydedin. Daha sonraki ayrıştırıcıların eski kanıtları sessizce yeniden yorumlamaması için sözleşme tanımlayıcısını her koleksiyon çalıştırmasında tutun.
Zaman penceresini, filtreleri ve beklenen tamamlanma sinyalini tanımlayın. Route 53 belgelenmiş liste işlemi, ad, tür ve varsa tanımlayıcı için IsTruncated ve devam değerlerini kullanır. Cloudflare DNS listesi uç noktası bunun yerine sayfa parametrelerini ve sonuç bilgilerini açıklar. Bunlar, kimlik doğrulama raporlama API'si için değiştirilebilir tarifler değil, farklı sözleşme örnekleridir. Route 53 Ve Cloudflare.
Sırları saklamadan yeterli bağlamı yakalayın
Bir yerel çalıştırma tanımlayıcısı atayın ve istek süresini, yanıt süresini, uç nokta şablonunu, gizli olmayan kaynak referansını, yanıt durumunu ve belgelenen herhangi bir sağlayıcı istek tanımlayıcısını kaydedin. Onaylanmış yanıt içeriğini veya korumalı yapı referansını özet ve koleksiyon kaynağıyla birlikte koruyun. Karma, daha sonraki bayt değişikliklerinin algılanmasına yardımcı olabilir; kaynağın doğru olduğunu veya bir koleksiyonun eksiksiz olduğunu kanıtlayamaz.
Kanıt izinde yetkilendirme başlıklarını, erişim belirteçlerini, imzalama sırlarını veya sınırsız hata ayıklama dökümlerini saklamayın. İncelenmiş bir alan izin verilenler listesi kullanın ve belge düzenleme kurallarını kullanın. Redakte edilmiş bir türev, orijinalin muhafaza edilmesinin gerekçeli ve yetkili olduğu durumlarda kontrollü orijinale olan bağlantıyı muhafaza etmelidir. OWASP'ın günlük kaydı kılavuzu, yararlı olay içeriğini, doğrudan günlüğe kaydedilmemesi gereken kimlik bilgilerinden ve hassas verilerden ayırır. OWASP Günlüğe Kaydetme Hile Sayfası.
Sayfalandırmanın eksiksizliğini kayıtlı bir sonuç haline getirin
Beklenen her devam adımını ve sonucunu izleyin. Sayfa tanımlayıcılarını veya işaretçilerini, öğe sayımlarını, mükerrer tespitleri ve terminal durumunu koruyun. Orta sayfa başarısız olursa, başarılı gözlemleri saklayın ancak koleksiyonu kısmi olarak etiketleyin. Gelen alt kümeden "başarısız gönderen yok" sonucunu çıkarmayın. Önbelleğe alınmış önceki bir başarı, mevcut çalıştırmanın tamamlanmamış durumunun üzerine yazmamalıdır.
Ayrıca sayfalar arasındaki tutarlılığı da göz önünde bulundurun. Route 53 listeleme sırasındaki kayıt değişikliklerinin eski ve yeni görünümleri karıştırabileceği konusunda uyarıyor. Diğer API'ler farklı anlık görüntü garantileri sunabilir veya hiç sunmayabilir. Gerçek sözleşmeyi, gözlemlenen tahsilat aralığını ve eşzamanlı değişiklik belirsizliğini kaydedin. Tam bir geçiş, otomatik olarak tek bir atomik anlık görüntü değildir.
Aktarım yeniden denemelerini mantıksal işlemden ayırın
Belgelenen hizmet sözleşmesini kullanarak yeniden denenebilir sonuçları sınıflandırın. Hız sınırı sinyallerine saygı gösterin, sınırlı geri çekilme uygulayın ve deneme sayılarını ve nihai tükenmeyi koruyun. Cloudflare HTTP 429'u ve yeniden deneme davranışını belgeliyor ancak bu, başka bir sağlayıcının kotasını veya yeniden deneme politikasını oluşturmaz. Yeniden denemek, ilk toplama işleminin geciktiği veya eksik olduğu gerçeğini ortadan kaldırmamalıdır. Cloudflare hız sınırı belgeleri.
HTTP yönteminin semantiği de önemlidir. Eşgüçlülük, tekrarlanan özdeş isteklerin aynı amaçlanan etkiye sahip olduğu anlamına gelir; her yanıtın aynı olması veya her işlemin zararsız olması anlamına gelmez. Belirsiz bir değişiklik isteğini yalnızca bir istemcinin zaman aşımına uğraması nedeniyle otomatik olarak yeniden yürütmeyin. Bu iş akışı salt okunurdur; gelecekteki herhangi bir yazma yolunun ayrı bir yetkilendirmeye ve doğrulanmış bir sonuç kontrolüne ihtiyacı vardır. RFC 9110 , bölüm 9.2.2.
Olay alımı için belgelenmiş bir olay kimliği ve dayanıklı bir yineleme işleme kuralı tanımlayın. Sağlayıcı teslimatı yeniden deneyebilir veya ilgili olayları beklenmedik bir sırayla gönderebilir. Bir olayı kabul etmeden önce göndereni söz konusu sağlayıcının desteklenen mekanizmasını kullanarak doğrulayın, ardından paylaşılan sırrı günlüğe kaydetmeden doğrulama ve işleme sonuçlarını kaydedin. OWASP'ın web kancası kılavuzu, belirli bir kimlik doğrulama satıcısının imzalı olayları uyguladığının kanıtı değil, güvenlik tasarımı desteğidir. OWASP Web Kancası Güvenliği.
Dönüşümleri ve kararları ayrı kayıtlar olarak koruyun
Ayrıştırıcı sürümünü, normalleştirme kurallarını ve reddedilen girişleri kaydedin. Sağlayıcının zaman damgalarını besleme süresinden ve analiz zamanından farklı tutun. İçin DMARC Satırları birleştirmeden önce verileri toplayın, raporlama organizasyonunu, raporlama aralığını ve rapor kimliğini koruyun. RFC 9990 raporlama yapısını tanımlar; belirli bir API sarmalayıcının her raporu döndürdüğünü veya her alanı koruduğunu belirlemez. RFC 9990.
Temel gözlemi yeniden yazmak yerine, analistin yorumunu ve insan onayını yeni kayıtlar olarak ekleyin. Bir düzeltme neyin yerine geçtiğini ve nedenini tanımlamalıdır. Erişim kısıtlamaları, saklama ve yetkili açıklamanın kendilerine ait sahipleri olması gerekir. Teknik olarak ayrıntılı bir iz, kararla ilgisi olmayan geniş bir mesaj içeriği veya müşteri bilgisi deposu haline gelmemelidir.
Güvenilirliği talep etmeden önce fikstürleri belirtin
Önerilen fikstür seti, temiz bir çok sayfalı geçişi, tekrarlanan kayıtları, yinelenen olayları, gecikmiş bir olayı, hız sınırı duraklamasını, tükenmiş yeniden denemeleri ve daha önceki başarının ardından kısmi bir başarısızlığı kapsamalıdır. Bir şema değişikliğini ve reddedilen bir yetkilendirme girişimini ekleyin. Beklenen sonuçlar, hangi kanıtların kullanılabilir kaldığını ve hangi sonuçların saklanması gerektiğini tanımlamalıdır. Bu makale için bu vakaların hiçbiri idam edilmedi.
Tam orijinal kanıt gereksinimi açıktır: Sürüme sabitlenmiş bir API sözleşmesi ve sayfalandırma, yinelenen olaylar, yeniden denemeler ve kısmi hatalar için sabitler. Tarihli kamuya açık referanslar ve bu anlatım, gerçek bir entegrasyon için tamamlanmış bir sözleşme veya fikstür paketi değil, hazırlık niteliğindedir. Bağımsız inceleme, teknik ve güvenlik kabulü, onaylanmış operasyonel kanıtlar, görsel kontroller ve sahibin yayınlama izni henüz tamamlanmamıştır.