.well-known Dizini Nedir? SSL, Security.txt ve App Link Yapılandırması

Modern web sunucularında, istemcilerin ve otomatik sistemlerin sunucu hakkındaki metadata bilgilerine standart bir yoldan erişebilmesi için belirlenmiş özel kök dizinler kullanılır. Bu dizinlerin başında .well-known gelir. İnternet Tahsisli Sayılar ve İsimler Kurumu (IANA) ve IETF tarafından standartlaştırılan bu dizin, SSL/TLS sertifika doğrulamasından siber güvenlik bildirimlerine, mobil uygulama derin bağlantılarından (Deep Linking) kimlik doğrulama protokollerine kadar geniş bir yelpazede hizmet verir.

Peki, teknolojik altyapıların görünmeyen kahramanı olan .well-known dizini nedir, web sitenizde nasıl yapılandırılır ve hangi protokoller için kritik öneme sahiptir? Bu rehberde, sunucu konfigürasyonlarından güvenlik ayarlarına kadar tüm süreçleri adım adım ele alıyoruz.

.well-known Dizini Nedir ve Neden Önamlidir?

.well-known dizini, IETF tarafından RFC 5785 (daha sonra RFC 8615 ile güncellenmiştir) standardı kapsamında tanımlanmış, web sitelerinin kök dizininde (/) yer alan gizli bir klasördür. Unix tabanlı sistemlerde başında nokta (.) bulunan klasörler gizli dizin olarak kabul edildiğinden, bu klasör varsayılan olarak standart dosya yöneticilerinde görünmez.

Bu standart dizinin temel amacı; arama motorları, güvenlik tarayıcıları, SSL sertifika yetkilileri (CA) ve mobil işletim sistemleri gibi harici istemcilerin, web sitenize ait yapılandırma dosyalarını sabitleştirilmiş bir URI yolunda bulabilmesini sağlamaktır. Klasör adı sabit olduğu için istemcilerin sitenizin yapısını tahmin etmesine veya karmaşık yönlendirmeleri izlemesine gerek kalmaz.

Örneğin bir SSL sertifikası sağlayıcısı, sitenizin mülkiyetini doğrulamak istediğinde otomatik olarak https://alanadiniz.com/.well-known/acme-challenge/ adresini kontrol eder. Benzer şekilde bir iOS cihazı, web sitenizdeki bir bağlantının mobil uygulamanızda açılıp açılmayacağını anlamak için https://alanadiniz.com/.well-known/apple-app-site-association dosyasına istek atar.

.well-known Dizininin En Yaygın Kullanım Alanları

.well-known klasörü, protokollerin bağımsız çalışmasını engelleyerek merkezi ve güvenilir bir erişim noktası sunar. Günümüz web standartlarında bu dizin altında çalışan en kritik yapılandırmalar şunlardır:

1. SSL/TLS Sertifika Doğrulaması (ACME Challenge)

Let's Encrypt, ZeroSSL ve Sectigo gibi ücretsiz veya otomatikleşmiş sertifika yetkilileri, HTTP-01 doğrulama yöntemi için .well-known/acme-challenge/ yolunu kullanır. Sertifika talep ettiğinizde otomatik istemci (örneğin Certbot), bu dizin altına geçici ve benzersiz bir doğrulama dosyası oluşturur. Sertifika otoritesi bu dosyayı HTTP üzerinden okuyarak alan adının kontrolünüz altında olduğunu doğrular.

Örnek bir ACME doğrulama adresi ve içerik kontrolü şu şekildedir:

curl -I https://alanadiniz.com/.well-known/acme-challenge/xYz123456789TokenString

Bu aşamada sunucunuzun belirtilen adrese 200 OK yanıtı vermesi ve düz metin (text/plain) formatında token'ı sunabilmesi gerekir.

2. Siber Güvenlik ve Güvenlik Bildirimi: security.txt

Web sitenizde bir güvenlik açığı bulan etik korsanların (white-hat hackers) veya güvenlik araştırmacılarının sizinle doğru kanaldan iletişime geçebilmesi için RFC 9116 standardı ile tanımlanan security.txt dosyası bu dizinde saklanır. Detaylı bilgi için security.txt dosyası nedir başlıklı rehberimize göz atabilirsiniz.

Örnek bir /.well-known/security.txt dosya içeriği:

Contact: mailto:guvenlik@alanadiniz.com
Contact: https://alanadiniz.com/guvenlik-bildirimi
Expires: 2026-12-31T23:59:59.000Z
Preferred-Languages: tr, en
Canonical: https://alanadiniz.com/.well-known/security.txt
Policy: https://alanadiniz.com/guvenlik-politikasi

3. Mobil Uygulama Entegrasyonu: Universal Links ve App Links

Web siteniz ile iOS veya Android mobil uygulamanız arasında kesintisiz bir geçiş sağlamak (Deep Linking) için işletim sistemleri .well-known dizinindeki yetkilendirme dosyalarını kontrol eder.

• iOS (Apple Universal Links): /.well-known/apple-app-site-association (JSON formatındadır ancak uzantısı yoktur).
• Android (App Links): /.well-known/assetlinks.json

Örnek bir Android assetlinks.json dosyası:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.app",
    "sha256_cert_fingerprints": [
      "14:6D:E2:CD:AB:83:8B:C3:0A:A6:39:79:B0:EA:A2:1F:B1:A2:80:B4:4D:AE:C2:5E:FE:03:FE:19:D8:17:F1:C9"
    ]
  }
}]

4. Kimlik Doğrulama ve Diğer Web Standartları

