Beyaz Etiketli AI API Uç Noktaları: Özel Etki Alanları, TLS Otomasyonu ve Kiracı İçin Güvenli Yönlendirme

Ağ geçidinize işaret eden bir müşteri CNAME'si, üretime hazır, markalı bir uç nokta oluşturmaz. DNS kaydı, bir sertifika kullanılabilir olmadan önce çözümlenebilir, sertifika yalnızca doğrulama kayıtları bozulmadan kaldığı sürece yenilenebilir ve işaretlenmemiş bir Host başlığı, bir isteği yanlış kiracı bağlamına yönlendirebilir.

Daha güvenli model, her markalı ana makine adını dayanıklı bir kontrol düzlemi kaynağı olarak ele almaktır. Sahiplik, sertifika verme, DNS geçişi, yönlendirme etkinleştirme, askıya alma ve silme işlemlerinin her birinin açık bir duruma ihtiyacı vardır. İstek zamanında, ana makine adı izin verilen kiracı bağlamını daraltırken, API anahtarı yetkilendirme sınırı olarak kalır.

Alan yaşam döngüsünü bağımsız kontrollere ayırın

Özel bir alanı verified gibi tek bir Boole değeriyle temsil etmeyin. En azından dört bağımsız koşulu izleyin:

• Sahiplik: Müşterinin ana makine adının kontrolünü kanıtladı mı?
• Sertifika: Uçta geçerli bir sertifika verilmiş ve dağıtılmış mı?
• DNS: Yetkili DNS, beklenen ağ geçidi hedefi?
• Yönlendirme: Tam ana makine adı etkin bir kiracıya ve yönlendirme profiline bağlı mı?

Bu ayırma, belgelenmiş uç sağlayıcı davranışını yansıtır. Yönetilen özel ana bilgisayar adı ürünleri, ana bilgisayar adı sahipliği ve sertifika doğrulaması için farklı kayıtlar ve durumlar kullanabilir. Bu nedenle DNS çözümlemesi tek başına uç noktanın hazır olduğunu kanıtlamaz.

Pratik bir durum makinesi:

requested
  -> ownership_pending
  -> certificate_pending
  -> dns_pending
  -> ready
  -> suspended
  -> draining
  -> deleted

Bunlar iş durumlarıdır, sağlayıcı durumlarının doğrudan kopyaları değildir. Sağlayıcının ham durumunu ayrı olarak saklayın, ardından belgelenen değişmezlere göre kendi durumunuzu türetin. Örneğin, ready alan adını yalnızca sahiplik geçerli olduğunda, sertifika etkin olduğunda, DNS beklenen hedefi işaret ettiğinde ve uç rota etkin olduğunda işaretleyin.

Öneri:, ilk etkinleştirme sırasında geçişleri monoton hale getirir. Geçici ve başarılı bir TLS araştırması, sahiplik doğrulamasını veya yönlendirme kontrollerini atlamamalıdır. Etkinleştirmeden sonra, mutabakat, bir alanı ready konumundan suspended durumuna taşıyabilir veya bu değişmezler tutmayı bıraktığında açık bir şekilde bozulmuş duruma geçebilir.

Bir alanı birinci sınıf bir kaynak olarak depolayın

İşlemsel beyaz etiketli AI API ağ geçidi için alan kaydı, belirsiz API çağrılardan ve sağlayıcıdan kurtulmak için yeterli bilgi içermelidir drift:

{
  "domain_id": "dom_01J...",
  "hostname_ascii": "api.customer.example",
  "tenant_id": "ten_01H...",
  "brand_id": "brand_42",
  "state": "certificate_pending",
  "ownership_method": "dns_txt",
  "ownership_record": {
    "name": "_gateway-verify.api.customer.example",
    "value": "verify=..."
  },
  "certificate_status": "pending_validation",
  "expected_cname": "customers.edge.example",
  "routing_profile_id": "route_openai_compatible_v3",
  "provider_hostname_id": "edge_8f2...",
  "creation_operation_id": "op_01J...",
  "last_reconciled_at": "2026-11-02T10:00:00Z",
  "last_reconciliation_result": "certificate_pending"
}

Benzersizlik kontrollerinden önce IDNA uyumlu bir kitaplık kullanarak ana makine adını küçük harf ASCII'ye normalleştirin. Sondaki noktayı kaldırın ve IP değişmezlerini, URL yollarını, bağlantı noktalarını, açıkça desteklenmedikçe joker karakterleri ve kabul edilen genel son ek politikanızın dışındaki adları reddedin. Gönderilen görüntüleme formunu yalnızca yetkili olmayan meta veriler olarak koruyun.

