Web Sitelerinde .well-known Dizini ve Yapılandırma Dosyaları Rehberi

Modern web geliştirme ekosisteminde, sunucu altyapıları ile dış istemciler, güvenlik araçları ve mobil uygulamalar arasındaki otomatik iletişimi standartlaştırmak kritik bir ihtiyaç haline gelmiştir. İşte bu noktada IETF (Internet Engineering Task Force) tarafından tanımlanan .well-known dizini, web sitelerinde bilinen standart URL yollarını barındıran gizli bir kök dizin olarak öne çıkar. İnternet standartları geliştikçe, SSL/TLS sertifikalarının otomatik yenilenmesinden siber güvenlik zafiyetlerinin bildirilmesine, mobil derin bağlantılardan (deep linking) OAuth ve Passkey kimlik doğrulamalarına kadar birçok kritik protokol bu dizine bağımlı hale gelmiştir.

Bir web geliştirici veya sistem yöneticisi olarak .well-known dizini mimarisini doğru anlamak ve web sunucunuzda (Nginx, Apache veya IIS) doğru şekilde yapılandırmak, hem web sitenizin güvenliğini artırır hem de platformlar arası entegrasyon süreçlerini kusursuzlaştırır. Bu rehberde, .well-known standardının ne olduğunu, en çok kullanılan yapılandırma dosyalarını, sunucu kurulum adımlarını ve sık yapılan hataları detaylarıyla ele alıyoruz.

.well-known Dizini Nedir ve Neden Önemlidir?

RFC 5785 ve bunu güncelleyen RFC 8615 standartları ile tanımlanan .well-known dizini, web sunucularının public yayın yapılan kök dizininde (/.well-known/) yer alan özel bir alandır. Web tarayıcıları, arama motoru botları, güvenlik araştırmacıları ve mobil işletim sistemleri, bir alan adı (domain) hakkında önceden tanımlanmış meta verileri ve yapılandırma dosyalarını çekmek için doğrudan bu dizine standart istekler atarlar.

Geleneksel web mimarilerinde her yazılım sağlayıcısı kendi özel URL yapısını (örneğin /admin/config veya /api/security) kullandığında, istemcilerin bu dosyaları otomatik olarak keşfetmesi imkansızdı. IETF, bu dağınıklığı önlemek adına kök dizinde nokta (.) ile başlayan ve gizli klasör statüsünde olan tek bir standart yol belirlemiştir.

.well-known kullanımının temel avantajları şunlardır:

• Otomasyon ve Standartlaşma: ACME protokolü gibi sistemlerin insan müdahalesi olmadan SSL sertifikası üretmesini sağlar.
• Güvenlik ve Şeffaflık: Siber güvenlik araştırmacılarının sitedeki zafiyetleri doğru kişilere iletmesi için standart bir iletişim kanalı açar.
• Platformlar Arası Köprü: Mobil uygulamaların (iOS ve Android) web sitenizle güvenli şekilde eşleşmesini doğrular.

En Çok Kullanılan .well-known Yapılandırma Dosyaları

.well-known klasörü içerisine rastgele dosyalar konulmaz. IANA (Internet Assigned Numbers Authority) tarafından tescillenmiş veya sektör standardı kabul edilmiş belirli dosya ve dizin isimleri bulunur. Günümüzde en sık karşılaşılan yapılandırma dosyaları şunlardır:

1. acme-challenge (SSL/TLS Sertifika Doğrulaması)

Let's Encrypt ve diğer otomatik sertifika otoriteleri (CA), ACME (Automated Certificate Management Environment) protokolünü kullanır. Sunucunuz için bir SSL sertifikası talep ettiğinizde, doğrulama mekanizması http://example.com/.well-known/acme-challenge/<RASTGELE_TOKEN> adresine geçici bir dosya bırakır ve bu dosyayı HTTP üzerinden okuyarak alan adının sahibi olduğunuzu kanıtlar.

2. security.txt (RFC 9116 Siber Güvenlik Bildirimi)

Bir güvenlik araştırmacısı sitenizde açık bulduğunda size nasıl ulaşacağını bilmelidir. /.well-known/security.txt dosyası; iletişim e-postası, PGPP anahtarları, güvenlik politikası ve ödül programı (bug bounty) detaylarını barındırır. 2026 yılı itibarıyla uluslararası siber güvenlik standartlarında bu dosyanın bulunması kritik bir gereksinim olarak değerlendirilmektedir.

