WS-Security Token

SOAP tabanlı servislerde STS token üretimi ve yönetimini otomatikleştirebilirsiniz

Bu doküman spesifik bir politikanın detaylı kullanımını anlatır. Eğer Apinizer politika yapısını ilk kez kullanıyorsanız veya politikaların genel çalışma prensiplerini öğrenmek istiyorsanız, öncelikle Politika Nedir? sayfasını okumanızı öneririz.

​

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

1. İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. 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ı?
3. WS Security STS Token Doğrulaması: configureIssueToken ayarına göre ya tanımlı STS servis uç noktasına WS-Trust Issue isteği gönderilir ya da apiEndPointURL üzerinden harici token alınır; kullanıcı bilgileri ve WS-Addressing üst bilgileri isteğe enjekte edilir.
4. 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.
5. 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: configureIssueToken ile 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: tokenCachePeriod ve expirationPeriod ile 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-settings bileş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: Variable Kullanımı	- Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilirsiniz. - Context/global variable ifadeleri sayesinde politika parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. - Bu kullanım, değişen değerlerde manuel güncelleme ihtiyacını azaltır ve operasyonel kolaylık sağlar. - Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
Adım 4: 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 5: 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 6: 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 7: 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 8: 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 9: 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.

Koşullar ve Hata Mesajı Özelleştirme panellerinin açıklaması için Politika Nedir? sayfasındaki Koşullar ve Hata Mesajı Özelleştirme (Error Message Customization) bölümlerini inceleyebilirsiniz.

Hata mesajı yapılandırmasının tüm katmanları, öncelik sırası ve senaryo örnekleri için Hata Mesajı Yapılandırma Rehberi sayfasına bakın.

​

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.