NextQuantumSystem.Protect.SwaggerGuard 1.0.0

NextQuantumSystem.Protect — SwaggerGuard

Swagger UI'yi ve ilişkili endpoint'leri JWT + rol geçidinin arkasına alan, DLL olarak her projeye takılabilen yeniden kullanılabilir koruma modülü.

İçindekiler

1. Amaç — Neden & Niçin
2. Nasıl Çalışır — Akış
3. Mimari
4. Kurulum & Kullanım
5. Konfigürasyon Referansı
6. Güvenlik Notları
7. Test
8. Sık Sorulanlar
9. Sürüm Geçmişi

1. Amaç — Neden & Niçin

Problem

ABP / ASP.NET Core projelerinde Swagger UI (/swagger) çoğu zaman herkese açık gelir. Development/staging ortamlarında bu, API şemasının, endpoint listesinin ve örnek payload'ların yetkisiz kişilere sızması demektir.

Çözüm

Swagger direkt açılmaz. Yerine token giriş sayfası çıkar; kullanıcı geçerli bir JWT girer, token imzası + issuer + expiry doğrulanır ve yalnızca izin verilen rollere (AllowedRoles) sahip kullanıcılar Swagger'a erişebilir.

Neden ayrı bir modül / DLL?

Aynı korumayı onlarca mikroservise kopyala-yapıştır yapmak yerine, tek bir DLL'i her projeye takıp her serviste tutarlı koruma sağlanır (defense-in-depth: her servis kendini korur, sadece gateway'e güvenilmez). Her proje sadece kendi appsettings.json'ındaki değerleri değiştirir; kod ve DLL aynı kalır, yeniden derleme gerekmez.

2. Nasıl Çalışır — Akış

İstek  ──▶  SwaggerProtectionMiddleware
                │
                ├─ IsEnabled=false?  ──▶ dokunma, geç
                │
                ├─ Yol == TokenInputPath (auth/swagger)?
                │     ├─ GET  ──▶ token giriş sayfasını göster (200)
                │     └─ POST ──▶ token doğrula
                │                   ├─ geçersiz/expired ──▶ sayfa + 401
                │                   ├─ rol uygun değil   ──▶ sayfa + 403
                │                   └─ geçerli+rol OK ──▶ cookie yaz + returnUrl'e 302
                │
                ├─ Yol ProtectedPaths içinde değil? ──▶ geç
                │
                └─ Korunan yol:
                      ├─ cookie yok       ──▶ giriş sayfasına 302
                      ├─ cookie geçersiz  ──▶ cookie sil + giriş sayfasına 302
                      ├─ rol uygun değil  ──▶ 403
                      └─ her şey OK       ──▶ Swagger'a geç

Cookie: doğrulanan token __auth_token adıyla, HttpOnly + Secure (HTTPS'te) + SameSite=Lax + CookieExpirationHours süreli olarak yazılır.

3. Mimari

Karar: çekirdek ABP'den bağımsız, böylece hem ABP hem düz ASP.NET Core host'lar kullanabilir. ABP tarafı ince bir sarmalayıcıdır.

Protect/
├── src/
│   ├── NextQuantumSystem.Protect.SwaggerGuard/          ← ABP'siz düz çekirdek
│   │   ├── SwaggerProtectionOptions.cs                  · tüm ayarlar
│   │   ├── SwaggerProtectionMiddleware.cs               · path/cookie/rol/redirect mantığı
│   │   ├── SwaggerProtectionExtensions.cs               · AddSwaggerProtection / UseSwaggerProtection
│   │   └── Internal/
│   │       ├── IJwtTokenValidator.cs                    · doğrulama soyutlaması
│   │       ├── JwksJwtTokenValidator.cs                 · Authority/JWKS ile imza doğrulama
│   │       └── TokenInputPageRenderer.cs                · token giriş sayfası (HTML)
│   │
│   └── NextQuantumSystem.Protect.SwaggerGuard.Abp/      ← ince ABP modülü
│       └── ProtectSwaggerGuardModule.cs                 · AbpModule, otomatik wiring
│
└── test/
    └── NextQuantumSystem.Protect.SwaggerGuard.Tests/    ← in-memory TestServer, 10 test

4. Kurulum & Kullanım

4.a) ABP Host

1. Referans ver (proje referansı veya DLL/NuGet):

NextQuantumSystem.Protect.SwaggerGuard.Abp

2. Modülü bağımlılık olarak ekle:

[DependsOn(
    typeof(ProtectSwaggerGuardModule)   // ← tek satır, gerisi otomatik
    // ... diğer modülleriniz
)]
public class MyServiceHttpApiHostModule : AbpModule { }

3. appsettings.json'a "Swagger" bölümünü ekle (bkz. Konfigürasyon).

Middleware, modül host'un bağımlılığı olduğu için host'un kendi UseAbpSwaggerUI() çağrısından önce kaydolur (ABP init sırası: bağımlılıklar önce). Ekstra bir Use... çağrısı gerekmez.

4.b) Düz ASP.NET Core Host

1. Referans ver:

NextQuantumSystem.Protect.SwaggerGuard

2. Program.cs:

var builder = WebApplication.CreateBuilder(args);

// "Swagger" bölümünden bind eder
builder.Services.AddSwaggerProtection(builder.Configuration);

var app = builder.Build();