3. apple-app-site-association (iOS Evrensel Bağlantılar)

iOS uygulamalarının web sitenizdeki URL'leri doğrudan uygulama içinde açabilmesi (Universal Links) ve Passkey kimlik doğrulama desteği sunabilmesi için bu dosya gereklidir. /.well-known/apple-app-site-association yolunda uzantısız bir JSON formatında sunulur.

4. assetlinks.json (Android App Links)

Android ekosisteminde Digital Asset Links doğrulama mekanizması için kullanılır. /.well-known/assetlinks.json dosyası, Android uygulamanızın paket adını (package name) ve SHA-256 sertifika parmak izini içerir. Böylece web sitenize tıklayan kullanıcılar doğrudan mobil uygulamanıza yönlendirilir.

5. change-password (Otomatik Şifre Değiştirme Yönlendirmesi)

Apple Safari, Google Chrome ve 1Password gibi parola yöneticileri, sızdırılmış bir şifre tespit ettiğinde kullanıcıyı şifre değiştirme sayfasına yönlendirmek ister. /.well-known/change-password adresi ziyaret edildiğinde web sitenizin ilgili şifre sıfırlama paneline HTTP 302/301 ile yönlendirme yapması önerilir.

6. openid-configuration (OAuth 2.0 ve OpenID Connect Keşfi)

Siteniz bir OAuth 2.0 veya OpenID Connect kimlik sağlayıcısı (Identity Provider) olarak çalışıyorsa, istemciler yetkilendirme (authorization) ve token uç noktalarını /.well-known/openid-configuration adresinden otomatik olarak çekerler.

Sitenizde aşamalı web uygulamaları inşa ediyorsanız, manifest dosyalarının konumlandırılması ve servis işçileri (service worker) ile ilişkisini öğrenmek için Web App Manifest (manifest.json) Nedir? Yapılandırma ve PWA Entegrasyon Rehberi içeriğimizi inceleyebilirsiniz.

Sunucu Düzeyinde .well-known Dizini Yapılandırması (Nginx ve Apache)

Web sunucuları varsayılan olarak nokta (.) ile başlayan dosyaları ve klasörleri gizli kabul eder ve erişimini engeller (HTTP 403 Forbidden veya HTTP 404 Not Found). Bu nedenle .well-known dizini dış dünyaya açık hale getirilmek için sunucu konfigürasyonunda özel kurallar tanımlanmalıdır.

Nginx Yapılandırması

Nginx sunucunuzda tüm gizli dosyaları bloklayan bir kuralınız varsa, .well-known klasörüne istisna tanımanız gerekir. Sitenizin Nginx blok dosyasına (/etc/nginx/sites-available/example.com) aşağıdaki konfigürasyonu ekleyin:

server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/example.com/public;

    # Tüm gizli dosyalara erişimi engelle
    location ~ /\.(?!well-known) {
        deny all;
        return 404;
    }

    # .well-known dizinine açıkça izin ver ve MIME türlerini ayarla
    location ^~ /.well-known/ {
        allow all;
        default_type text/plain;
        autoindex off;
    }

    # apple-app-site-association için özel JSON MIME türü
    location = /.well-known/apple-app-site-association {
        default_type application/json;
    }
}

Yapılandırmayı test edip Nginx'i yeniden başlatın:

sudo nginx -t
sudo systemctl reload nginx

Apache (.htaccess) Yapılandırması

Apache web sunucusu kullanıyorsanız, kök dizindeki .htaccess dosyasına aşağıdaki kuralları ekleyerek .well-known erişimini güvenli şekilde aktif edebilirsiniz:

<IfModule mod_rewrite.c>
    RewriteEngine On
    
    # .well-known dışındaki tüm gizli dosyalara erişimi engelle
    RewriteRule "(?:^|/)\.(?!well-known)" - [F]
</IfModule>

# Özel Content-Type tanımlamaları
<IfModule mod_headers.c>
    <Files "apple-app-site-association">
        Header set Content-Type "application/json"
    </Files>
    <Files "security.txt">
        Header set Content-Type "text/plain; charset=utf-8"
    </Files>
</IfModule>

Uygulamalı .well-known Dosya Oluşturma ve Test Etme

