Token Servisi (Token Service)

Apinizer, yetkilendirme yapmanın yanı sıra bir kimlik sağlayıcı servis gibi de çalışabilmektedir. İstemciler, kimlik bilgileri ile Apinizer'ın token oluşturan servisini kullanılarak token üretebilirler. Üretilen token'ları mesajın içerisinde göndererek kendi kimlik bilgileri yerine bu token'lar aracılığı ile kimlik doğrulama ve yetkilendirme yapılmasını sağlayabilirler.

Bu uç noktalar nerede çalışır: API Manager'da değil, API Gateway'de

Apinizer iki ayrı düzlemde çalışır ve token uç noktaları API Gateway'e aittir:

• API Manager (yönetim/kontrol düzlemi). Tüm yapılandırmanın yapıldığı yönetimsel bileşen — API proxy'leri, tüketiciler, politikalar, ayarlar. Management API ve APIops uç noktaları burada çalışır. Manager dışarıya açılmaz; yalnızca yöneticiler yapılandırma değişikliği için kullanır ve istek sıcak yolunda (hot path) değildir.
• API Gateway (veri düzlemi). Her API isteğini işleyen yüksek performanslı çalışma zamanı. Token uç noktaları burada çalışır, Manager'da değil. İstemci erişimine açıktır: istemci token almak için bunları çağırır, sonra o token ile proxy'lenen API'lere erişir. Gateway üretim trafiğini taşıdığından genellikle bir yük dengeleyici (load balancer) arkasına konur ve yatay ölçeklenir.

Kısaca: yapılandırma değişiklikleri Manager'a (APIops) gider; token alma ve API erişimi Gateway'e (token API) gider. İkisi bilinçli olarak ayrılmıştır — Manager özel ve yönetimsel kalır, token API ise istemciler tarafından erişilebilir.

bilgi

Apinizer ile OAuth2 veya JWT token üretebilir, bu token'lar ile API Proxy'lerinizde güvenlik kontrolü yapabilirsiniz.

İstemci ile Apinizer arasındaki veri akışı aşağıdaki görselde basit olarak verilmiştir:

Apinizer, OAuth2 kimlik doğrulaması için üretilen token'ları kendi veri tabanında saklar ve performans için ayrıca önbelleğine alır.

Token Depolama

Erişim (access) ve yenileme (refresh) token'ları veri tabanına hiçbir zaman düz metin olarak yazılmaz. Apinizer her token değerinin yalnızca SHA-256 özetini (digest) saklar; doğrulama, yenileme ve iptal işlemlerinin tamamı bu özet üzerinden eşleştirilir, token değerinin kendisi ise yalnızca bellekte ve istemciye dönen yanıtta bulunur. Veri tabanı herhangi bir şekilde ele geçirilse dahi, saklanan kayıtlar tek başına çalışan bir token'ın yeniden oluşturulması için kullanılamaz.

Bu depolama değişikliğini getiren sürüme yükseltildiğinde, Manager'ın ilk açılışında eksik kalan özetler otomatik olarak tamamlanır ve ardından eski düz metin sütunları kaldırılır — operatör müdahalesi gerekmez; yalnızca çok büyük bir token geçmişine sahip kurulumlarda bu adım ilk açılış süresini biraz uzatabilir. Çok düğümlü bir kurulumu yükseltmeden önce Apinizer Sürüm Yükseltme sayfasına bakın.

JWT kimlik doğrulamasında ise Apinizer token doğrulaması için herhangi bir token depolama alanına ihtiyaç duymaz. Bunun yerine her ortam içerisindeki Worker'a ait RSA anahtarını saklar. JWT token'ın üretildiği RSA anahtarının kontrolü ile token doğrulanmış olur. Bu kontrol sadece token'ın Apinizer tarafından üretildiğini ve verilerin bozulmadığını ve değiştirilmediğini (üretildiği gibi olduğunu) doğrular. Politika bu doğrulamanın yanı sıra mesajın geldiği API Proxy bilgisine göre token içindeki "claim" değerlerini de kontrol eder.

bilgi

Apinizer yeni bir yaklaşım ile anahtar değerin istemciye verilerek değil API çağrımı yaparak JWT token üretilmesini tercih eder.