Normalleştirilmiş ana makine adı üzerinde genel bir benzersizlik kısıtlaması uygulayın. İki kiracı, farklı büyük harf kullanımı veya Unicode gösterimleri kullansalar bile hiçbir zaman aynı yetkiyi talep edememelidir.

Üretim DNS'sini değiştirmeden önce ön doğrulama

Edge platformu desteklediğinde, müşteriden üretim CNAME'sini değiştirmesini istemeden önce sertifikayı yayınlayın ve dağıtın.Tipik bir sıra şöyledir:

1. Alan kaynağını bir kimlik anahtarıyla oluşturun.
2. Sahiplik ve sertifika doğrulama kayıtlarını döndürün.
3. Her iki doğrulama da başarılı oluncaya kadar sağlayıcı etkinliklerini yoklayın veya alın.
4. Sertifikanın tam ana makine adı için dağıtıldığını onaylayın.
5. Müşteriden üretim CNAME'sini ağ geçidine yönlendirmesini isteyin target.
6. Birden fazla ağ konumundan yetkili DNS'yi çözümleyin.
7. Yolu etkinleştirin ve kimliği doğrulanmış uçtan uca bir inceleme gerçekleştirin.
8. Alan adını işaretleyin ready.

Gerçek: yönetilen SaaS-edge belgeleri, sıfır kesinti süreli geçiş dizilerini açıklar. doğrulama ve sertifika verilmesi, üretim CNAME'si değişmeden önce gerçekleşir. Ödünleşme: bu, gözle görülür bir TLS etkinleştirme açığını önler ancak müşterinin ek TXT, CNAME veya yetkilendirilmiş doğrulama kayıtları oluşturmasını gerektirir.

Ön doğrulama mevcut değilse olası kesintiyi açıkça belirtin. Sertifika verme yalnızca trafik taşındıktan sonra başladığında sıfır kesinti süresi sözü vermeyin.

Tam yetkiye göre yönlendirin, ardından anahtarı yetkilendirin

Güvenilen uç, ana makine adından izin verilen kiracı veya marka bağlamına kadar tam bir izin verilenler listesi tutmalıdır:

api.customer.example -> {
  tenant_id: "ten_01H...",
  brand_id: "brand_42",
  state: "ready"
}

Bilinmeyen, etkin olmayan ve belirsiz yetkilileri reddet. Bunları asla varsayılan kiracıya göndermeyin. HTTP/1.1 için Host'yi doğrulayın; HTTP/2 ve HTTP/3 için :authority'yi doğrulayın. TLS'nin aynı uçta sonlandırıldığı durumlarda istek yetkilisini, proxy tarafından desteklenen SNI ve sertifika bağlamıyla karşılaştırın.

Yönlendirme başlıkları aynı disiplini gerektirir. Genel uç, gelen X-Forwarded-Host, Forwarded ve tüm dahili kiracı başlıklarını kaldırmalı, ardından standart bir ana bilgisayar ve çözümlenmiş kiracı sinyali eklemelidir. Kaynak, bu sinyalleri yalnızca kimliği doğrulanmış uçtan kökene bağlantılar üzerinden kabul etmelidir.

Çalışma zamanı yetkilendirme sırası şöyle olmalıdır:

1. Etkin ana makine adı izin verilenler listesi aracılığıyla normalleştirilmiş yetkiyi çözümleyin.
2. API anahtarının kimliğini bağımsız olarak doğrulayın.
3. Etkin ana makineye eklenen değişmez kiracı tanımlayıcısını yükleyin. anahtar.
4. Çözümlenen ana makine adında anahtarın kiracısına izin verildiğini doğrulayın.
5. Kiracı ve anahtar kimliklerini kullanarak model, bütçe, hız sınırı ve yönlendirme politikası uygulayın.
6. Kullanım kayıtlarını ana makine adına değil, bu değişmez kimliklere yazın.

Bu, Partner API otomasyon, alan adı yönetimi işlemini yetkilendirme kısayoluna dönüştürmeden.

