OAuth2 Authentication

ipucu

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?

• 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, veritabanı veya OIDC sağlayıcılarıyla entegre ederek yetkilendirme süreçlerini uyumlu hale getirir.

Ç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ü: 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ı?
3. 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.
4. 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.
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

• 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, veritabanı veya OIDC Kimlik Sağlayıcı 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: 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: OAuth 2 Akış Parametreleri	- Yönetim (varsayılan: Bu Politikadan Yönet): İki seçenekten biri seçilir.   - ACL'den Yönet: Kimin çağırabileceğine consumer, API client ve ACL satırları karar verir; token ayarları API client'tan gelir.   - Bu Politikadan Yönet: Bu politikanın kimlik kaynağı, grant tipleri ve token ayarları karar verir; API client ayarları kullanılmaz.   - Grant Type, kimlik kaynağı ve token ayarları ile Tarayıcı ile giriş, API Anahtarını Göster, istemci adresi kontrolü, URL parametreleri, yetkilendirme bilgisini temizleme ve kimliği başlığa ekleme alanları yalnızca Bu Politikadan Yönet seçiliyken görünür. Kimlik kaynağı OIDC ise Yönetim seçimi görünmez. - Grant Type: CLIENT_CREDENTIALS veya PASSWORD seçin. - Identity Role Group: PASSWORD akışında kimlik sağlayıcısını Secret Manager, LDAP, Database, API veya OIDC üzerinden seçin. OIDC seçildiğinde aranabilir bir OIDC Kimlik Sağlayıcı listesi açılır (ad, açıklama, sağlayıcı türü); Generic türündeki bir sağlayıcı da burada geçerli bir seçimdir, çünkü yalnızca token doğrulaması kullanılır. - Check Client IP Address: Secret Manager akışında token'ın kaynak IP ile eşleşmesini zorunlu kılın. - Kimlik Kaynağı her grant tipinde görünür: CLIENT_CREDENTIALS akışında yalnızca Secret Manager (varsayılan — token üretimi ve doğrulaması değişmez) veya OIDC sunulur. - CLIENT_CREDENTIALS ile OIDC (sağlayıcının ürettiği token): politika token üretmez; istemci sağlayıcının erişim token'ını Authorization: Bearer ile sunar, Apinizer her istekte doğrular (çevrimdışı JWKS imzası, çevrimiçi introspection/userinfo — opak token'lar introspection ile desteklenir). Kimlik sağlayıcının Kullanıcı Adı Claim Yolu alanından (opak token'da introspection yanıtından), roller sağlayıcının rol kaynağından gelir; Eşleşen Consumer Zorunlu kimliği kota/ACL atfı için bir Consumer ile eşler. Öncekini Sil, token süresi ve yenileme ayarları gizlenir; proxy'nin /auth/* token ucu 400 invalid_request döner. PASSWORD + OIDC önceki davranışı korur. İstemci için ACL Kontrol Et: Varsayılan olarak açıktır. Kimlik kaynağı Secret Manager olduğunda veya ACL'den Yönet modu seçildiğinde görünür; OIDC için gizlidir. Kapalıyken politika yalnızca kimliği çözümler ve doğrular; tüketicinin bu API Proxy veya Proxy Group için erişim listesini (ACL) kontrol etmez. Bkz. Yalnızca Kimlik Modu (ACL Kapalı).
Adım 5: 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 6: Header ve Yetkilendirme Entegrasyonu (Varsa)	- Set Resolved Identity to Context (Çözümlenen Kimliği İstek Bağlamına Yaz): Bu politikanın çözümlediği kimliğin (kullanıcı/anahtar) isteğin kimliği olarak kaydedilip kaydedilmeyeceğini belirler. Açık (varsayılan) iken bu kimlik trafik loglarında ve sonraki politikalar ile scriptlerde görünür. Kapalı iken kimlik yalnızca gerekli iç kimlik doğrulama/yetkilendirme kontrolleri için kullanılır, isteğin kalıcı kimliği olarak tutulmaz. - 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 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
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 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.

Client Id / Client Secret Yönetimi