app.UseSwaggerProtection();   // ← Swagger UI'DEN ÖNCE
app.UseSwagger();
app.UseSwaggerUI();

app.Run();

Alternatif kayıt yöntemleri:

// Belirli bir bölümden
services.AddSwaggerProtection(builder.Configuration.GetSection("Swagger"));

// Kod içi (sabit değerler koda, değişkenler config'e)
services.AddSwaggerProtection(o =>
{
    o.Authority = "https://id.example.com";
    o.ProtectedPaths = new() { "swagger", "swagger/v1/swagger.json" };
    o.AllowedRoles   = new() { "admin" };
});

5. Konfigürasyon Referansı

appsettings.json içindeki "Swagger" bölümü SwaggerProtectionOptions'a bind edilir.

{
  "Swagger": {
    "IsEnabled": true,
    "RoutePrefix": "swagger",
    "DocumentTitle": "API Dokümanı",
    "CookieName": "__auth_token",
    "CookieExpirationHours": 8,
    "TokenInputPath": "auth/swagger",
    "ProtectedPaths": [
      "swagger",
      "api/abp/api-definition",
      "swagger/v1/swagger.json"
    ],
    "AllowedRoles": ["admin"],

    "Authority": "https://id.example.com",
    "Audience": "my-service",
    "ValidateAudience": false,
    "ValidateIssuer": true,
    "RequireHttpsMetadata": true,
    "RoleClaimTypes": ["role", "roles"]
  }
}

Her projede değişen değerler (Authority, Audience) DLL içinde değil, her host'un kendi config'inde tutulur. Tekrarı azaltmak için: ortak appsettings.shared.json, environment variable (Swagger__Authority=...) veya kod-içi AddSwaggerProtection(o => ...) overload'u kullanılabilir.

📄 Tam örnek + açıklamalı senaryolar: samples/appsettings.Swagger.sample.jsonc — her ayarın satır-içi açıklaması ve 5 hazır senaryo (production, development, rol-kısıtsız, audience-doğrulamalı, kapalı).

6. Güvenlik Notları

• 🔴 JWT imzası MUTLAKA doğrulanır. Authority yapılandırılmazsa doğrulama başarısız döner — token asla "sadece decode edilip" kabul edilmez. Bu, saldırganın kendi role=admin token'ını üretmesini engeller. İmza + issuer + expiry hep doğrulanır.
• 🔁 Sonsuz redirect koruması: TokenInputPath asla korunan değildir; kendi içinde ele alınır.
• 🍪 Cookie: HttpOnly (JS erişemez) + Secure (HTTPS'te) + SameSite=Lax. Bayat/geçersiz cookie otomatik silinir.
• ↩️ Open-redirect koruması: returnUrl yalnızca site-içi (yerel) yollara izin verir; // veya mutlak URL'ler reddedilir.
• ⚠️ api/abp/api-definition'ı korumak, ABP dinamik client-proxy üretimini etkileyebilir (cookie'siz çağıran araçlar 302 alır). Bilinçli tercih olmalı.
• 🌐 Gateway/reverse-proxy: X-Forwarded-* / PathBase algılanan yolu değiştirebilir; ProtectedPaths eşleştirmesi buna göre ayarlanmalı.

7. Test

In-memory TestServer üzerinde gerçek HTTP akışıyla 10 integration testi (test/NextQuantumSystem.Protect.SwaggerGuard.Tests). JWKS yerine simetrik anahtarlı bir doğrulayıcı enjekte edilerek tüm middleware mantığı sınanır.

dotnet test NextQuantumSystem.Protect.slnx

Sonuç: 10/10 geçiyor.

8. Sık Sorulanlar

S: Bu bir ABP modülü mü, yoksa düz kütüphane mi? İkisi de. Çekirdek (SwaggerGuard) ABP'siz düz kütüphanedir; SwaggerGuard.Abp onu ABP host'ları için otomatik wire eden ince bir modüldür.

S: Her mikroservis için ayrı DLL derlemek gerekir mi? Hayır. Aynı DLL tüm projelerde kullanılır; sadece appsettings.json değişir.

S: Bu proje neden 8 katmanlı ABP şablonu değil? Swagger koruması bir middleware işidir; Domain/EF/Application katmanları gerekmez. Şablon, sadece bu üç projeye sadeleştirildi. İleride DB gerektiren özellik eklenirse ilgili katman ABP CLI/Studio ile ya da git geçmişinden geri getirilebilir.

9. Sürüm Geçmişi

1.0.0 — 2026-07-18

• İlk sürüm.
• SwaggerProtectionMiddleware: path eşleştirme, cookie tabanlı JWT geçidi, rol kontrolü, redirect akışı.
• JwksJwtTokenValidator: Authority/JWKS ile imza + issuer + expiry doğrulaması.
• Token giriş sayfası (MVC'siz, HTML render).
• Düz ASP.NET Core için AddSwaggerProtection / UseSwaggerProtection extension'ları.
• ABP host'ları için ProtectSwaggerGuardModule (tek [DependsOn] ile otomatik wiring).
• 10 integration testi (in-memory TestServer).
• ABP DDD şablon katmanları (Domain, Application, EntityFrameworkCore, HttpApi, HttpApi.Client, Installer) bu amaç için gereksiz olduğundan çıkarıldı.