JWT token değerinin üretimi için çoğu zaman anahtar değeri paylaşılsa da Apinizer bu noktada yeni bir yaklaşım ile API çağrımı yaparak JWT token üretmeyi tercih eder. Böylece anahtar kontrolü ve paylaşımı yerine token üretimini ve anahtar yönetimini istemciler için de kolay bir hale getirir. Bu yaklaşımda JWT token üretim API'sinde OAuth2'de istenen standart parametreler istenir ve benzer şekilde işlenir.

bilgi

Jwt ile token alma ve Oauth2 ile token alma panelinin açıklamasını görüntülemek için Token Alma Yöntemleri sayfasını ziyaret edebilirsiniz.

bilgi

JWT veya OAuth2 ile token alırken "Manage From This Policy"(Bu Politikadan Yönet) seçiliyse, CORS ve XFF ayarları API Proxy'nin "Settings" sekmesinden yapılandırdığınız bilgiler geçerli olacaktır.

Ancak bu seçenek işaretli değilse, "ACL'den Yönet" üzerinden yönetiliyorsa "Gateway Environments"(Ağ Geçidi Ortamı) içindeki Worker'a eklediğiniz CORS ve XFF ayarları geçerli olur. Bkz.

Token Exchange (RFC 8693)

ACL'den Yönet seçiliyken token ucu (/credential/token) token exchange grant'ını da kabul eder. Ajan, bir kullanıcı adına hedef API'yi çağırmasını sağlayan token'ı bu grant ile alır. Ajan kendi kimliğini korur. Hedef ikisini de görür.

Ajan https://apinizerErişimAdresiniz/credential/token adresine POST isteği gönderir. Client credentials grant'ındaki gibi kimlik doğrular (client ID ve secret). Ajanın tüketicisi client credentials grant türünü kullanmalıdır. İstek gövdesine şu parametreler yazılır:

Parametre	Değer
grant_type	urn:ietf:params:oauth:grant-type:token-exchange
subject_token	Kullanıcının access token'ı. Aşağıdaki subject token kurallarına bakın.
subject_token_type	urn:ietf:params:oauth:token-type:access_token veya urn:ietf:params:oauth:token-type:jwt
requested_token_type	İsteğe bağlı. Aynı iki değer.
resource veya audience	Hedef. İkisinden tam birini, tek değerle gönderin. Hedef API proxy'nin kanonik adresidir.
scope	İsteğe bağlı. Kullanıcının scope'unu yalnız daraltabilir.

Kurallar:

• Hedef API proxy yetki devri token'larını kabul etmelidir: JWT veya OAuth2 kimlik doğrulama politikasında Yetki devri token'larını kabul et (token exchange) açık olmalı ve ajanın adı İzin verilen ajanlar listesinde bulunmalıdır. Politika ayrıca yetki devri zincirinin derinliğini belirler (bir veya iki ajan). Bu ayar yoksa istek invalid_target ile reddedilir.
• Ajan, API istemcisinin client ID değeriyle tanımlanır. Bu değeri hedefin İzin verilen ajanlar listesine yazın.
• Token servisi şu subject token'ları kabul eder:
  • Bu token servisinin, Standart MCP istemci profilini kullanan bir MCP proxy için verdiği access token. Buna, ACL'den Yönet yetkilendirme sunucusundan (/credential) tarayıcı ile giriş yapan kullanıcının tarayıcı girişi (authorization code) token'ı da dahildir.
  • Önceki bir token exchange'den gelen token. Bu, zincire sonraki ajanı ekler.
• Token servisi şu subject token'ları invalid_grant ile reddeder:
  • Opaque (JWT olmayan) token'lar.
  • İptal edilmiş token'lar.
  • /auth yetkilendirme sunucusunun (Bu Politikadan Yönet) tarayıcı girişi token'ları.
  • Sıradan API proxy'ler için verilmiş token'lar. Örnekler: MCP olmayan bir proxy'nin tarayıcı girişi, password veya client credentials token'ları.
  • Başka bir issuer'ın token'ları.
  • Refresh token'lar.