• OpenID Connect Discovery: /openid-configuration dosyası, SSO (Tekli Oturum Açma) sağlayıcılarının uç noktalarını (endpoints) dış dünyaya açıklar.
• Şifre Değiştirme Yönlendirmesi: /change-password adresi, parolalarını güncellemek isteyen kullanıcıları tarayıcı otomasyonu aracılığıyla doğrudan şifre değiştirme sayfanıza yönlendirir.
• E-posta Güvenliği (MTA-STS): Mail transfer ajanlarının TLS kullanımını zorunlu kılmak için /mta-sts.txt dosyası kullanılır.

Web Sunucularında .well-known Dizini Yapılandırması

Varsayılan sunucu ayarlarında gizli dosyalar ve dizinler (. ile başlayanlar) güvenlik gerekçesiyle engellenmiş olabilir. Bu durum .well-known dizinine yapılan isteklerin 403 Forbidden hatası dönmesine neden olur. Aşağıda yaygın web sunucuları için doğru yapılandırma örneklerini bulabilirsiniz.

Nginx Yapılandırması

Nginx üzerinde gizli dosyaları engellerken .well-known dizinine istisna tanımak için aşağıdaki location bloğunu konfigürasyon dosyanıza (/etc/nginx/sites-available/default) eklemelisiniz:

# Gizli dosyalara erişimi engelle ancak .well-known dizinine izin ver
location ~ /\.(?!well-known).* {
    deny all;
    access_log off;
    log_not_found off;
}

# .well-known dizini için özel erişim kuralı
location ^~ /.well-known/ {
    allow all;
    default_type "text/plain";
    try_files $uri $uri/ =404;
}

Apache (.htaccess) Yapılandırması

Apache sunucularda Mod_Rewrite kullanıyorsanız, gizli klasör engelini .htaccess dosyanıza şu kuralı ekleyerek aşabilirsiniz:

RewriteEngine On

# .well-known dışındaki tüm gizli dosya ve klasörleri engelle
RewriteCond %{REQUEST_URI} !^/\.well-known/ [NC]
RewriteRule "(?:^|/)\." - [F]

IIS (Windows Server) Yapılandırması

Windows IIS sunucularda uzantısız dosyalar (örn: apple-app-site-association) varsayılan olarak servis edilmez. Bunun için web.config dosyanıza MIME türü ve erişim izinlerini eklemelisiniz:

<configuration>
  <system.webServer>
    <staticContent>
      <mimeMap fileExtension="." mimeType="application/json" />
    </staticContent>
    <security>
      <requestFiltering>
        <hiddenSegments>
          <remove segment=".well-known" />
        </hiddenSegments>
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

Sık Yapılan Hatalar ve Çözüm Yolları

.well-known entegrasyonlarında geliştiricilerin sıklıkla karşılaştığı sorunlar ve çözümleri şunlardır:

• 403 Forbidden / Access Denied Hatası: Sunucu güvenlik duvarı (WAF) veya web sunucusu ayarları nokta ile başlayan klasörleri tamamen engelliyor olabilir. Yukarıda paylaşılan sunucu kuralları ile .well-known için özel izin tanımlamalısınız.
• Yanlış Content-Type Başlığı: Örneğin, Apple cihazları apple-app-site-association dosyasını okurken Content-Type: application/json başlığı bekler. Sunucunuz bu dosyayı text/plain olarak servis ederse Universal Links çalışmayabilir.
• Sonsuz HTTP -> HTTPS Yönlendirme Döngüleri: ACME sertifika doğrulaması sırasında HTTP isteği HTTPS'e yönlendirilirken sertifika geçersizse doğrulama başarısız olur. ACME isteklerinin yönlendirmeye girmeden HTTP (80 portu) üzerinden yanıt vermesini sağlamak en güvenli yoldur.
• CORS (Cross-Origin Resource Sharing) Engelleri: Mobil uygulamalardan veya farklı alan adlarından yapılan doğrulama isteklerinde Access-Control-Allow-Origin: * başlığının eklenmesi gerekebilir.

Modern Web Standartları ve PWA Ekosistemi

.well-known dizini yalnızca güvenlik ve mobil yönlendirme ile sınırlı kalmaz. Web deneyimini yerel uygulama seviyesine çıkaran yapılarda da kritik bir köprü görevi görür. Örneğin, bir PWA projesi geliştirirken uygulama manifestoları ve mobil entegrasyonlar birbiriyle etkileşime girer. Bu konuda detaylı altyapı bilgisi için Web App Manifest (manifest.json) ve Progressive Web App (PWA) makalelerimizi inceleyebilirsiniz.

Aşağıdaki tablo, .well-known altındaki kritik dosyaların dosya türünü ve kullanım amacını özetlemektedir:

• acme-challenge/: Dizin | SSL/TLS Sertifikasyon Doğrulaması
• security.txt: Düz Metin | Güvenlik Açığı Bildirim Kanalları
• assetlinks.json: JSON | Android App Links Yetkilendirmesi
• apple-app-site-association: JSON (Uzantısız) | iOS Universal Links Yetkilendirmesi
• openid-configuration: JSON | OAuth 2.0 / OIDC Otomatik Yapılandırma

Sonuç

.well-known dizini, modern web mimarisinde sistemlerin birbiriyle standart, güvenli ve otomatik bir şekilde haberleşmesini sağlayan görünmez bir omurgadır. Otomatik SSL yenilemelerinin kesintiye uğramaması, siber güvenlik araştırmacılarının size ulaşabilmesi ve mobil uygulamalarınızın web sitenizle sorunsuz entegre olabilmesi için bu dizinin sunucunuzda doğru yapılandırılması şarttır.

Sonraki Adım: Sunucu yapılandırma dosyanızı (Nginx, Apache veya IIS) kontrol edin ve /.well-known/security.txt dosyanızı oluşturarak güvenlik bildirimi altyapınızı hemen aktif hale getirin.