Genel Bakış
Amacı Nedir?
- Kurumsal servislerin OAuth 2 tabanlı erişiminde kimlik doğrulamayı standardize ederek API Proxy (API Vekil Sunucusu) seviyesinde merkezi kontrol sağlar.
- Farklı grant type ihtiyaçlarını tek politika altında yönetip proje bazlı tutarlılık sunar.
- Token ve refresh token yaşam döngülerini denetleyerek erişim süresini, yenileme haklarını ve güvenlik sınırlarını kurum politikalarına göre ayarlar.
- Kimlik ve rol kaynaklarını Secret Manager, API, LDAP veya veritabanı sağlayıcılarıyla entegre ederek yetkilendirme süreçlerini uyumlu hale getirir.
Ç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ü: OAuth 2 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ı?
- OAuth 2 Akış Kontrolü: Seçili grant type’a göre istemci kimlik bilgilerini doğrular, gerekli ise Identity Role Group ve Secret Manager bilgilerinden kimlik veya rol verisi çeker, token üretim/yenileme kurallarını uygular.
- Karar Verme:
- Eşleşme Var: Yetkili istemci için erişim tokenı oluşturulur veya mevcut token doğrulanır, header zenginleştirmeleri uygulanır.
- Eşleşme Yok: Token üretimi veya doğrulama reddedilir, yetkisiz erişim kaydedilir.
- 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
- Grant Type Yönetimi: CLIENT_CREDENTIALS ve PASSWORD akışlarını destekleyerek farklı istemci türlerine uygun kimlik doğrulama sağlar.
- Token Yaşam Döngüsü Kontrolü: Erişim token süresi, refresh token hakları ve yenileme sayısını proje gereksinimlerine göre tanımlar.
- Kimlik Sağlayıcı Entegrasyonu: Secret Manager, Identity Role Group, LDAP, API veya veritabanı tabanlı kimlik kaynaklarıyla çalışarak kimlik doğrulama esnekliği 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
- Secret Manager Tabanlı Güvence: Kimlik bilgilerini güvenli kasada tutarak parolasız flows için ek güvenlik ve IP adresi takibi sağlar.
- Header Zenginleştirme: Doğrulanan kullanıcının kimlik ve rol bilgilerini özelleştirilebilir header alanlarına yazar.
- Metot Bazlı Yetkilendirme: API metodları için özel rol setleri tanımlayıp granular erişim kontrolü uygular.
- 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ç |
|---|---|---|---|
| M2M Servis Token Yönetimi | Makine kullanıcısı backend’e erişmek istiyor | Grant Type = CLIENT_CREDENTIALS, Token Never Expires = false, Token Expires In = 15 dk | Token periyodik yenilenir, servisler kontrollü erişir |
| Kullanıcı Parola Yetkilendirmesi | Son kullanıcı mobil uygulamadan giriş yapıyor | Grant Type = PASSWORD, Identity Role Group = RetailUsers, Check Client IP Address = true | IP eşleşmesi olmayan token reddedilir, rol bazlı header set edilir |
| Refresh Token Döngüsü | Uzun süreli oturum ihtiyacı var | Token Never Expires = false, Refresh Token Allowed = true, Refresh Token Count = 5 | Refresh token ile kesintisiz erişim sağlanır, limit aşıldığında yeniden kimlik doğrulama istenir |
| Rollerin Header’a Eklenmesi | Downstream servis rol bilgisi bekliyor | Add Roles To Header = true, Roles Header Name = X-Authorized-Roles | İstek header’ında rol listesi taşınır, hedef servis ek sorgu yapmaz |
| Secret Manager Entegrasyonu | Kimlik bilgileri Apinizer kasasında tutulacak | Grant Type = PASSWORD, Authentication Provider = Secret Manager, Use Secret Manager For Authorization = true | Kimlik/rol verileri kasadan okunur, parola yönetimi uygulamadan bağımsızlaşır |
| Yalnızca Belirli Endpoint | Admin API yalnızca yönetici rolüyle erişilsin | Condition: Path = /api/admin/*, Enable Authorization = true, Method Access = role mapping | Admin olmayan çağrılar 403 döner, yönetici metodları erişilebilir |
| Audit Odaklı Token Sıfırlama (opsiyonel) | Eski tokenlar geçersiz kılınacak | Delete Previous = true, Clear Auth = true | Yeni token üretildiğinde eski tokenlar iptal edilir, loglama kolaylaşır |
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 OAuth 2 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 → OAuth 2 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_OAuth2Auth- 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: “M2M servisleri için OAuth 2 CLIENT_CREDENTIALS akışı.” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: OAuth 2 Akış Parametreleri | - Managed From This Policy: Token yönetimini politika mı üstlenecek belirleyin. - Grant Type: CLIENT_CREDENTIALS veya PASSWORD seçin. - Identity Role Group: PASSWORD akışında kimlik sağlayıcısını Secret Manager, LDAP, Database veya API üzerinden seçin. - Check Client IP Address: Secret Manager akışında token’ın kaynak IP ile eşleşmesini zorunlu kılın. |
| Adım 4: Token Yaşam Döngüsü ve Refresh Ayarları (Varsa) | - Delete Previous: Yeni token üretildiğinde eski tokenları iptal edin. - Token Never Expires: Süresiz token gerekiyorsa açık bırakın; kapatırsanız süre ve birim tanımlayın. - Refresh Token Allowed: Yenileme hakkını aktif edin, sayıyı ve süresini belirleyin. - Allow URL Parameters / Clear Auth: Token endpoint’inde URL parametresi kabulü ve eski kimlik bilgilerinin temizlenmesini yapılandırın. |
| Adım 5: Header ve Yetkilendirme Entegrasyonu (Varsa) | - Add User To Header / User Header Name: Doğrulanan kullanıcı bilgisini özel header’a ekleyin. - Authorization Configuration: Method bazlı rol atamaları, yetkilendirme kaynağı (Secret Manager, API, LDAP, DB) ve rol header yönetimini ayarlayın. - Add Roles To Header / Roles Header Name: Roller için iletilecek header isimlerini belirleyin. |
| 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 OAuth 2 akış seçimi ve gerekli kimlik sağlayıcısı belirlenmiş durumda. 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 |
|---|---|
| Secret Manager ile Kimlik Doğrulama | - PASSWORD grant seçildiğinde Secret Manager sağlayıcısını işaretleyin - Identity Role Group dialogu ile güvenli kasadaki kimlikler eşleştirilir - Check Client IP Address aktifken token yalnızca tanımlı IP’den geçerli olur |
| Method Bazlı Yetki Haritalama | - Authorization Configuration’da Enable Method Access’i açın - Tüm metodlar otomatik listelenir ve rol listeleri atanır - Rol bazlı metod sınırları Policy Usage raporlarına yansır |
| Header Zenginleştirme ve SSO Entegrasyonu | - Add User To Header aktifken kullanıcı kimliği özel header’a yazılır - Add Roles To Header ile kullanıcı rol listesini paylaşın - Downstream servisler ek sorgu yapmadan federasyon sağlar |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Token Yaşam Döngüsü | Kötü: Token Never Expires açık bırakılmış, süresiz erişim İyi: Token süresi 24 saat, refresh token kapalı En İyi: Token 15 dk, refresh token 3 hak, kısa süreli erişim |
| Grant Type Seçimi | Kötü: PASSWORD grant her servis için zorlanmış İyi: PASSWORD yalnızca kullanıcı etkileşimli API’lerde En İyi: CLIENT_CREDENTIALS makine erişiminde, PASSWORD mobil uygulamada |
| Header Yönetimi | Kötü: Header isimleri varsayılan bırakılmış, kullanım net değil İyi: Header isimleri dökümante edilmiş En İyi: Header değerleri log’lanmadan, downstream sözleşmesiyle uyumlu |
| Secret Manager Kullanımı | Kötü: Kimlik bilgileri manuel giriliyor İyi: Secret Manager kullanılıyor fakat audit kapalı En İyi: Secret Manager + IP kontrolü + düzenli erişim log analizi |
| Authorization Konfigürasyonu | Kötü: Enable Authorization kapalı, tüm API’ler herkesçe erişilebilir İyi: Metot bazlı rol ataması yapılmış En İyi: Roller, Policy Group ve CI/CD pipeline ile versiyonlanmış |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Token Sona Erme | Kısa ömürlü erişim tokenları kullanın, sessiz saldırı yüzeyini azaltın. |
| Refresh Token Koruması | Refresh token sayısını sınırlayın, sızıntı durumunda hızlı iptal için Delete Previous’u aktifleştirin. |
| Secret Manager Erişimi | Kimlik kasasına erişimi sadece yetkili operasyon kullanıcılarına verin, audit loglarını izleyin. |
| Header Maskeleme | Kullanıcı verilerini taşıyan header’ları loglarda maskeleyin, PII sızıntısını engelleyin. |
| IP ve Koşul Kontrolü | Üretim ortamında koşullar ve IP doğrulamasıyla politikayı daraltın; açık erişim bırakmayın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Süresiz Token Tanımlama | Neden kaçınılmalı: Saldırı yüzeyi artar. Alternatif: Kısa süreli token + refresh döngüsü. |
| Ortak Secret Paylaşımı | Neden kaçınılmalı: Birden çok istemci aynı kimlik bilgiyi kullanırsa izleme yapılamaz. Alternatif: İstemci başına secret üretip Secret Manager’da tutun. |
| Koşulsuz Global Aktarım | Neden kaçınılmalı: Tüm API’ler etkilenir, test edilmemiş değişiklikler yayılır. Alternatif: Önce test ortamında local politika olarak deneyin. |
| Header Standartlarını Bozma | Neden kaçınılmalı: Downstream servisler hata verir. Alternatif: Header değişikliklerini tüketici ekiplerle birlikte planlayın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Token Üretim Sıklığı | Öneri: Token süresini çok kısa tutmayın (örn. 5 dk altı). Etki: Authentication servisine yük azalır. |
| Refresh Token Kullanımı | Öneri: Gereksiz refresh döngülerini kapatın. Etki: Veri tabanı ve cache üzerinde daha az okuma. |
| Secret Manager Çağrıları | Öneri: Secret Manager isteklerini cache’leyin. Etki: Secret store’a gecikme ve maliyet düşer. |
| Rol Listesi Boyutu | Öneri: Header’a sadece gerekli rolleri ekleyin. Etki: Response boyutu küçülür, ağ gecikmesi azalır. |
| Condition Kullanımı | Öneri: Gereksiz karmaşık koşullardan kaçının, spesifik filtreler tanımlayın. Etki: Politika değerlendirme süresi kısalır. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | OAuth 2 Kimlik Doğrulama Politikası hangi grant tiplerini destekler? | CLIENT_CREDENTIALS ve PASSWORD akışları desteklenir; her biri için ayrı yapılandırma yapılabilir. |
| Genel | Managed From This Policy kapatılırsa ne olur? | Token yönetimi dış sistemde tutulur, politika sadece koşul ve header zenginleştirmesi için kullanılır. |
| Teknik | Secret Manager seçildiğinde hangi ek ayarlar gerekir? | Identity Role Group üzerinden kasadaki kimlik seti seçilmeli, gerekirse Check Client IP Address aktifleştirilmelidir. |
| Teknik | Refresh token limiti nasıl hesaplanır? | Refresh Token Count alanı izinli yenileme sayısını belirler; aşıldığında yeni kimlik doğrulama gerekir. |
| Kullanım | Politikayı API’ye bağladıktan sonra değişiklik anında yansır mı? | Global politikada deploy gerekir; local politikada kayıt sonrası anında API flow’una yansır. |
| Kullanım | Header isimlerini değiştirmek güvenli midir? | Evet, ancak downstream servislerle koordine edilmelidir; değişiklik öncesi test önerilir. |