Bu Politikadan Yönet seçildiğinde, token isteklerinde doğrulanacak Client Id ve Client Secret değerleri; bu politikanın bağlı olduğu API Proxy, API Proxy Group veya Politika Grubu (Policy Group)'nun kendi anahtarlarıdır. Politika formunda yer alan API Anahtarını Göster (Show API Key) seçeneğiyle açılan pencerede mevcut Client Id ve Client Secret görüntülenebilir, kopyalanabilir ve gerektiğinde değiştirilebilir. Her iki alan salt okunurdur; değeri göstermek için göz butonu, değiştirmek için kalem butonu (Client Id Düzenle / Client Secret Düzenle) kullanılır.

Anahtar Üretim Tipi (Key Generation Type)

Client Id veya Client Secret düzenlenirken ilgili kaydın adı yazılır ve bir anahtar üretim tipi seçilir:

• Otomatik (Automatic): Yeni rastgele değeri sistem üretir.
• Manuel (Manual): Değeri siz yazarsınız. Anahtar değerini elle girmenin tek yolu budur; yalnızca boşluklardan oluşan değer kabul edilmez.

uyarı

Anahtarı değiştirmek kritik bir işlemdir: Client ID değiştirilir ve mevcut değeri kullanan entegrasyonlar çalışmaz. Devam edebilmek için ilgili kaydın adını yazmanız, Düzenle butonuna tıklamanız ve son soruyu ("Key'i değiştirmek istediğinizden emin misiniz?") onaylamanız istenir. Yeni anahtar taslak olarak tutulur; kaydedilmeden geçerli olmaz (Save ve key dialogunda onay; Cancel taslağı iptal eder); kayıttan sonra yeni anahtarların etkin olabilmesi için ilgili API Proxy, API Proxy Group veya Politika Grubu'nun yeniden yüklenmesi (redeploy) gerekir. Bu politikayı kullanan mevcut istemcilerin de yeni Client Id/Client Secret değerleriyle yeniden yapılandırılması gerekir.

Ekranlar Arası Tutarlılık

Bu Client Id / Client Secret görüntüleme, kopyalama ve düzenleme deneyimi (Otomatik/Manuel seçimi, isim yazarak onaylama, son onay adımı dahil); API Proxy, Politika Grubu (Policy Group) ve API Proxy Group ekranlarındaki kendi anahtar yönetimi bölümleriyle birebir aynıdır. Bu OAuth 2 Kimlik Doğrulama Politikası bir API Proxy'nin, bir API Proxy Group'un veya bir Politika Grubu'nun politika listesine bağlandığında — global (paylaşılan) bir politika olarak seçilmiş olsun ya da o API/Grup'a özel yerel bir politika olarak oluşturulmuş olsun — politika formunda görünen API Anahtarını Göster seçeneği aynı deneyimi sunar.

Token alma ve elle iptal (Manage From This Policy)

Delete Previous Token yalnızca yeni token alındığında aynı istemciye ait önceki token'ları geçersiz kılar. Belirli bir token'ı istediğiniz anda iptal etmek için politika ayarı yerine gateway'deki POST /auth/revoke uç noktasını (RFC 7009) kullanırsınız; kimlik doğrulama, token alma ile aynı proxy uygulama anahtarı ile yapılır.

• Token alma: Token Alma Yöntemleri (POST /auth/token)
• Sorgulama, iptal ve keşif: Token Sorgulama, İptali ve Keşif (/auth/introspect, /auth/revoke, /.well-known/oauth-authorization-server)

not

Token uç noktaları API Gateway erişim adresinizin kökünde çalışır (\{gatewayErişimAdresi\}/auth/token, \{gatewayErişimAdresi\}/auth/revoke). API Proxy client route yolunun sonuna /auth/token veya /auth/revoke eklemeyin; proxy'lenen API çağrıları client route üzerinden gider, token işlemleri /auth önekli gateway uçlarından gider.

Client Authentication — Authorization Basic Header Desteği (RFC 6749 §2.3.1)

Örnek:

Basic Authorization Header (Yeni — 2026.04.4)

curl -u "my-client-id:my-secret" \
  -d "grant_type=client_credentials" \
  https://gateway.example.com/credential/token

Body Parametreleri (Geriye Dönük Uyumlu)

curl -d "grant_type=client_credentials&client_id=my-client-id&client_secret=my-secret" \
  https://gateway.example.com/credential/token

Önemli Kurallar:

