API Key, OAuth2 ve Client Credentials ile API Güvenliği

API Key, OAuth2 ve Client Credentials ile API Güvenliği

API'lerinizi korumak için doğru kimlik doğrulama mekanizmasını seçmek, güvenlik ile operasyonel basitlik arasında bir denge kurmaktır. API Key, OAuth2 Client Credentials ve mTLS, makineden makineye (M2M) iletişimde en yaygın kullanılan üç yaklaşımdır. Her biri farklı güven seviyeleri ve farklı risk profilleri sunar.

1. API Key: Basit ama Sınırlı

API Key, istemcinin her isteğe eklediği statik bir dizedir. Genellikle X-API-Key veya Authorization başlığında taşınır.

Güçlü Yönleri:

Entegrasyon Kolaylığı: Tek bir başlık eklemek yeterlidir; token exchange akışı yoktur .
Hızlı Başlangıç: Geliştiriciler, dashboard'dan anahtarı alıp dakikalar içinde ilk çağrıyı yapabilir .

Zayıf Yönleri:

Uzun Ömürlü ve Statik: Anahtar, manuel olarak döndürülene kadar geçerlidir. Sızıntı durumunda risk penceresi çok geniştir .
Kimlik ve Yetkilendirme Yok: API anahtarı, isteği yapan kullanıcıyı veya uygulamayı tam olarak tanımlamaz; yalnızca "bir anahtar" olduğunu doğrular .
Sızıntı Riski: İstemci tarafında (mobil uygulama, tarayıcı) kolayca ele geçirilebilir .

Ne Zaman Kullanılır?

Düşük riskli, iç ağdaki mikroservisler .
Hızlı prototipleme veya geliştirici onboarding'i.
OAuth altyapısının maliyetinin faydayı aşacağı basit senaryolar.

ASP.NET Core'da Uygulama: AspNetCore.Authentication.ApiKey gibi kütüphaneler veya özel middleware ile kolayca eklenir . Anahtarlar asla kodda saklanmamalı; environment variable veya secret manager kullanılmalıdır .

2. OAuth2 Client Credentials: M2M için Standart

Client Credentials, kullanıcı etkileşimi olmadan çalışan servislerin (daemon, batch job) bir yetkilendirme sunucusundan kısa ömürlü access token almasını sağlayan OAuth2 akışıdır .

Güçlü Yönleri:

Kısa Ömürlü Token: Access token'lar genellikle 1 saat içinde sona erer; sızıntı durumunda risk penceresi dardır .
Scope Tabanlı Yetkilendirme: Token, yalnızca belirli izinleri (ör. metrics.read) taşır; ele geçirilse bile sınırlı işlem yapılabilir .
Standart ve Ölçeklenebilir: RFC 6749 ile tanımlıdır; kurumsal OAuth altyapılarıyla uyumludur .

Zayıf Yönleri:

Altyapı Gereksinimi: Bir yetkilendirme sunucusu (IdentityServer, Entra ID, Keycloak) gerekir .
Client Secret Hala Uzun Ömürlü: Token'lar kısa ömürlü olsa da, token almak için kullanılan client_secret döndürülene kadar geçerlidir .
İstemci Karmaşıklığı: Token exchange, cache ve expiry yönetimi ek kod gerektirir .

Ne Zaman Kullanılır?

Kurumlar arası entegrasyonlar (SaaS API tüketimi) .
Güven sınırını aşan tüm servis-servis trafiği .
Kurumsal müşterilerin OAuth tabanlı erişim kontrolü talep ettiği durumlar .

ASP.NET Core'da Uygulama: AddJwtBearer ile token doğrulama yapılandırılır; [Authorize(Policy = "...")] ile scope kontrolü eklenir . Token almak için Microsoft.Identity.Client veya Duende'nin AccessTokenManagement kütüphanesi kullanılabilir .

3. mTLS: En Yüksek Güvenlik

mTLS (Mutual TLS), hem istemcinin hem sunucunun X.509 sertifikası ile birbirini doğruladığı en güvenli yöntemdir.

Ne Zaman Kullanılır?

Bankacılık, sağlık, hassas devlet sistemleri .
Sıfır güven (zero-trust) mimarilerinde her servis-servis atlamasının kriptografik olarak doğrulanması gerektiğinde .

Dezavantajı: Sertifika yaşam döngüsü yönetimi, rotasyon ve hata ayıklama operasyonel olarak maliyetlidir .

4. Karşılaştırma ve Karar Rehberi

Kriter	API Key	OAuth2 Client Credentials	mTLS
Güvenlik Seviyesi	Düşük	Yüksek	En Yüksek
Token Ömrü	Uzun (manuel döndürme)	Kısa (1 saat)	Sertifika ömrü
Yetkilendirme	Yok	Scope tabanlı	Sertifika bazlı
Altyapı Maliyeti	Çok düşük	Orta-Yüksek	Yüksek
Entegrasyon Kolaylığı	Çok kolay	Orta	Zor

Pratik Öneri (2026):

Dış entegrasyonlar (Stripe, Twilio): OAuth2 Client Credentials (sağlayıcının kendi auth server'ı ile) .
Kendi API'niz, müşteri uygulamaları: OAuth2 Client Credentials (kendi auth server'ınız, müşteri bazlı scope) .
İç servisler (aynı VPC): mTLS (service mesh ile) + uygulama seviyesinde scope'lu JWT .
Düşük riskli iç trafik: API Key (döndürme planı belgelenmiş şekilde) .

5. En İyi Pratikler

Pratik	Açıklama
API anahtarlarını 90 günde bir döndürün	Sızıntı riskini azaltır .
Client secret'ı asla log'lamayın	Token'lar ve secret'lar log adapter'ında maskelenmelidir .
Token'ı memory'de cache'leyin	Disk veya Redis'te kalıcı cache, invalidation sorunlarına yol açar .
Clock skew'e karşı önlem alın	Token süresi dolmadan 60 saniye önce yenileyin .
Eşzamanlı yenileme fırtınasını önleyin	Token expiry anında yüzlerce istek aynı anda yenileme yapmasın; kilit kullanın .
En az ayrıcalık (least privilege)	API anahtarlarını yalnızca gerekli API'lere kısıtlayın .

Sonuç

API güvenliğinde "tek doğru" yoktur; doğru seçim, risk seviyesine ve operasyonel kapasiteye bağlıdır. API Key, hızlı ve düşük riskli entegrasyonlar için pratiktir; ancak yüksek güvenlik gerektiren sistemlerde asla yeterli değildir. OAuth2 Client Credentials, güven sınırını aşan M2M iletişimde standarttır ve kısa ömürlü token'lar sayesinde sızıntı riskini sınırlar. mTLS ise en yüksek güvenlik seviyesini sunar, ancak operasyonel maliyeti yüksektir. Olgun platformlar genellikle hem API Key (kolay onboarding) hem de Client Credentials (kurumsal güvenlik) sunar . Unutmayın: Güvenlik bir ürün değil, bir süreçtir; anahtarlarınızı döndürün, token'larınızı kısa tutun ve her zaman en az ayrıcalıkla çalışın.

İlgili yazılar