API Güvenliği & Kimlik Doğrulama 29 okunma

API Key, OAuth2 ve Client Credentials

API Key, OAuth2 Client Credentials ve mTLS ile API güvenliği yöntemlerinin karşılaştırması; güvenlik seviyeleri, kullanım senaryoları, .NET'te uygulama stratejileri ve en iyi pratikler ele alınır.

API Key, OAuth2 ve Client Credentials

1. Üç Yöntemin Karşılaştırmalı Analizi

API güvenliğinde doğru yöntemi seçmek, uygulamanızın güvenlik ihtiyaçlarına ve kullanım senaryosuna bağlıdır. Aşağıdaki tablo, üç yöntemi temel boyutlarda karşılaştırmaktadır:

Boyut API Key OAuth2 Client Credentials mTLS
Token/Kimlik Bilgisi Ömrü Manuel döndürme (genellikle uzun ömürlü) 5-60 dakika (kısa ömürlü access token) Sertifika ömrü (saatler-günler, otomatikleştirilebilir)
Sıfır Güven Hazırlığı Hayır Kısmi Evet
Yetkilendirme Esnekliği Yok (yalnızca kimlik doğrulama) Kapsam (scope) tabanlı yetkilendirme Makine kimliği doğrulama
Sızıntı Risk Yönetimi Yüksek (statik, uzun ömürlü) Düşük (kısa ömürlü) Düşük (sertifika bazlı)
Uygulama Karmaşıklığı Çok Düşük Yüksek Orta
İdeal Kullanım Alanı İç API'ler, basit entegrasyonlar Makineden makineye (M2M) iletişim Yüksek güvenlik gerektiren ortamlar

2. API Key Authentication

Nasıl Çalışır? İstemci, isteğe bir API anahtarını (genellikle X-API-Key başlığında veya query parametresinde) ekleyerek kimlik doğrulamasını gerçekleştirir. Sunucu, bu anahtarı doğrular ve geçerliyse isteği kabul eder.

Güçlü Yönleri:

  • Uygulama Kolaylığı: En basit API güvenlik yöntemidir.

  • Düşük Overhead: Minimal işlem maliyeti.

  • Hızlı Entegrasyon: Partner entegrasyonları veya iç servis iletişimi için idealdir.

Zayıf Yönleri:

  • Statik ve Uzun Ömürlü: API anahtarları manuel olarak döndürülmedikçe sonsuza kadar geçerlidir. Bu, sızıntı durumunda uzun süreli bir güvenlik açığı oluşturur.

  • Yetkilendirme Yok: API Key yalnızca kimlik doğrulama sağlar; yetkilendirme (hangi kaynaklara erişileceği) ayrıca yönetilmelidir.

  • Sızıntı Riski: Kod içinde, Git repository'lerinde veya istemci tarafında saklanırsa kolayca ele geçirilebilir.

En İyi Pratikler:

  • Anahtarları asla kod içinde veya Git'te saklamayın.

  • Azure Key Vault, AWS Secrets Manager veya HashiCorp Vault gibi güvenli gizli yöneticileri kullanın.

  • Düzenli anahtar döndürme (rotation) politikası uygulayın (örn. 90 günde bir).

  • Rate limiting, IP beyaz listeleme ve izleme ile ek koruma katmanları ekleyin.

  • Sadece HTTPS üzerinden iletin.

.NET'te API Key Authentication Uygulaması:

csharp

