Genel Bakış
Amacı Nedir?
- WS-Trust 1.3 uyumlu Security Token Service çağrılarını merkezi politikayla yönettiği için SOAP servislerinin kimlik doğrulamasını standartlaştırır.
- Ortam bazlı kullanıcı adı/parola havuzlarını koşullara göre eşleştirerek operasyonel esneklik sağlar.
- WS-Addressing üst bilgilerini (Action, To, ReplyTo vb.) tek noktadan yapılandırarak servis sağlayıcı çalışmalarını hızlandırır.
- Token önbellekleme ve zaman damgası ayarlarıyla gereksiz STS trafiğini azaltır, gecikmeleri düşürür.
Ç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ü: WS Security STS Token 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ı?
- WS Security STS Token Doğrulaması:
configureIssueTokenayarına göre ya tanımlı STS servis uç noktasına WS-Trust Issue isteği gönderilir ya daapiEndPointURLüzerinden harici token alınır; kullanıcı bilgileri ve WS-Addressing üst bilgileri isteğe enjekte edilir. - Karar Verme:
- Eşleşme Var: Token alınır, önbellek süresi dolmadıysa cache’den kullanılır, SOAP isteğine eklenir.
- Eşleşme Yok: Token üretilemez; isteğin SOAP başlıkları değiştirilmez.
- 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
- Konfigürasyon Modu Seçimi:
configureIssueTokenile STS tokenını Apinizer üzerinden üretme veya harici bir Endpoint çağırma seçeneklerini sunar. - SOAP Versiyon Desteği: SOAP 1.1 ve SOAP 1.2 arasında seçim yaparak servis uyumluluğunu garanti eder.
- Token Servis Parametreleri: Token servis adı, port adı, WS-Trust 1.3 URL ve AppliesTo URL alanlarıyla STS entegrasyonunu detaylı yönetir.
- 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
- Token Önbellekleme ve Yenileme:
tokenCachePeriodveexpirationPeriodile token yenileme eşiğini belirleyip gereksiz STS çağrılarını engeller. - WS-Addressing Ayar Motoru: WSA Action, To, ReplyTo ve MessageId alanlarını
app-soap-api-method-wsa-settingsbileşeni üzerinden detaylı olarak yönetir. - Koşullu Kimlik Bilgisi Havuzu: Birden fazla kullanıcı adı/parolayı Query Builder koşulları ve ortam etiketleriyle ilişkilendirerek yanlış ortamda yanlış kimlik bilgisi kullanımını önler.
- Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Geliştirme, Test, Canlı Ortam) 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 SOAP Kimlik Doğrulama | Kurumsal CRM, STS üzerinden token istemeden erişim reddediyor | configureIssueToken=true, token servis bilgileri ve PasswordDigest seçimi | SOAP isteği STS tokenı içerir, 200 döner |
| Ortam Bazlı STS Ayırımı | Test ve Canlı Ortam için farklı STS kullanıcıları var | Her ortam için ayrı kullanıcı kaydı, Query Builder ile Header=X-Environment koşulu | İstek doğru kimlik bilgisiyle STS’ye gider, erişim sağlanır |
| Harici STS Delegasyonu | Apinizer dışındaki STS’ye yönlendirme gerekiyor | configureIssueToken=false, apiEndPointURL olarak harici URL girilir | Politika dış servis çağrısı yapar, tokenı SOAP başlığına ekler |
| WS-Addressing Zorunluluğu | Servis sağlayıcı WSA Action header’ı bekliyor | WSA ayarlarında Action, To ve MessageId alanları doldurulur | STS isteği WSA ile uyumlu olur, entegrasyon hatasız tamamlanır |
| Token Önbellekleme İhtiyacı | Yüksek trafikli servis her çağrıda STS’e gitmemeli | tokenCachePeriod=300, expirationPeriod=5 | Token 5 dakika tekrar kullanılır, performans artar. |
| Çoklu Kimlik Sağlayıcı | Partner bazlı farklı kullanıcı bilgileri var | Koşullu kullanıcı kaydı, partner header’ına göre seçim | Partner’e göre doğru kimlik bilgisi kullanılır, yanlış token engellenir |
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 WS Security Token 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 → WS Security Token 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_WSSTS- 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 STS token yönetimi” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: STS Token Servis Yapılandırması | - configureIssueToken açık ise Token Servis Adı, Port Adı, WS-Trust 1.3 URL ve AppliesTo URL alanlarını zorunlu doldurun.- connectionTimeout ve tokenCachePeriod için saniye cinsinden değer girin (tokenCachePeriod ≥1).- wsaMustUnderstand gerekiyorsa uygun değeri seçin. |
| Adım 4: Kimlik Bilgisi ve Parola Yönetimi | - passwordType olarak PasswordText veya PasswordDigest seçin (PasswordDigest seçilince Nonce/Created otomatik aktif olur).- STS kullanıcı listesinde her kayıt için Query Builder koşullarını ve ortam listesini belirleyin. - Güvenlik için parolaları yalnızca gerekli ortamlarla eşleştirin. |
| Adım 5: WSA ve Zaman Damgası Ayarları | - app-soap-api-method-wsa-settings bileşeninde WSA Action, To, ReplyTo vb. alanları doldurun.- createdDateFormat ve expiresDateFormat alanlarını kurum standartlarına göre güncelleyin.- expirationPeriod (dakika) ile token geçerlilik süresini tanımlayı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 Detaylar için bakabilirsiniz: Koşullar (Conditions) |
| 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 STS kullanıcı kaydı 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 |
|---|---|
| Eşzamanlı STS Yenileme Planı | - Token süresi dolmadan expirationPeriod değeriyle yenileme pencereyi belirleyin.- tokenCachePeriod ile cache süresini aşmadan yeni Issue isteği tetikleyin.- Yoğun trafikte STS servisinin throttling limitlerini aşmamak için gecikme ekleyin. |
| Çoklu Koşullu Kimlik Havuzu | - Query Builder’da partner, ortam veya IP koşulları oluşturun. - Her koşul için farklı kullanıcı/parola eşleyin. - Koşul uyuşmadığında varsayılan kaydın kullanılacağını unutmayın. |
| WSA Varsayılanlarının Otomasyonu | - wsaAddDefaultAction ve wsaAddDefaultTo alanlarını aktif ederek boş Action/To değerlerini otomatik üretin.- wsaGenerateMessageId kullanarak her çağrıda benzersiz MessageId oluşturun.- Fault senaryolarında wsaFaultTo adresini doldurun. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| STS Endpoint Tasarımı | Kötü: Tek bir STS URL’sini tüm ortamlarla paylaşmak İyi: Ortam başına farklı URL tanımlamak En İyi: configureIssueToken modunu ortam bazlı koşulla yönetmek |
| Kimlik Bilgisi Yönetimi | Kötü: Parolaları manuel güncellemek İyi: Ortam bazlı kullanıcı kayıtları oluşturmak En İyi: Query Builder ile partner veya tenant bazlı koşullandırmak |
| WS-Addressing Kullanımı | Kötü: Tüm çağrılarda varsayılan WSA değerlerini kullanmak İyi: Zorunlu alanları doldurmak En İyi: Servis gereksinimlerine göre Action/To/ReplyTo’yu dinamik planlamak |
| Token Önbellekleme | Kötü: tokenCachePeriod=0 değerini bırakmakİyi: STS limitlerine göre temel cache süresi tanımlamak En İyi: Cache süresini expirationPeriod ile uyumlu tutup periyodik izlemek |
| Hata Mesajı Yönetimi | Kötü: Genel 500 mesajı döndürmek İyi: 403 ve 401 için açık mesajlar vermek En İyi: Özel hata kodlarıyla tüketiciye yönlendirme yapmak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Kimlik Bilgisi Saklama | Parolaları yalnızca politika ekranında tutun, dış sistemlerde kopyalamayın. |
| Şifreleme Standartları | PasswordDigest tercih ederek replay saldırılarına karşı korunma sağlayın. |
| WS-Addressing Doğruluğu | Yanlış Action/To değerleri SOAP servisinde yetkisiz kanal açabilir, doğrulayın. |
| Token Süresi | expirationPeriod değerini gereksiz uzun tutmayın, çalınan token riskini artırır. |
| Hata Mesajı İçeriği | Hata mesajlarında kullanıcı/parola bilgisi veya STS URL’si paylaşmayın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Hard-coded STS Parolaları | Neden kaçınılmalı: Kaynak kod sızıntısında kimlik bilgileri ifşa olur. Alternatif: Parolaları yalnızca politika ekranında yönetin. |
| Sıfır Cache Süresi | Neden kaçınılmalı: Her istekte STS çağrısı yaparak gecikme ve throttling riskini arttırır. Alternatif: İhtiyaca göre tokenCachePeriod tanımlayın. |
| WSA Alanlarını Boş Bırakmak | Neden kaçınılmalı: Bazı servisler header eksikliği nedeniyle 500 döner. Alternatif: Gereken WSA alanlarını servis dokümantasyonuna göre doldurun. |
| Tek Ortam Kimlik Bilgisi | Neden kaçınılmalı: Yanlış ortamda yanlış kimlik bilgisi kullanılabilir. Alternatif: Her ortam için ayrı kullanıcı oluşturun, Query Builder ile koşullandırın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| STS Çağrı Frekansı | Öneri: tokenCachePeriod ≥ 120 saniye seçin.Etki: STS trafik yükü ve gecikmeler azalır. |
| Bağlantı Zamanaşımı | Öneri: connectionTimeout değerini STS SLA’sına göre ayarlayın.Etki: Gereksiz bekleme olmadan hızlı hata tespiti yapılır. |
| Koşul Değerlendirme | Öneri: Query Builder koşullarını minimal tutun. Etki: Politika değerlendirme süresi kısalır. |
| WSA Otomasyonu | Öneri: Gerekmeyen WSA alanlarını devre dışı bırakın. Etki: Header serileştirme maliyeti düşer. |
| Token Yenileme Penceresi | Öneri: expirationPeriod ile tokenCachePeriod arasında 1-2 dakikalık tampon bırakın.Etki: Token yenileme çakışmaları azalır. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | WS Security STS Token Politikası hangi API tipleriyle uyumlu? | SOAP tabanlı ve WS-Trust 1.3 destekli servislerle uyumlu çalışır. REST çağrıları için uygun değildir. |
| Genel | Aynı politikayı birden fazla API Proxy (API Vekil Sunucusu) ile paylaşabilir miyim? | Evet, global politika olarak deploy edildiğinde tüm uygun API Proxy (API Vekil Sunucusu) örnekleri tarafından kullanılabilir. |
| Teknik | configureIssueToken=false ne yapar? | Apinizer’da Issue isteği oluşturmak yerine tanımlı harici STS Endpoint’ine doğrudan SOAP çağrısı yapar. |
| Teknik | PasswordDigest seçince Nonce/Created neden kilitleniyor? | WS-Security standartları gereği Digest hesaplaması için Nonce ve Created alanları zorunludur, sistem otomatik olarak aktif eder. |
| Kullanım | Ortam bazlı kullanıcıyı nasıl seçerim? | STS kullanıcı listesinde environmentIdList alanında ilgili ortamları seçin, gerekirse Query Builder ile ek koşul ekleyin. |
| Kullanım | Token süresi dolmadan yenilenmesini sağlayabilir miyim? | expirationPeriod değerini gerçek süreye göre belirleyip tokenCachePeriod’u daha kısa tutarak token yenilemeyi kontrol edebilirsiniz. |