Geliştirici Güvenliği•7 dk okuma•

API Anahtarı ve Secret Token Güvenliği Rehberi

API anahtarı güvenliği: kod içi anahtar riski, .env ve vault ile saklama, rotasyon, sızan anahtara acil müdahale ve CSPRNG ile güvenli token üretimi.

API anahtarları ve secret token'lar, modern yazılım altyapısının en kritik ama en sık ihmal edilen bileşenlerinden biridir. Bir parolayı unutan kullanıcı şifresini sıfırlayabilir; sızan bir API anahtarı ise gece boyunca fatura ödeyen, veri çeken veya sistemi kilitleyen bir makineye dönüşür. Bu rehber, uygulama sırlarını (secrets) doğru oluşturmayı, saklamayı, rotasyona tabi tutmayı ve sızıldığında müdahale etmeyi adım adım anlatır.

API Anahtarı ve Secret Token Nedir?

API anahtarı, bir uygulamanın başka bir servise kimliğini kanıtlamak için kullandığı uzun, rastgele bir dizidir. Secret token ise bu ailenin daha geniş adıdır: webhook imza anahtarları, veritabanı bağlantı cümleleri, servis hesabı kimlik bilgileri, JWT imzalama anahtarları ve TLS özel anahtarları da aynı kategoriye girer.

İnsan parolasından temel farkı şudur: API anahtarı ezberlenmez, saklanır. Bir kişi "Trabzon-34!" gibi hatırlanabilir bir parola seçer; bir uygulama ise 32-64 karakterlik tamamen rastgele bir dizgi kullanır. Bu yüzden güvenlik stratejisi de farklıdır. İnsan parolalarında sorun "hatırlanabilirlik ve tahmin edilebilirlik" iken, makine sırlarında sorun oluşturma, saklama ve döngüsel yenileme süreçleridir.

En Büyük Güvenlik Açığı: Hardcoded (Kod İçi) Anahtarlar

Sızan anahtarların en yaygın kaynağı, anahtarın doğrudan kaynak koda yazılmasıdır:

const API_KEY = "sk-live-9f2b7c..."; // asla böyle yapmayın

Bu yaklaşım üç nedenden ölümcüldür:

  • Git geçmişi silmez. Anahtarı sonraki bir commit ile kaldırsanız bile, geçmişteki her sürümde durmaya devam eder. Depoyu klonlayan herkes eski commit'lere bakabilir.
  • Herkese açık depolar taranır. GitHub'daki herkese açık depoları anahtar deseni arayan otomatik tarayıcılar sürekli gezer. Yanlışlıkla push edilen bir anahtarın sızdığını varsaymak, en gerçekçi yaklaşımdır.
  • Kod nereye giderse anahtar da gider. Mobil uygulamaların paketinden çıkarılabilir, Docker imajlarının katmanlarında bulunabilir, istemci tarafı JavaScript'te herkese görünür, hata mesajlarında ve log dosyalarında iz bırakabilir.

Kural basittir: Bir anahtar kaynak koda girdiyse, artık gizli değildir. Aynı durum .env dosyasını .gitignore'a eklemeden commit etmek için de geçerlidir.

Gizli Anahtarları Güvenli Saklama Yöntemleri (.env ve Vault Sistemleri)

Sırların saklanmasında olgunluk seviyeleri vardır. Her proje vault'a ihtiyaç duymaz, ama hiçbir proje anahtarı kodda tutmamalıdır.

Yöntem Uygun senaryo Sınırlamalar
.env + .gitignore Tek geliştiricinin yerel ortamı Dağıtımı elle yapılır, denetim izi yoktur
CI/CD gizli değişkenleri Build ve deploy süreçleri Yalnızca pipeline kapsamında erişilir
Secret manager (Vault, AWS Secrets Manager, Azure Key Vault, Google Secret Manager) Ekip ve üretim ortamları Kurulum gerektirir; en güçlü seçenek