// Program.cs - Özel Authentication Handler ile
public class ApiKeyAuthenticationHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    private const string ApiKeyHeaderName = "X-API-Key";
    private readonly IConfiguration _configuration;

    public ApiKeyAuthenticationHandler(
        IOptionsMonitor<AuthenticationSchemeOptions> options,
        ILoggerFactory logger,
        UrlEncoder encoder,
        ISystemClock clock,
        IConfiguration configuration)
        : base(options, logger, encoder, clock)
    {
        _configuration = configuration;
    }

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.TryGetValue(ApiKeyHeaderName, out var apiKeyHeader))
        {
            return Task.FromResult(AuthenticateResult.Fail("API Key eksik."));
        }

        var apiKey = apiKeyHeader.ToString();
        var validApiKey = _configuration["ApiKey"];

        if (apiKey != validApiKey)
        {
            return Task.FromResult(AuthenticateResult.Fail("Geçersiz API Key."));
        }

        var claims = new[] { new Claim(ClaimTypes.Name, "ApiClient") };
        var identity = new ClaimsIdentity(claims, Scheme.Name);
        var principal = new ClaimsPrincipal(identity);
        var ticket = new AuthenticationTicket(principal, Scheme.Name);

        return Task.FromResult(AuthenticateResult.Success(ticket));
    }
}

// Program.cs - Servis kaydı
builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = "ApiKey";
    options.DefaultChallengeScheme = "ApiKey";
})
.AddScheme<AuthenticationSchemeOptions, ApiKeyAuthenticationHandler>("ApiKey", null);

3. OAuth2 Client Credentials Flow

Nasıl Çalışır? Client Credentials flow, kullanıcı olmadan, makineden makineye (machine-to-machine) iletişim için tasarlanmış bir OAuth2 akışıdır. Bir servis (istemci), kendi kimlik bilgileriyle (client id ve client secret veya sertifika) doğrudan yetkilendirme sunucusuna (authorization server) kimlik doğrulaması yaparak bir access token alır. Bu token daha sonra API çağrılarında Bearer token olarak kullanılır.

Güçlü Yönleri:

  • Kısa Ömürlü Token'lar: Access token'lar tipik olarak 5-60 dakika arasında sona erer, bu da sızıntı durumunda risk penceresini önemli ölçüde azaltır.

  • Yetkilendirme Desteği: Kapsam (scope) tabanlı yetkilendirme ile hangi kaynaklara erişileceği kontrol edilebilir.

  • Sıfır Güven Uyumlu: Kısa ömürlü token'lar ile sıfır güven mimarisine daha uygundur.

  • Daha Güvenli: API Key'e kıyasla sızıntıya karşı daha dayanıklıdır.

Zayıf Yönleri:

  • Karmaşıklık: Uygulaması API Key'e göre daha karmaşıktır.

  • Ek Altyapı: Bir yetkilendirme sunucusu (Identity Server, Entra ID, vb.) gerektirir.

.NET'te Client Credentials Uygulaması (Microsoft Entra ID ile):

csharp

// 1. NuGet paketleri
// Microsoft.Identity.Web
// Microsoft.Identity.Client

// 2. Program.cs - Servis kaydı
using Microsoft.Identity.Web;

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

// 3. appsettings.json
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret" // veya sertifika
  }
}

Client Credentials ile Token Alma (Daemon Uygulaması):

csharp

using Microsoft.Identity.Client;

// Client Credentials flow ile token alma[reference:37]
var app = ConfidentialClientApplicationBuilder
    .Create(clientId)
    .WithClientSecret(clientSecret)
    .WithAuthority(new Uri($"https://login.microsoftonline.com/{tenantId}"))
    .Build();

string[] scopes = new[] { "https://api.example.com/.default" }; // API'nin scope'u[reference:38]

var result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();

var accessToken = result.AccessToken;

// Token'ı HttpClient ile kullanma
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", accessToken);

OpenIddict ile Client Credentials Flow (Kendi Identity Sunucunuz):

csharp

// OpenIddict ile Client Credentials flow'u etkinleştirme[reference:39]
builder.Services.AddOpenIddict()
    .AddCore(options => { /* ... */ })
    .AddServer(options =>
    {
        options.AllowClientCredentialsFlow(); // Client Credentials akışını etkinleştir
        // ... diğer yapılandırmalar
    });

