Apache/Nginx'te Basic Authentication ile Dizin Koruma (.htpasswd)

HTTP Basic Authentication nedir, ne zaman kullanılır?

HTTP Basic Authentication, bir dizine veya URL'ye erişimi kullanıcı adı ve şifre ile sınırlamak için HTTP protokolünün kendi standardında tanımlı, en eski kimlik doğrulama yöntemlerinden biridir. Korunan bir sayfaya girildiğinde tarayıcı kendi yerleşik giriş penceresini gösterir; kullanıcı adı ve şifre girildikten sonra tarayıcı bu bilgiyi her istekle birlikte sunucuya iletir. Oturum yönetimi, çerez veya uygulama seviyesinde bir giriş formu gerekmez — doğrulama tamamen web sunucusu (Apache veya Nginx) katmanında gerçekleşir.

Bu basitlik Basic Auth'u belirli senaryolar için gerçekçi bir seçim yapar: henüz yayına alınmamış bir staging ortamını arama motorlarından ve tesadüfi ziyaretçilerden gizlemek, bir yönetim panelini (izleme aracı, dahili panel, phpMyAdmin gibi bir araç) ek bir katmanla korumak ya da sadece ekip içinde kullanılan bir dizine dışarıdan erişimi engellemek. Kullanıcı kaydı, parola sıfırlama akışı veya veritabanı gerektirmez; birkaç satır sunucu yapılandırması yeterlidir. Buna karşılık, herkese açık bir üyelik sistemi ya da rol/izin bazlı ayrıntılı yetkilendirme gerektiren durumlar için Basic Auth uygun değildir; bu ihtiyaçlar uygulama seviyesinde bir kimlik doğrulama sistemi ister.

Basic Auth'u uygulama içi bir giriş sisteminin yerine geçen bir çözüm olarak değil, sunucu seviyesinde ek bir kapı olarak düşünmek gerekir. Örneğin bir WordPress kurulumunun test sunucusunu canlıya almadan önce dış dünyadan gizlemek istediğinizde, uygulamaya hiç dokunmadan sadece sunucu yapılandırmasına birkaç satır ekleyerek tüm siteyi parola arkasına alabilirsiniz. Aynı yaklaşım, bir CI/CD önizleme ortamı, dahili bir raporlama aracı veya henüz test aşamasındaki bir API uç noktası için de geçerlidir.

.htpasswd dosya formatı ve şifre hashleme

.htpasswd, kullanıcı adı ve şifre karşılıklarını satır satır tutan düz metin bir dosyadır — ama düz metin derken kastedilen dosyanın kendisi, şifrenin saklanma biçimi değildir. Her satır kullaniciadi:hash biçimindedir ve dosyada birden fazla kullanıcı tanımlanabilir. Doğru üretilmiş bir .htpasswd dosyasında şifreler asla açık metin olarak durmaz, her zaman bir özet (hash) fonksiyonundan geçirilmiş halde tutulur.

admin:{SHA}5en6G6MezRroT3Xr8qkW3DTiP80=
ikincikullanici:$apr1$Qh9s0f2a$G8x1kR4vN9jZq7wYh1mIc0

Apache'nin desteklediği birkaç hash şeması vardır. {SHA} öneki ile başlayan format, şifrenin SHA-1 özetinin Base64 ile kodlanmasından oluşur ve klasik htpasswd -s komutunun ürettiği biçimdir; bu şema geriye dönük uyumluluk amacıyla hâlâ desteklenir ancak SHA-1 kriptografik olarak zayıf kabul edilir. $apr1$ ile başlayan format ise Apache'nin kendi MD5 tabanlı (APR1) algoritmasıdır. Modern Apache kurulumlarında mümkün olduğunda htpasswd -B ile üretilen bcrypt hash'i tercih edilmelidir; bcrypt kasıtlı olarak yavaş çalışacak şekilde tasarlanmıştır ve bu özelliği kaba kuvvet saldırılarına karşı onu çok daha dayanıklı kılar. Nginx tarafında ngx_http_auth_basic_module, {SHA} formatını doğrudan destekler; bcrypt desteği kurulumdan kuruluma değişebileceği için hangi hash şemasının desteklendiğini önceden kontrol etmek gerekir.

Apache tarafında yapılandırma

Apache'de Basic Auth iki şekilde tanımlanabilir: ana yapılandırma dosyasındaki bir <Directory> bloğu içinde, ya da korunacak dizine bırakılan bir .htaccess dosyasında. Her iki yöntemde de aynı dört direktif kullanılır: AuthType Basic kimlik doğrulama yönteminin Basic olduğunu belirtir; AuthName tarayıcının giriş penceresinde gösterdiği metindir (realm); AuthUserFile, kullanıcı adı:hash satırlarını içeren .htpasswd dosyasının sunucu üzerindeki tam yoludur; Require valid-user ise dosyada tanımlı herhangi bir kullanıcının girişine izin verir — yalnızca belirli kullanıcılar için Require user kullaniciadi da yazılabilir.

<Directory "/var/www/protected">
    AuthType Basic
    AuthName "Restricted"
    AuthUserFile /etc/apache2/.htpasswd
    Require valid-user
</Directory>

.htaccess ile çalışıyorsanız aynı dört satırı doğrudan bu dosyanın içine yazmanız yeterlidir; ancak çalışması için ana yapılandırmada ilgili dizin için AllowOverride AuthConfig (veya AllowOverride All) tanımlı olması gerekir. Aksi halde Apache, .htaccess içindeki kimlik doğrulama direktiflerini tamamen yok sayar ve dizin korumasız kalır. Bu ayar unutulduğunda dosyanın 'çalışmadığı' düşünülüp hash veya yol sorgulanmaya başlanır; oysa sorun çoğunlukla AllowOverride satırındadır.

Nginx tarafında yapılandırma

Nginx, .htaccess gibi dizin bazlı geçersiz kılma dosyalarını desteklemez; tüm yapılandırma server veya location bloğunun içinde tanımlanır. Basic Auth için iki direktif yeterlidir: auth_basic, tarayıcıda gösterilecek realm metnini belirler (devre dışı bırakmak için off değeri kullanılabilir); auth_basic_user_file ise .htpasswd dosyasının sunucudaki yolunu gösterir.

location /protected {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Belirli bir alt dizini değil tüm siteyi korumak isterseniz aynı iki satırı location bloğu yerine doğrudan server bloğunun içine yazabilirsiniz. Apache'nin .htaccess dosyasından farklı olarak, Nginx'te yapılan her değişiklik yapılandırma yeniden yüklenene (nginx -s reload) kadar etkili olmaz; bu nedenle değişiklik sonrası servisin haberdar edilmesi gerektiği unutulmamalıdır.

Sık yapılan hatalar

Basic Auth doğru kurulduğunda, uygulama koduna dokunmadan eklenen basit ama etkili bir erişim engelidir. Tek satırlık bir yapılandırma hatası — yanlış yol, unutulan AllowOverride, HTTP üzerinden yayın — bu korumayı anlamsız hale getirebileceğinden, hem .htpasswd satırını hem de sunucu tarafı direktifleri kurulumdan sonra tarayıcıdan test etmek gerekir.

.htpasswd Oluşturucu

Kullanıcı adı ve şifreden Apache/Nginx için {SHA} formatında .htpasswd satırı üretin; hash tarayıcınızda hesaplanır, şifreniz hiçbir yere gönderilmez.