• Çift gönderim yasağı: Aynı istekte hem Authorization Basic header'ı hem body'de client_id/client_secret parametreleri gönderirseniz, sunucu HTTP 400 (invalid_request) ile reddeder (RFC 6749 §2.3.1 "MUST NOT" kuralı).
• Bozuk header işlemesi: Base64-decode edilemeyen veya eksik Basic header'lar HTTP 401 (invalid_client) ile reddedilir.
• Diğer Authorization scheme'leri: Basic dışındaki yetkilendirme türleri (örn. Bearer, Digest) görmezden gelinir; bu durumda body parametreleri kullanılır.
• Şifre ve kullanıcı adı: PASSWORD grant akışında username ve password her zaman request body'de gönderilir; Authorization header sadece client_id/client_secret için kullanılı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.

Tarayıcı ile Giriş (authorization_code)

Bu Politikadan Yönet modunda politikaya Tarayıcı ile giriş (authorization_code) anahtarını açabilirsiniz. Anahtar açıkken standart bir OAuth2 istemcisi (örneğin Claude Code veya MCP Inspector) Apinizer'ı yetkilendirme sunucusu olarak kullanır. Kullanıcı gateway'in /auth giriş sayfasında oturum açar ve uygulama onun adına token alır. Seçili eski grant (client credentials veya password) çalışmaya devam eder.

• Kullanıcılar politikanın kimlik kaynağından gelir: Secret Manager, LDAP, veritabanı veya API. Kimlik kaynağı OIDC ise anahtar kapalıdır.
• Politikada Token Never Expires kapalı olmalı ve access token süresi sonlu olmalıdır. Refresh token'a izin veriyorsanız refresh süresi de sonlu olmalıdır. Tarayıcı girişi süresiz token vermez.
• İstemci, uygulamaya ait bir API istemcisidir. client_id değeri bu istemcinin client kimliğidir. Uygulamanın proxy için ACL satırı da gerekir.
• Anahtar yalnız API Proxy'nin kendi token politikasında kullanılabilir. Proxy grubu politikasında ve bir metodun politikasında kullanılamaz.
• Anahtarı açtıktan ya da kapattıktan sonra politikayı kaydedin ve proxy'yi yeniden deploy edin. Anahtarı kapatırsanız tarayıcı girişiyle verilmiş token'lar hemen geçersiz olur.
• Tüm worker'lar yükseltilmeden anahtarı açmayın.
• ACL'den Yönet modunda anahtar görünmez. Bu modda tarayıcı girişi, uygulamaya ait API istemcisinde açılır.

Politika kaydedilirken şu hata mesajları görünebilir:

Mesaj	Anlamı
Token politikasının grant listesi geçerli değil. Liste, seçili grant tipiyle aynı olan tek bir eski grant (client credentials veya password) içermelidir. Tarayıcı girişi (authorization_code) eklenebilir.	Grant listesi geçersiz.
Bu politikada tarayıcı girişi (authorization_code) için access token süresi sonlu olmalıdır. Refresh açıksa refresh token süresi de sonlu olmalıdır.	Süresiz token ayarı var.
Kimlik kaynağı OIDC ise tarayıcı girişi (authorization_code) kullanılamaz. OIDC sağlayıcısının kendi girişini kullanın.	Kimlik kaynağı OIDC.
Tarayıcı girişi (authorization_code) API proxy'nin kendi token politikasının ayarıdır. Proxy grubu politikasında kullanılamaz.	Politika bir proxy grubuna bağlı.
Tarayıcı girişi (authorization_code) API proxy'nin kendi token politikasının ayarıdır. Bir metodun politikasında kullanılamaz.	Politika bir metoda bağlı.

Adım adım kurulum için MCP Gateway'e Keycloak Olmadan Tarayıcı ile Giriş senaryosuna bakın. Uç noktalar için Token Servisi sayfasına bakın.

Yetki Devri Token'larını Kabul Etme (Token Exchange)

Yetki devri token'larını kabul et (token exchange) anahtarı, bir ajanın bu API proxy'yi bir kullanıcı adına çağırmasını sağlar. Ajan, token exchange ile aldığı token'ı kullanır. Anahtar varsayılan olarak kapalıdır. Anahtar kapalıyken politika yetki devri token'ını eskisi gibi reddeder. Doğrudan istemciler etkilenmez.