• Hedef, JWT veya OAuth2 politikası yetki devri token'larını kabul eden herhangi bir API proxy olabilir (REST, SOAP veya MCP). Kaynak, yani kullanıcının token'ı, Standart profilli bir MCP proxy'den gelmelidir. Sıradan bir API proxy'nin kullanıcı token'ı, kullanıcı adına başka bir API proxy'yi çağırmak için değiştirilemez.
• Ajan kullanıcı token'ını kendisi değiştiriyorsa MCP proxy JWT kimlik doğrulama politikası kullanmalıdır. Çünkü opaque subject token'lar reddedilir. MCP Gateway'in Delege kullanıcı modunda bu sınır yoktur. Gateway, zaten doğruladığı kimliği kullanır. MCP proxy JWT veya OAuth2 politikası kullanabilir.
• Yeni token yalnız hedef içindir (aud hedeftir). Kullanıcıyı özne, ajanları aktör zinciri (act) olarak taşır.
• Hedef kullanıcının güncel rollerini uygular. Yeni token'ın scope'u rolleri yalnız daraltabilir. OAuth scope adı olmayan rol taşınmaz.
• Yeni token, kullanıcı token'ı ile ajan token ömründen erken biten süreyle sona erer. İkisinin de süresi yoksa bir saat sonra sona erer. Yanıtta refresh token yoktur.
• Yeniden değiştirilen ajan token'ı zincire sonraki ajanı ekler. Zincir hedefin izin verdiği derinlikten uzun olamaz.
• URL sorgusundaki subject_token reddedilir. Gövdede gönderin.
• Hatalar RFC 8693 ve RFC 6749 kodlarıyla HTTP 400 döner (sunucu hatasında HTTP 500 server_error). Diğer grant türleri değişmez.
• /credential/.well-known/openid-configuration adresindeki yetkilendirme sunucusu meta verisi bu grant'ı listeler. Eski oauth-authorization-server belgesi listelemez.

Apinizer gateway'in kendisi, bir MCP Gateway aracı Delege kullanıcı modunda çalışırken aynı grant'ı kullanır.

Tarayıcı ile Giriş: Authorize Uç Noktası

Token servisi, authorization code + PKCE akışıyla tarayıcıda kullanıcı girişini de destekler. Standart OAuth2 istemcileri (Claude Code, MCP Inspector, tek sayfa uygulamaları, mobil uygulamalar) bu akışı kullanır.

Mod	Uç noktalar
ACL'den Yönet	https://apinizerErişimAdresiniz/credential/authorize, /credential/token, /credential/revoke, /credential/introspect
Bu Politikadan Yönet	https://apinizerErişimAdresiniz/auth/authorize, /auth/token, /auth/revoke, /auth/introspect

• authorize uç noktası GET isteğiyle kullanıcıya giriş sayfasını gösterir. Giriş sonrası tarayıcı yönlendirme adresine code, state ve RFC 9207 iss parametreleriyle yönlendirilir.
• Yalnız PKCE S256 kabul edilir. Yönlendirme adresi tam eşleşir. Loopback adreslerinde (127.0.0.1, [::1], localhost) yalnız port farklı olabilir.
• resource parametresi zorunludur. Değer hedef API proxy'nin kanonik adresidir. Yoksa invalid_target hatası döner.
• token uç noktası grant_type=authorization_code isteğini code, code_verifier, redirect_uri, client_id ve resource ile kabul eder. code istek gövdesinde gönderilir. Açık (public) istemci secret göndermez.
• Access token JWT ise başlığında typ: at+jwt bulunur. Refresh token her kullanımda yenilenir. Kullanılmış bir refresh token yeniden gelirse token ailesi iptal edilir.
• Açık istemci introspection yapamaz. Revocation için client_id yeterlidir.
• Ortamın erişim URL'si tanımlı değilse tarayıcı girişi kapalıdır. Issuer yalnız bu yapılandırmadan gelir.
• Giriş sayfası, her istemci adresi ve her kullanıcı adı için dakikada en çok 10 giriş denemesi kabul eder. Fazla denemeler geçici olarak reddedilir. Hesap kilitlenmez.

Yetkilendirme sunucusu meta verisi (RFC 8414) kanonik adreste yayınlanır:

Mod	Kanonik adres
ACL'den Yönet	https://apinizerErişimAdresiniz/.well-known/oauth-authorization-server/credential
Bu Politikadan Yönet	https://apinizerErişimAdresiniz/.well-known/oauth-authorization-server/auth

Eski adresler çalışmaya devam eder. Ayrıntı için Token Sorgulama, İptali ve Keşif bölümüne bakın. Kurulum ve sınırlar için MCP Gateway'e Keycloak Olmadan Tarayıcı ile Giriş senaryosuna bakın.

İlgili Sayfalar

• Token Sorgulama, İptali ve Keşif — Token geçerlilik sorgulama, iptal ve Discovery uç noktaları
• Gateway Token Uç Noktaları — Formal API referansı
• Token Alma Yöntemleri — OAuth2 ve JWT token alma örnekleri