4. mTLS (Mutual TLS)

Nasıl Çalışır? mTLS, istemci ve sunucu arasında karşılıklı sertifika doğrulaması sağlar. Hem sunucu hem de istemci kendi sertifikalarını sunar ve karşılıklı olarak doğrular.

Güçlü Yönleri:

  • En Yüksek Güvenlik: Sertifika tabanlı kimlik doğrulama, en güçlü güvenlik mekanizmalarından biridir.

  • Sıfır Güven Uyumlu: mTLS, sıfır güven mimarisinin temel yapı taşlarından biridir.

  • Otomatik Döndürme: Sertifikalar otomatikleştirilebilir ve kısa ömürlü olabilir.

Zayıf Yönleri:

  • Operasyonel Karmaşıklık: Sertifika yönetimi (dağıtım, yenileme, iptal) ek yük getirir.

  • Altyapı Gereksinimi: Sertifika otoritesi (CA) ve PKI altyapısı gerektirir.

mTLS ile API Güvenliği, bankacılık sistemleri ve yüksek güvenlik gerektiren ortamlar için tercih edilen yöntemdir.

5. Hangisi Ne Zaman Kullanılmalı?

Senaryo Önerilen Yöntem Açıklama
İç API'ler ve Basit Entegrasyonlar API Key Düşük karmaşıklık, hızlı uygulama
Partner/Üçüncü Taraf Entegrasyonları OAuth2 Client Credentials Daha güvenli, yetkilendirme ve audit desteği
Mikroservisler Arası İletişim OAuth2 Client Credentials veya mTLS Yüksek güvenlik, sıfır güven uyumu
Kullanıcı Temsilcisi (User Delegation) OAuth2 Authorization Code Flow Kullanıcı oturumu ve yetkilendirme gerektiğinde
Çok Yüksek Güvenlik Gereksinimleri mTLS Bankacılık, kritik altyapı

Önemli Not: API Key auth, genellikle "underrated" (hafife alınan) bir yöntem olarak görülse de, tam OAuth2'nin fazla geldiği iç servis iletişimi için pratik bir çözüm olabilir. Ancak, hassas verilere erişen veya dışa açık API'ler için OAuth2 veya mTLS gibi daha güçlü yöntemler tercih edilmelidir.

6. Güvenlik En İyi Pratikleri

  1. Her Zaman HTTPS Kullanın: Tüm API iletişimi HTTPS üzerinden şifrelenmelidir.

  2. Token/Kimlik Bilgilerini Asla Kaydetmeyin: API anahtarlarını, secret'ları ve sertifikaları kod içinde, Git'te veya log'larda saklamayın.

  3. Güvenli Gizli Yöneticileri Kullanın: Azure Key Vault, AWS Secrets Manager veya HashiCorp Vault tercih edin.

  4. Düzenli Döndürme (Rotation): API anahtarlarını ve sertifikaları düzenli aralıklarla yenileyin.

  5. Rate Limiting ve İzleme: Anormal aktiviteleri tespit etmek için rate limiting, IP beyaz listeleme ve izleme uygulayın.

  6. Scope Tabanlı Yetkilendirme: OAuth2 kullanırken en az ayrıcalık prensibine uygun scopes tanımlayın.

Sonuç

API Key, OAuth2 Client Credentials ve mTLS arasındaki seçim, güvenlik ihtiyacı, uygulama karmaşıklığı ve kullanım senaryosuna bağlıdır. API Key, basit ve hızlı çözümler için idealken; OAuth2 Client Credentials, makineden makineye iletişimde daha güvenli ve yetkilendirme desteği sunar. mTLS ise en yüksek güvenlik seviyesini gerektiren kritik sistemler için tercih edilir. .NET ekosistemi, bu üç yöntemi de rahatça uygulayabileceğiniz zengin araçlar ve kütüphaneler sunmaktadır.

Tüm yazılar