Yetki, yapılandırılan kaynak veya bağlantı bağlamıyla eşleşmediğinde 421 Misdirected Request değerini döndürür. Ana bilgisayar adı geçerli olduğunda ancak kimliği doğrulanmış anahtar, onu kullanmasına izin verilmeyen bir kiracıya ait olduğunda 403 Forbidden değerini döndürün. Hata gövdelerini, hangi kiracının bir ana makine adına sahip olduğunu açıklamayacak kadar genel tutun.

Kanonik ve markalı uç nokta uyumluluğu

Bazı müşterilerin hem ağ geçidinin kanonik uç noktası hem de markalı uç noktası üzerinde çalışmak için tek bir anahtara ihtiyacı vardır. Bu yalnızca her iki ana bilgisayar adı da aynı yetkili kiracı bağlamına çözümlendiğinde kabul edilebilir.Her anahtarın tek bir ana makine adına sıkı bir şekilde bağlanması, markalar arası kullanımı azaltır, ancak taşıma işlemlerini ve uç noktalar arasında geçiş yapan istemcileri karmaşık hale getirir.

Öneri: modeli, uygulama kodu içindeki dizeleri karşılaştırmak yerine, anahtar politikası olarak uç nokta bağlamlarına izin verdi. Örneğin, bir anahtar tenant:any-active-hostname, brand:brand_42 veya tam bir domain_id'ye izin verebilir.

İş Ortağı aracılığıyla yaşam döngüsü işlemlerini açığa çıkarma API

Minimum bir API, oluşturma, inceleme, yeniden doğrulama, askıya alma, devam ettirme ve silme işlemlerini desteklemelidir:

POST   /partner/v1/custom-domains
GET    /partner/v1/custom-domains/{domain_id}
POST   /partner/v1/custom-domains/{domain_id}/revalidate
POST   /partner/v1/custom-domains/{domain_id}/suspend
POST   /partner/v1/custom-domains/{domain_id}/resume
DELETE /partner/v1/custom-domains/{domain_id}

Oluşturma ve silme işlemleri, kararlı bağımsız anahtarları kabul etmelidir. Sağlayıcı API'leri, DNS yayılımı ve ağ zaman aşımları, arayan kişinin bir işlemin başarılı olup olmadığından emin olmamasına neden olabilir. Uç sağlayıcıyı çağırmadan önce işlem kaydını sürdürün ve istek aynı anahtar ve eşdeğer yük ile yeniden denendiğinde aynı alanı veya silme işlemini döndürün.

custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk ve custom_domain.deleted gibi imzalı yaşam döngüsü etkinliklerini yayınlayın. Olaylar bildirimdir, gerçeğin tek kaynağı değildir; tüketiciler, kaçırılan veya yinelenen teslimattan sonra mevcut durumu alabilmelidir.

DNS'yi, sertifikaları ve yönlendirmeyi sürekli olarak mutabakata varın

Etkinleştirme, yaşam döngüsünün sonu değildir. DNS kayıtları düzenlenir, doğrulama kayıtları kaybolur, uç yapılandırmasında sapmalar olur ve sertifikalar yenilenmeye yaklaşır.

Şunları kontrol eden periyodik bir uzlaştırıcı çalıştırın:

• Yetkili DNS ve beklenen CNAME veya yetki verilen hedef
• Sağlayıcı ana makine adı ve sertifika durumları
• Sertifika adları, geçerlilik süresi ve yenileme health
• Gerekli DNS doğrulama kayıtlarının varlığı
• Tam uç rota sahipliği ve etkinleştirme durumu
• Kiracının trafiğe hizmet vermeye mevcut uygunluğu

DNS tarafından doğrulanan sertifika otomasyonu, doğrulama CNAME kayıtlarının genel olarak çözümlenebilir durumda kalmasına bağlı olabilir. Otomatik yenilemenin her zaman başarılı olacağını varsaymak yerine, süre dolmadan önce uyarı verin.

Sertifika işlemleri için üstel gerileme ve titreşim ile sınırlı yeniden denemeleri kullanın. Düzenlemeyi doğrudan gerçekleştirdiğiniz ACME hesabını ve sipariş durumunu koruyun. Tekrar tekrar silme ve yeniden oluşturma, sertifika siparişi veya kayıtlı alan adı hız sınırlarını tüketebilir. Bekleyen ana makine adı kayıtları da açıkça kaldırılana kadar sağlayıcı kotasını tüketebilir.