• Anahtar hem ACL'den Yönet hem de Bu Politikadan Yönet modunda görünür. Kimlik kaynağı OIDC ise görünmez.
• Anahtarı açtığınızda iki alan daha görünür.
• İzin verilen ajanlar: Ajanların API istemcilerinin client ID değerlerini girin. Eski tüketici için kullanıcı adını girin. Değeri yazın ve Enter tuşuna basın. Liste boşsa hiçbir ajan kabul edilmez.
• Yetki devri zinciri derinliği: Bir ajan veya En çok iki ajan seçeneğini seçin. Varsayılan değer En çok iki ajan seçeneğidir.
• Gateway bu ayarı yalnız API proxy'nin kendi istek politikası listesindeki aktif JWT ve OAuth2 politikalarından okur. Metot, proxy grubu veya politika grubu içindeki politikaları okumaz.

Gateway, yetki devri token'ı için şunları denetler:

• Token yalnız bu API proxy içindir. Audience değeri bu proxy'nin kanonik adresidir.
• Zincirdeki her ajan İzin verilen ajanlar listesindedir. Zincir, seçilen derinlikten uzun değildir.
• Her ajan hâlâ aktiftir ve token'ları iptal edilmemiştir.
• Kullanıcı, istek kimliği olarak bu proxy'nin erişim denetimlerinden geçer. ACL denetimi açıksa kullanıcının ACL satırı gerekir.
• İstek, kullanıcının güncel rolleriyle çalışır. Token'ın scope'u rolleri yalnız daraltabilir. OAuth scope adı olmayan rol taşınmaz.

Reddedilen token için gateway normal "token geçerli değil" yanıtını verir.

JWT politikası yetki devri JWT'lerini doğrular. OAuth2 politikası saklanan (opaque) yetki devri token'larını doğrular. Token exchange, hedef politikanın doğruladığı biçimde token verir. Ajan biçimi seçemez.

Daha fazla bilgi için Token Exchange (RFC 8693) bölümüne bakın.

Yalnızca Kimlik Modu (ACL Kapalı)

İstemci için ACL Kontrol Et kapalıyken politika yalnızca kimlik modunda çalışır. Kimliği yine çözümler ve doğrular; ancak tüketicinin bu API Proxy veya Proxy Group için erişim listesini (ACL) kontrol etmez.

ACL kapalıyken yine uygulananlar

ACL kapalıyken atlananlar

Tüketici mevcuttur ve etkindir. Tüketicinin organizasyonu ve üst organizasyonları aktiftir. Tüketicinin geçerlilik süresi (expire date) dolmamıştır. Tüketicinin sözleşmeleri bitiş tarihini geçmemiştir. İstemci IP'si tüketicinin IP listesindedir (Validate Client Address açıksa). API Client sahibi aktiftir. Rol yetkilendirmesi (etkinse) ve Limit Plan kuralları uygulanır. İstek doğrulanmış olarak işaretlenir ve çözümlenen kimlik trafik loguna yazılır.

Tüketicinin bu API Proxy veya Proxy Group için erişim satırı (süresi, ortam etkinleştirme anahtarı, izin verilmeyen method ve proxy'ler). API Client aboneliği ve erişim izinleri (portal abonelikleri). Bu bilgi erişim satırından geldiği için trafik logunda bu istekler için abonelik ürünü ve planı görünmez.

uyarı

ACL kapalıyken, kimlik kurallarını geçen ortamdaki her aktif tüketici API'yi çağırabilir. Proje sınırı yoktur.

Seçenek token uçlarına da uygulanır: PASSWORD grant için token üretimi aynı anahtarı izler.

bilgi

LDAP, Database, API ve OIDC kimlik kaynakları ACL'yi hiçbir zaman sorgulamaz. Bu kaynaklarda seçeneğin etkisi yoktur.

Bir API Product'ın güvenlik sekmesinde, ACL'si kapalı politika mevcut "Politikadan yönetiliyor" durumuyla raporlanır: kimlik doğrulama consumer store (ACL) yerine politikadan yönetilir, bu nedenle uygulama credential'ları orada yetkilenmez.

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	Yönetim alanında ACL'den Yönet seçilirse ne olur?	Kimin çağırabileceğine consumer, API client ve ACL satırları karar verir; token ayarları API client'tan gelir. Politikadaki grant tipi, kimlik kaynağı ve token ayarları kullanılmaz ve formda gösterilmez. Yetkilendirme yapılandırması bu modda da formda gösterilir. Formda gizlenen yetkilendirme bilgisini temizleme ve kimliği başlığa ekleme ayarlarının kayıtlı değerleri bu modda da uygulanı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.