Pratik öneriler:

  • Depoya yalnızca anahtar adlarını içeren, değerleri boş bir .env.example dosyası koyun.
  • .env dosyasının dosya izinlerini daraltın (ör. yalnızca sahip okuyabilir).
  • Üretimde merkezi bir secret manager kullanın; erişim yetkileri, denetim kayıtları ve otomatik rotasyon gibi olanaklar bu sistemlerin asıl değeridir.
  • Ekip içi sırlar için geliştirici odaklı çözümler (ör. ekip parola yöneticilerinin secret paylaşımı) küçük ekipler için makul bir ara adımdır.

Token Rotasyonu Nedir ve Neden Gereklidir?

Rotasyon, bir anahtarı belirli aralıklarla veya belirli olaylarda yeni bir anahtarla değiştirmektir. Amaç, sızma ihtimali olsa bile anahtarın kullanılabilirlik penceresini kısaltmaktır.

Rotasyonu zorunlu kılan tipik durumlar:

  • Anahtara erişimi olan personelin ayrılması veya rol değişikliği
  • Şüpheli erişim kayıtları
  • Taşınan, yeniden yapılandırılan veya ihale edilen sistemler
  • Sözleşme ve uyumluluk gereksinimleri

Sıfır kesintili rotasyonun standart deseni şudur:

  1. Yeni anahtarı oluşturun ve servise tanıtın (eski anahtar hâlâ aktif).
  2. Tüm tüketen servisleri yeni anahtara geçirin.
  3. Eski anahtarın son kullanımını loglardan doğrulayın.
  4. Eski anahtarı iptal edin ve değişikliği belgelendirin.

Rotasyon sıklığı için evrensel bir sayı yoktur; risk seviyesine, anahtarın eriştiği verinin hassasiyetine ve sağlayıcının politikasına göre belirlenir. Önemli olan, rotasyonun belgelenmiş ve tekrarlanabilir bir süreç olmasıdır.

Sızan Bir API Anahtarı Tespit Edildiğinde Acil Müdahale Planı

Bir anahtarın sızdığını öğrendiğinizde panik yerine kontrol listesi uygulayın:

  1. İptal edin. Önce iptal, sonra inceleme. Kullanımda kesinti oluşsa bile, ihlal maliyeti neredeyse her zaman daha yüksektir.
  2. Yeni anahtar oluşturun ve tüketen servisleri güncelleyin.
  3. Kötüye kullanımı denetleyin. Sağlayıcının kullanım loglarını, alışılmadık IP'ler, ani istek artışları ve yetki dışı işlemler için inceleyin.
  4. Git geçmişini temizleyin. git filter-repo veya BFG Repo-Cleaner gibi araçlarla anahtarı geçmişten kaldırın — ancak bunun sızıntıyı geri almadığını, yalnızca gelecekteki keşfi zorlaştırdığını bilin. Gerçek çözüm 1. adımdır.
  5. Kök nedeni araştırın. Anahtar nasıl sızdı: commit mi, log mu, yetkisiz erişim mi? Sızıntı tarama araçları (ör. gitleaks, trufflehog) commit öncesi kontrol olarak sürece eklenebilir.
  6. Gerekirse bildirimde bulunun. Sızan anahtar müşteri verisine erişebiliyorsa, yasal ve etik yükümlülükler devreye girer.

Minimum Yetki Prensibi (Least Privilege) ile Erişim Yönetimi

Bir anahtar sızsa bile verebileceği hasar, o anahtara verdiğiniz yetkiyle sınırlıdır. Bu yüzden her anahtarı ihtiyacı olan en dar yetkiyle oluşturun:

  • Yalnızca okuma yeterliyse yazma izni vermeyin.
  • Anahtarı belirli kaynaklara (tek kova, tek servis, tek veri tabanı) bağlayın.
  • Mümkünse IP kısıtlaması ve son kullanma tarihi tanımlayın.
  • Geliştirme, test ve üretim ortamları için ayrı anahtarlar kullanın; geliştirme anahtarı üretim verisine dokunmamalı.
  • Ana hesabın (root/admin) API anahtarını rutin işlerde asla kullanmayın.
  • Kullanılmayan anahtarları düzenli olarak listeleyin ve silin.