Operasyonel tahmin: Mutabakat olmadan, en yaygın hatalar başarılı bir katılımdan sonra, DNS düzenlemeleri, sertifika yenileme, sağlayıcı tarafında sapma veya müşteri kaybı sırasında ortaya çıkar. Bu, ölçülen bir başarısızlık oranı değil, mimari bir beklentidir.

İki aşamada devre dışı

Önce veritabanı satırını silmek güvenli değildir çünkü uç eşlemeler, sertifikalar veya DNS bundan daha uzun süre dayanabilir.Denetlenebilir iki aşamalı bir iş akışı kullanın:

1. Alan adını draining'e taşıyın ve yeni entegrasyonlar için reklamını yapmayı bırakın.
2. Mevcut isteklerin kısa bir ek süre mi alacağına yoksa anında reddedileceğine karar verin.
3. Ana makine adının varsayılan bir kiracıya çözümlenememesi için uç rotayı devre dışı bırakın.
4. Özel ana makine adını ve sertifika ilişkisini sağlayıcı.
5. Müşteriden DNS kaydını kaldırmasını veya değiştirmesini isteyin.
6. DNS'nin artık hizmetinize yönlendirmediğini doğrulayın.
7. Tanımlayıcıları ve denetim kaydını korurken kaynağı deleted işaretleyin.

Temel hazırlığı kaldırılmış bir hizmeti hedefleyen sarkan bir CNAME, alt alan adının devralınması riski oluşturabilir. Tersine, eski bir haritalamayı aktif bırakmak, eski bir müşterinin trafiğini sizin tarafınızdan göndermeye devam edebilir. Sağlayıcı temizliğini ve DNS doğrulamasını aynı silme işlemiyle birleştirin, ancak her sonucu bağımsız olarak kaydedin.

Yalnızca mutlu yolu değil, sınırı da test edin

Müşteri alanlarını etkinleştirmeden önce, aşağıdakiler için uyumluluk testlerini otomatikleştirin:

• Sahte bir Host veya X-Forwarded-Host başlığı
• Çakışan SNI ve HTTP yetki değerleri
• Bilinmeyen bir ana makine adı ve bilinen ancak askıya alınmış bir ana makine adı
• Kiracı B'nin ana makine adında kullanılan A kiracısından geçerli bir anahtar
• Aynı önemsizlik anahtarıyla yinelenen oluşturma ve silme istekleri
• Büyük/küçük harf, son nokta veya Unicode varyasyonlarıyla gönderilen aynı ana makine adı
• DNS, etkinleştirmeden sonra beklenen hedef
• Yenilemeden önce kaldırılmış bir sertifika doğrulama kaydı
• Uç eşleme kaldırıldıktan sonra ancak DNS değişmeden önce silme işlemi kesintiye uğradı

Ayrıca günlüklerin, faturalandırmanın, kullanım ilişkilendirmesinin, hız sınırlarının ve politika kararlarının kiracı ve anahtar kimliklerini kullandığını doğrulayın. Ana bilgisayar adları değiştirilebilir sunum ve yönlendirme girişleridir; mali veya güvenlik kimlikleri haline gelmemelidirler.

Uygulama kontrol listesi

• Ana makine adlarını normalleştirin ve küresel benzersizliği zorunlu kılın.
• Sahiplik, sertifika, DNS ve yönlendirme hazırlığını ayrı ayrı izleyin.
• Desteklendiği durumlarda, sertifikaları geçişten önce önceden doğrulayın.
• Tam yetkili makamları izin verilenler listesine ekleyin güvenilen uçta.
• Güvenilmeyen yönlendirme başlıklarını çıkarın ve kimliği doğrulanmış bir kaynak sinyali oluşturun.
• Ana makine adının kiracı bağlamına göre API anahtarını yetkilendirin.
• Kök veya bağlantı uyumsuzluğu için 421 ve kiracılar arası anahtar kullanımı için 403 kullanın.
• Oluşturma ve silme işlemlerini gerçekleştirin idempotent.
• Sağlayıcı durumu, DNS, yönlendirme ve yenileme durumunu sürekli olarak uzlaştırın.
• Uç eşlemelerini açıkça silin ve ayrılma sırasında DNS'yi doğrulayın.

Markalı bir uç nokta yalnızca kontrol düzlemi durumu ve veri düzlemi davranışı uyumlu olduğunda hazır olur.Bu sözleşmeyi açıkça modelleyin, negatif yolları test edin ve API anahtarını son kiracı yetkilendirme sınırı olarak tutun.

İlgili okuma

• idempotent İş Ortağı API işlemleri