Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) trafiğini harici OIDC sağlayıcılarına yönlendirerek uç kullanıcı kimlik doğrulamasını standartlaştırmak.
- ID token ve access token doğrulamasıyla mikro servislerin kimlik doğrulama yükünü hafifletmek ve güvenliği merkezileştirmek.
- Oturum, cookie ve cache yönetimi sayesinde uzun süreli kullanıcı oturumlarını güvenli biçimde sürdürebilmek.
- Rol haritalama ve header enjeksiyonlarıyla API katmanında ince taneli yetkilendirme kuralları uygulamak.
Çalışma Prensibi
- İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- Politika Kontrolü: OIDC Kimlik Doğrulama politikası aktif ise, sistem aşağıdaki sırayla kontrol yapar:
- Condition (koşul) tanımlı mı? Varsa koşul sağlanıyor mu?
- Politika aktif mi (active=true)?
- Variable kullanılıyor mu yoksa Apinizer default mı?
- OIDC Yetkilendirme Akışı: İstek, seçilen OIDC/OAuth2 flow tipine göre yönlendirilir; issuer/discovery metadatası çekilir, PKCE ve nonce/state değerleri üretilir, token valide edilir.
- Karar Verme:
- Eşleşme Var: Doğrulanmış token’dan kullanıcı bilgileri çıkarılır, header/cookie güncellenir, opsiyonel yetkilendirme servisi tetiklenir ve isteğe izin verilir.
- Eşleşme Yok: Yetkilendirme başarısız olur, tanımlanan hata mesajı veya redirect kuralı uygulanır.
- Hata İşleme: Politika kuralına uymayan istekler için özelleştirilebilir HTTP durum kodu ve hata mesajı döndürülür.
Özellikler ve Yetenekler
Temel Özellikler
- Dinamik OIDC Keşfi: Well-known endpoint üzerinden issuer, JWKS ve diğer metadata bilgilerini otomatik keşfederek manuel yapılandırma ihtiyacını azaltır.
- Çoklu Akış Desteği: Authorization Code, Implicit, Hybrid ve saf OAuth2 Authorization Code akışlarını aynı politikada yönetir; PKCE desteğiyle güvenliği artırır.
- Token Doğrulama Kontrolleri: ID/Access token doğrulaması, imza algoritması kontrolü, kullanıcı bilgisi alma ve API tabanlı token doğrulama seçeneklerini sunar.
- Aktif/Pasif Durum Kontrolü: Politikanın aktif veya pasif durumunu kolayca değiştirme (active/passive toggle). Pasif durumda politika uygulanmaz ancak yapılandırması saklanır.
- Koşul Bazlı Uygulama: Query Builder ile karmaşık koşullar oluşturarak politikanın ne zaman uygulanacağını belirleme (örn: sadece belirli endpoint’lere veya header değerlerine göre).
İleri Düzey Özellikler
- Gelişmiş Oturum Yönetimi: Session cookie adı, timeout, state/nonce doğrulaması, oturum şifreleme ve sıkıştırma ayarları ile kurumsal güvenlik standartlarını karşılar.
- Rol ve Yetkilendirme Entegrasyonu: Rol haritalama, header’a rol ekleme, harici yetkilendirme servisi veya Credential Role Service ile derinlemesine erişim yönetimi sağlar.
- Uyarlanabilir Token Taşıma: Token’ı header, cookie veya her ikisi üzerinden kabul edebilir; bearer formatını zorunlu kılabilir, özel header isimleri kullanabilir.
- Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Development, Test, Production) import etme. Versiyon kontrolü ve yedekleme imkanı.
- Policy Group ve Proxy Group Desteği: Birden fazla politikayı Policy Group içinde yönetme. Proxy Group’lara toplu politika atama. Merkezi güncelleme ve deploy işlemleri.
- Deploy ve Versiyonlama: Politika değişikliklerini canlı ortama deploy etme. Hangi API Proxy’lerde kullanıldığını görme (Policy Usage). Proxy Group ve Policy Group kullanım raporları.
Kullanım Senaryoları
| Senaryo | Durum | Çözüm (Politika Uygulaması) | Beklenen Davranış / Sonuç |
|---|---|---|---|
| Kurumsal Portal SSO | Tek oturum açma sağlanmak isteniyor | Authorization Code + PKCE, global politika | Kullanıcı tek girişle bütün API Proxy’lerde yetkilendirilir. |
| Mobil Uygulama Güvenliği | Mobil istemcilerde token sızıntısı riski var | PKCE etkin, kısa token cache süresi | Mobil uygulama token’ı secure storage’da tutar, süresi dolunca yeniler. |
| Legacy API Koruması | Eski servisler Basic Authentication kullanıyor | Token validation + header enjeksiyonu | Kimlik doğrulama gateway’de yapılır, servis yalnızca header’ı okur. |
| Harici İş Ortağı Entegrasyonu | Dış sistemler cookie tabanlı erişim istiyor | Token cookie’lere yazılır, SameSite/secure ayarlanır | İş ortağı tarayıcıları ek config olmadan oturum taşır. |
| Çoklu OIDC Sağlayıcı Yönetimi | Farklı tenant’lar farklı issuer kullanıyor | Özel condition + discovery URL değişkeni | Her tenant isteği kendi issuer’ına yönelir ve doğrulanır. |
| Yüksek Güvenlikli API | Token imzası ve aud doğrulaması zorunlu | ValidateJwtSignature + ExpectedAudience listesi | Yanlış issuer/audience içeren token’lar 403 ile reddedilir. |
| Geliştirici Sandbox (opsiyonel) | Test ortamında hafif doğrulama gerekli | Condition ile /sandbox/* path seçimi, debug logging açık | Sadece sandbox çağrıları zayıf doğrulamadan geçer, canlı trafik etkilenmez. |
Politika Parametrelerini Yapılandırma
Bu adımda, kullanıcı yeni bir politika oluşturabilir ya da mevcut politika parametrelerini yapılandırarak erişim kurallarını belirleyebilir. Tanımlanan parametreler, politikanın çalışma şeklini (örneğin hangi IP’lerin izinli olacağı, coğrafi kısıtlamalar, koşullu aktivasyonlar vb.) doğrudan etkiler. Bu sayede politika hem kuruma özel gereksinimlere göre özelleştirilebilir hem de merkezi olarak yönetilebilir.Yeni OIDC Kimlik Doğrulama Politikası Oluşturma
Yapılandırma Adımları
| Adım | Açıklama / İşlem |
|---|---|
| Adım 1: Oluşturma Sayfasına Gitme | - Sol menüden Development → Global Settings → Global Policies → OIDC Kimlik Doğrulama Politikası bölümüne gidin. - Sağ üstteki [+ Create] butonuna tıklayın. |
| Adım 2: Temel Bilgileri Girme | Policy Status (Politika Durumu): Aktif/Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Name (İsim) Zorunlu: Örnek: Production_OIDCAuth- Benzersiz isim girin, boşlukla başlamaz. - Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim. Description (Açıklama): Örnek: “Kurumsal kullanıcılar için OIDC SSO” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: OIDC Sağlayıcı ve Uç Nokta Yapılandırması | - Issuer veya Discovery URL’sini tanımlayın. - Discovery devre dışı ise Authorization, Token, UserInfo, JWKS ve Introspection endpoint adreslerini manuel girin. - Client ID/Secret, Redirect URI, Realm ve scopes alanlarını doldurun. - PKCE ve zorunlu scope ihtiyaçlarını değerlendirerek işaretleyin. |
| Adım 4: Akış, Token ve Oturum Parametreleri | - Flow Type seçerek (Authorization Code, Implicit, Hybrid, OAuth2) yönlendirmeyi belirleyin. - Token doğrulama, imza algoritması, audience/issuer kontrollerini yapılandırın. - Token kabul yolu (header/cookie), bearer kullanım durumu ve cache timeout değerlerini girin. - Session cookie adı, timeout, encryption/compression seçeneklerini açın. |
| Adım 5: Gelişmiş Başlık ve Yetkilendirme Ayarları | - Custom header ve backend header tablolarına gereksinim duyulan key/value çiftlerini ekleyin. - Kullanıcı/rol bilgilerini header’a yazmak için toggle’ları aktif edin, header isimlerini belirleyin. - Identity Role Group Service ile rol eşlemeleri yapın, gerekirse Authorization Configuration bileşeni üzerinden ek servisleri bağlayın. |
| Adım 6: Koşul Tanımlama (İsteğe Bağlı) | - Condition sekmesine geçin. - Koşullar, politikanın hangi durumda aktif olacağını belirler. Örnekler: - Ortam bazlı: Header = X-Environment, Operator = Equals, Value = production- API Key bazlı: Header = X-API-Key, Starts With = PROD-- Endpoint bazlı: Path = /api/admin/*Koşul tanımlamazsa politika her zaman aktif |
| Adım 7: Hata Mesajı Özelleştirme (İsteğe Bağlı) | - Error Message Customization sekmesine gidin. - Erişim reddedildiğinde dönecek mesajı özelleştirin. Varsayılan: { "statusCode": 403, "message": "[Default hata mesajı]" }Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" } |
| Adım 8: Kaydetme | - Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir OIDC sağlayıcı konfigürasyonu mevcut Sonuç: - Politika listeye eklenir. - API’lere bağlanabilir. - Global politikaysa otomatik uygulanır. |
Politikayı Silme
Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için Politika Yönetimi sayfasındaki Akıştan Politika Kaldırma bölümüne bakabilirsiniz.Politikayı Dışa/İçe Aktarma
Bu politikanın dışa aktarma (Export) ve içe aktarma (Import) adımları için Export/Import sayfasına bakabilirsiniz.Politikayı API’ye Bağlama
Bu politikanın API’lere nasıl bağlanacağına ilişkin süreç için Politika Yönetimi sayfasındaki Politikayı API’ye Bağlama bölümüne bakabilirsiniz.İleri Düzey Özellikler
| Özellik | Açıklama ve Adımlar |
|---|---|
| Dinamik Metadata Keşfi | - Discovery URL girildiğinde issuer, JWKS, endpoint bilgilerini otomatik çeker. - Metadata cache timeout ile performans ayarı yapılır. - Keşif başarısızsa politika hata mesajı döndürür. |
| Güvenli Oturum Şifreleme | - SessionEncryptionKey/IV alanlarına 32/16 byte değerler girilir. - Şifreleme ve sıkıştırma ayrı ayrı etkinleştirilebilir. - Güvenlik gereksinimleri için TLS zorunlu kılınmalıdır. |
| Rol Haritalama ve Header Enjeksiyonu | - Claim path ve hedef rol eşlemesi yapılır. - Roller header’a eklenebilir, header isimleri özelleştirilebilir. - Identity Role Group Service ile rol seçimi yapılır. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| OIDC Sağlayıcı Yönetimi | Kötü: Tüm ortamlar için tek issuer kullanmak. İyi: Test ve canlı için farklı issuer tanımlamak. En İyi: Condition ile ortam bazlı issuer seçimi yapmak. |
| Token Güvenliği | Kötü: Imza doğrulamasını kapatmak. İyi: JWT signature doğrulaması yapmak. En İyi: JWKS anahtarlarını cache’leyip periyodik yenilemek. |
| Oturum Süreleri | Kötü: Süreleri varsayılanda bırakmak. İyi: Kullanıcı profiline göre timeout belirlemek. En İyi: Session absolute timeout + refresh token stratejisi uygulamak. |
| Rol Yönetimi | Kötü: Roller için tek claim kullanmak. İyi: Claim path ile rol çıkarmak. En İyi: Identity Role Group Service ile merkezi rol haritalama yapmak. |
| Hata Yönetimi | Kötü: Genel hata mesajı iletilmesi. İyi: OIDC’e özgü hata mesajı belirtmek. En İyi: Error Message Customization’da kullanıcı dostu ve log dostu farklı içerik sağlamak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| TLS Zorunluluğu | Tüm endpoint adresleri HTTPS olmalı; allowInsecureConnections=true yalnızca geçici kullanım için önerilir. |
| PKCE Kullanımı | Mobil ve SPAs için enablePKCE=true yapılandırılmalı, code verifier loglanmamalı. |
| Nonce/State Koruması | Nonce ve state doğrulaması devre dışı bırakılmamalı; replay saldırılarına karşı zorunludur. |
| Session Şifreleme | SessionEncryptionKey/IV değerleri ortam gizli değişkenlerinden beslenmeli, koda gömülmemelidir. |
| Cookie Güvenliği | Secure, HttpOnly ve SameSite politikaları etkinleştirilmeli; token cookie’leri minimum yetkilerle gönderilmelidir. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Varsayılan Key Kullanımı | Neden kaçınılmalı: Kod içindeki varsayılan session key değerleri tahmin edilebilir. Alternatif: Her ortam için gizli yönetim sistemi üzerinden benzersiz key üretin. |
| Geniş Scope Tanımları | Neden kaçınılmalı: Fazla scope, yetki genişlemesine sebep olur. Alternatif: En az ayrıcalık prensibiyle yalnızca gerekli scope’ları ekleyin. |
| Uzun Cache Süreleri | Neden kaçınılmalı: JWKS/token cache’i uzun tutulursa anahtar rotasyonuna uyum zayıflar. Alternatif: 15-60 dk arası cache süresi seçin ve refresh mekanizması kurun. |
| Debug Logları Canlıda Açık Tutmak | Neden kaçınılmalı: Hassas token bilgileri loglara düşebilir. Alternatif: Debug logging’i sadece sorun giderme anında kısa süre açın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Metadata Cache | Öneri: providerMetadataCacheTimeoutSeconds değerini 900-1800 sn aralığında tutun. Etki: Discovery endpoint çağrıları azalır, latency düşer. |
| Token Cache Timeout | Öneri: tokenCacheTimeoutSeconds’ı OIDC access token yaşam süresine göre ayarlayın. Etki: Gereksiz yeniden doğrulamalar engellenir, back-end yükü azalır. |
| JWKS Önbelleği | Öneri: jwkCacheTimeoutSeconds için 3600 sn üst sınırı aşmayın. Etki: Anahtar rotasyonunda hatalı imzaların kabul edilmesi engellenir. |
| Ignore Patterns | Öneri: Statik içerik path’lerini ignoreRequestPatterns’e ekleyin. Etki: Statik dosyalar gereksiz yönlendirmeden kurtulur, yanıt süresi artar. |
| Backend Header Yönetimi | Öneri: Gerekmeyen backendRequestHeaders girişlerini kaldırın. Etki: Backend’e giden istek boyutu ve işleme süresi düşer. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | OIDC kimlik doğrulama nedir? | OpenID Connect (OIDC), OAuth 2.0 üzerine kurulu kimlik doğrulama protokolüdür. ID token ve access token kullanarak kullanıcı kimliğini doğrular. |
| Genel | Hangi flow type’lar destekleniyor? | Authorization Code, Implicit, Hybrid ve saf OAuth2 Authorization Code flow type’ları desteklenir. |
| Teknik | Token nasıl doğrulanır? | Gateway, token’ı alır, JWT signature’ını JWKS endpoint’inden alınan public key ile doğrular, audience ve issuer kontrolü yapar. |
| Teknik | PKCE nedir? | Proof Key for Code Exchange (PKCE), authorization code interception saldırılarına karşı koruma sağlayan güvenlik mekanizmasıdır. |
| Kullanım | Farklı tenant’lar için farklı OIDC sağlayıcıları nasıl kullanılır? | Condition ile tenant bazlı issuer seçimi yapılabilir veya discovery URL değişkeni kullanılabilir. |
| Kullanım | Varsayılan hata mesajını nasıl değiştirebilirim? | Error Message Customization sekmesinden durum kodu, hata kodu ve mesaj alanlarını düzenleyebilirsiniz. |
| Genel | OIDC politikası Basic Authentication politikasıyla birlikte çalışabilir mi? | Evet, ancak Basic Authentication yalnızca fallback olarak önerilir; koşul bazlı olarak hangi politikanın çalışacağını belirleyebilirsiniz. |
| Genel | Politikayı local’e çevirdiğimde global kopya etkilenir mi? | Hayır, Localize işlemi yeni bir local politika oluşturur; global politika değişmeden kalır. |
| Teknik | Discovery URL kullanmazsam hangi alanları doldurmalıyım? | Authorization, Token, UserInfo, JWKS ve Introspection endpoint adreslerini manuel girmeniz gerekir. |
| Teknik | Token doğrulaması başarısız olduğunda hangi log mesajlarını aramalıyım? | Policy debug loglarını açarak validateAccessTokenWithApi ve validateJwtSignature adımlarının hata detaylarını inceleyebilirsiniz. |
| Kullanım | Birden fazla API Proxy (API Vekil Sunucusu) için aynı politikayı nasıl paylaşırım? | Politikayı global olarak oluşturup ilgili API Proxy’lere atayabilir veya Policy Group kullanabilirsiniz. |
| Kullanım | Mobil uygulamalar için PKCE zorunlu mu? | Güçlü güvenlik için önerilir; kod yakalama saldırılarını önlemek adına enablePKCE=true ayarını aktif edin. |