Kriptografik Token Oluştururken Dikkat Edilmesi Gerekenler

Anahtarın kendisi rastgele değilse, saklama çabanız anlamsızdır. Oluşturma aşamasında şu kurallara uyun:

  • CSPRNG kullanın. Math.random() gibi tahmin edilebilir üreteçler token üretimi için uygun değildir; tarayıcıda crypto.getRandomValues, sunucu tarafında işletim sisteminin kriptografik rastgelelik kaynağı kullanılmalıdır.
  • Yeterli entropi hedefleyin. Uzun ömürlü sırlar için en az 128 bit, yaygın uygulamada 256 bit rastgelelik makuldür. UUID v4 yaklaşık 122 bit rastgelelik içerir; kimlik belirteci olarak yeterlidir, ancak imza anahtarı olarak daha uzun bir secret tercih edilir.
  • Üretilen değeri kısaltmayın ve dönüştürmeyin. Base64URL veya hex gibi standart kodlamalar kullanın; kendi kodlama yöntemlerinizi oluşturmanız, standart dışı sonuçlara ve potansiyel güvenlik zafiyetlerine yol açabilir.
  • Güvenilir ortamda üretin. Anahtar, üretildiği andan itibaren gizlidir; üçüncü taraf bir web sitesine giren bir token artık güvenli sayılmaz.

Bu işlemleri tarayıcınızda, hiçbir verinin sunucuya gönderilmeden gerçekleştirmek isterseniz UK Bilişim'in Token Oluşturucu aracını kullanabilirsiniz: UUID v4, hex ve Base64URL formatlarında, tamamen yerel çalışan kriptografik üretim sunar.

Sık Sorulan Sorular

API anahtarı ile parola arasındaki fark nedir? Parola bir insanın kimliğini kanıtlar ve ezberlenebilir olması beklenir; API anahtarı bir uygulamanın kimliğini kanıtlar ve rastgele, uzun, saklanan bir dizgidir. Bu yüzden parolalarda tahmin edilebilirlik, anahtarlarda ise saklama ve rotasyon ana risktir.

.env dosyam yanlışlıkla commit edildi, ne yapmalıyım? Önce anahtarı iptal edin, sonra yeni anahtar oluşturup servisleri güncelleyin. Ardından git geçmişini temizlik araçlarından geçirebilirsiniz. Geçmişi temizlemek sızıntıyı geri almaz; iptal etmek geri alır.

Anahtarlar ne sıklıkla rotasyona tabi tutulmalı? Evrensel bir süre yoktur. Personel değişiklikleri, şüpheli aktivite ve uyumluluk gereksinimleri tetikleyicidir. Önemli olan, ihtiyaç anında uygulanabilen belgelenmiş bir rotasyon sürecinin hazır olmasıdır.

Math.random() ile token üretmek neden yeterli değil? Math.random() kriptografik güvenlik için tasarlanmamıştır; çıktısı tahmin edilebilir olabilir ve ürettiği değer bir saldırganın yeniden türetmesine açıktır. Token'lar mutlaka CSPRNG ile üretilmelidir.

Sızan anahtarın kötüye kullanılıp kullanılmadığını nasıl anlarım? Sağlayıcının denetim kayıtlarını bilinen kullanım deseninizle karşılaştırın: alışılmadık IP adresleri, coğrafi anomaliler, istek hacminde ani sıçramalar ve yetki dışı uç noktalara erişim arayın.

Güçlü bir güvenlik zinciri, güçlü rastgele üretimle başlar. İnsan parolalarınız için tamamen tarayıcınızda çalışan Şifre Oluşturucuyu, bir parolanın sızıntı listelerinde geçip geçmediğini görmek için Sızıntı Kontrolü aracını kullanabilirsiniz.

Güçlü Parolanızı Hemen Oluşturun

Cihazınızın Web Crypto motoruyla sıfır log ve sıfır veri transferi.

Şifre Oluşturucuya Git →