Sitenizi güncel standartlara uygun hale getirmek için adım adım örnek bir security.txt ve assetlinks.json dosyası oluşturalım.

Adım 1: security.txt Dosyası Oluşturma

Sunucunuzun kök dizininde .well-known isimli bir klasör açın ve içine security.txt dosyasını ekleyin:

Contact: mailto:güvenlik@example.com
Contact: https://example.com/güvenlik-bildirimi
Expires: 2027-12-31T23:59:59.000Z
Preferred-Languages: tr, en
Canonical: https://example.com/.well-known/security.txt
Policy: https://example.com/güvenlik-politikası

Adım 2: Android assetlinks.json Oluşturma

Android uygulamanız ile sitenizi doğrulamak için /.well-known/assetlinks.json dosyasına aşağıdaki yapıyı ekleyin:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.app",
    "sha256_cert_fingerprints": [
      "14:6D:E9:A1:C5:D9:85:D5:CD:B2:D6:7A:B7:C4:08:92:0C:84:C5:5D:87:69:B3:36:A2:35:E1:92:FC:99:C9:4D"
    ]
  }
}]

Adım 3: Yapılandırmayı Test Etme

Dosyalarınızı yükledikten sonra terminal üzerinden curl komutu ile HTTP yanıt başlıklarını ve durum kodlarını kontrol edebilirsiniz:

curl -I https://example.com/.well-known/security.txt

Başarılı bir senaryoda HTTP/2 200 yanıtı ve doğru content-type dönmelidir. Ayrıca tarayıcı tarafındaki ağ hareketlerini incelemek ve önbellek sorunlarını teşhis etmek için Chrome DevTools Kullanım Rehberi: Web Geliştiriciler İçin Hata Ayıklama kılavuzumuzdan faydalanabilirsiniz.

Sitenizi mobil cihazlara tam uyumlu hale getirirken PWA yeteneklerini de kullanıyorsanız, Progressive Web App (PWA) Nedir? Web Siteleri İçin PWA Kurulum Rehberi içeriğimize göz atabilirsiniz.

.well-known Yapılandırmasında Sık Yapılan Hatalar ve Güvenlik İpuçları

HTTP 403 / 404 Hataları: Web sunucularındaki varsayılan "gizli dosyalara erişimi engelle" (deny dotfiles) kuralları nedeniyle .well-known klasörü de engellenebilir. Yukarıda verilen Nginx (?!well-known) negatif bakış (negative lookahead) kuralı bu sorunu çözer.

Yanlış Content-Type Başlığı: Özellikle apple-app-site-association dosyasının uzantısız olması nedeniyle sunucular bunu text/plain veya application/octet-stream olarak sunabilir. Apple sunucuları strictly application/json başlığı bekler.

HTTPS Zorunluluğu ve SSL Döngüleri: Birçok .well-known dosyası (örneğin Android Asset Links veya Apple AASA) sadece geçerli bir SSL sertifikası (HTTPS) üzerinden çalışır. Ancak Let's Encrypt ilk sertifikayı üretirken HTTP (Port 80) üzerinden acme-challenge kontrolü yapar. Sunucunuzda HTTP'den HTTPS'e yönlendirme yaparken .well-known/acme-challenge/ yolunu bu yönlendirmenin dışında tutmak veya yönlendirmenin HTTP 301 ile sorunsuz çalıştığından emin olmak gerekir.

Hassas Bilgi İfşası (Information Disclosure): .well-known dizini altına sistem yedekleri, .env dosyaları veya özel sunucu anahtarlarını kesinlikle koymamalısınız. Yalnızca public olması tasarlanan standart dosyalar yer almalıdır.

Sonuç ve Sonraki Adımlar

.well-known dizini, modern web altyapısının sessiz ama en kritik yapı taşlarından biridir. Otomatik SSL yenilemelerinin kesintisiz çalışması, mobil uygulamalarınızın web sitenizle entegre olması ve siber güvenlik şeffaflığı için sunucu konfigürasyonunuzda .well-known kurallarının eksiksiz tanımlanmış olması gerekir.

Sonraki Adım: İlk iş olarak sunucunuzda curl -I https://siteniz.com/.well-known/security.txt komutunu çalıştırarak bir güvenlik iletişim dosyası oluşturun ve Nginx/Apache yapılandırmanızın .well-known isteklerine 403 engeli koymadığını doğrulayın.