Oturum Açmış Kullanıcı Adına API Çağırma (Delege Token'lar)

Ne Kuracaksınız

Kullanıcı bir MCP istemcisinde tarayıcıyla oturum açar. MCP Gateway'in bir aracı sonra bir hedef API'yi çağırır. Hedef, ortak bir servis kimliğini değil, oturum açmış kullanıcıyı görmelidir.

İki yol vardır. İkisi de delege token kullanır. Delege token, kullanıcıyı özne (subject) ve ajanı aktör (actor) olarak adlandırır.

	A. MCP Gateway, Delege kullanıcı modu	B. Kendi ajanınız
Kullanıcı token'ını kim değiştirir	Gateway, süreç içinde	Ajanınız, `POST /credential/token` isteğiyle (RFC 8693)
Hedefi kim çağırır	Gateway, araç için	Ajanınız
İzin verilen ajanlar listesindeki ajan	MCP proxy'sinin servis istemcisi	Ajanınızın API istemcisi

Örnekler Order Management projesindeki tek bir senaryoyu ve https://gateway.example.com gateway'ini kullanır. Kök bağlam /apigateway olarak yazılır.

Öğe	Örnek
Hedef REST proxy	Order Service API, yol `/order-service`, uç nokta `GET /orders`. JWT kimlik doğrulama politikası ACL'den Yönet modundadır.
MCP proxy	Order Service Tools, yol `/order-tools`, mod Araçları Aç, profil Standart MCP OAuth. JWT politikası ACL'den Yönet modundadır. `list_orders` aracı Order Service API proxy'sinin `GET /orders` ucunu çağırır.
Tarayıcı istemcisi	Claude Code uygulaması, açık (public) API istemcisi `claude-code-desktop`, yönlendirme adresi `http://localhost:33418/callback`.
Servis istemcisi	Order Tools Gateway uygulaması, API istemcisi `order-tools-gateway`. Bu client kimliğini MCP proxy'sinin Servis istemcisi alanına girersiniz.
Kendi ajanınız	Order Assistant uygulaması, gizli (confidential) API istemcisi `order-assistant`.
Kullanıcı	Tüketici `ella.moore`. Order Service Tools ve Order Service API üzerinde ACL satırı vardır.

Ön Koşullar

Order Service Tools MCP proxy'si, Claude Code uygulaması ve tarayıcı girişi hazırdır. Bkz. MCP Gateway'e Keycloak Olmadan Tarayıcı ile Giriş.
Hedef proxy Order Service API deploy edilmiştir. ACL'den Yönet seçili bir JWT kimlik doğrulama politikası vardır.
Tüketici ella.moore giriş yapabilir. Tüketici deploy edilmiştir.

Hedef API'yi Hazırlayın

Hangi ajanların kullanıcı adına çalışabileceğini hedef belirler. Hedefin kimlik doğrulama politikasını değiştirirsiniz.

Kimlik doğrulama politikasını açın

Order Service API proxy'sinin JWT kimlik doğrulama politikasını açın. OAuth2 kimlik doğrulama politikasında ayarlar aynıdır.

Delege token'ları kabul edin

Yetki devri token'larını kabul et (token exchange) anahtarını açın. Bu anahtar kapalıysa hedef her delege token'ı reddeder.

İzin verilen ajanları ekleyin

İzin verilen ajanlar alanına bir client kimliği yazın ve Enter tuşuna basın. Şu client kimliklerini ekleyin:

Client kimliği	Yol
`order-tools-gateway`	A. MCP proxy'sinin servis istemcisi.
`order-assistant`	B. Kendi ajanınız.

Liste boşsa hiçbir ajan kabul edilmez.

Zincir derinliğini seçin

Yetki devri zinciri derinliği alanında Bir ajan veya En çok iki ajan seçin. Örnekte En çok iki ajan seçin.

Order Service API JWT kimlik doğrulama politikası: ACL'den Yönet, İstemci için ACL Kontrol Et açık, Yetki devri token'larını kabul et açık, İzin verilen ajanlar order-tools-gateway ve order-assistant, Yetki devri zinciri derinliği En çok iki ajan

Kaydedin ve deploy edin

Politikayı kaydedin. Order Service API proxy'sini deploy edin.

Hedef herhangi bir API proxy olabilir. Bu senaryoda bir REST proxy'dir.

Kullanıcının ACL satırı

Hedefe giden istek kullanıcı olarak çalışır. Order Service API için ella.moore kullanıcısının ACL satırını ekleyin. Kullanıcının Order Service Tools için de ACL satırı olmalıdır. Bkz. API Proxy ACL.

Servis istemcisi order-tools-gateway için ACL satırı gerekmez. Ne MCP proxy'sinde ne de hedefte.

A. MCP Gateway'in Delege Kullanıcı Modu

Servis istemcisini girin

Order Service Tools proxy'sinin Yönlendirme sekmesinde Routing Modu bölümünde Yapılandır düğmesini seçin. Standart MCP OAuth profilini seçin. Servis istemcisi alanına order-tools-gateway değerini girin.

Aracın hedef kimliğini belirleyin

list_orders aracını düzenleyin. Hedef kimliği alanını Delege kullanıcı yapın.

Proxy'yi kaydedin ve deploy edin

Proxy'yi kaydedin. Deploy edin.

Order Service Tools yayımlanan araçlar tablosu: list_orders aracı, hedef Order Service API GET /orders, Zorunlu Scope'lar açık, Hedef kimliği Delege kullanıcı

Hedef delege token'ları kabul etmiyorsa ya da servis istemcisini listelemiyorsa Apinizer kaydı reddeder: "Delege kullanıcı modundaki aracın hedef API'si, JWT veya OAuth2 kimlik doğrulama politikasında delege token'ları kabul etmeli ve servis istemcisini izinli ajan olarak listelemelidir." Hedefin politikasını düzeltin, sonra yeniden kaydedin.

Aracın modları hakkında daha fazla bilgi için bkz. Araç hedefine yapılan çağrılar.

curl ile doğrulama

Kullanıcı, tarayıcı girişi senaryosundaki tarayıcı akışıyla giriş yapar. claude-code-desktop istemcisi https://gateway.example.com/apigateway/order-tools kaynağını ister. Token ucunun yanıtı kullanıcı token'ını içerir:

{"access_token":"…","refresh_token":"…","token_type":"Bearer","expires_in":900}

Kullanıcı token'ı typ: at+jwt başlıklı bir JWT'dir. Claim'leri şunlardır:

Claim	Değer
`sub`	`ella.moore`
`aud`	`https://gateway.example.com/apigateway/order-tools`
`client_id`	`claude-code-desktop`

1. Oturumu başlatın:

curl -i -X POST https://gateway.example.com/apigateway/order-tools \
  -H "Authorization: Bearer <kullanıcı access token'ı>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

2. Araçları listeleyin. Yanıt list_orders aracını içerir:

curl -s -X POST https://gateway.example.com/apigateway/order-tools \
  -H "Authorization: Bearer <kullanıcı access token'ı>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

3. Aracı çağırın:

curl -s -X POST https://gateway.example.com/apigateway/order-tools \
  -H "Authorization: Bearer <kullanıcı access token'ı>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_orders","arguments":{}}}'

Order Service API arka ucu bir Authorization: Bearer başlığı alır. Bu başlıktaki token yeni bir token'dır. Kullanıcının token'ı değildir. Çözülmüş claim'leri şunlardır:

{
  "sub": "ella.moore",
  "aud": "https://gateway.example.com/apigateway/order-service",
  "act": {"sub": "order-tools-gateway"},
  "client_id": "order-tools-gateway",
  "iss": "order-tools-gateway",
  "scope": "",
  "exp": 0
}

Claim	Anlam
`sub`	Kullanıcı. Hedef `ella.moore` kullanıcısını görür.
`act`	Kullanıcı adına çalışan ajan.
`aud`	Yalnız hedef. Token başka bir API için geçerli değildir.
`exp`	Kullanıcı token'ıyla aynı zaman. Delege token hiçbir zaman kullanıcı token'ından uzun yaşamaz.

Yanıtta refresh token yoktur.

B. Kendi Ajanınız Token'ı Değiştirir

Ajanınız, token exchange grant'ı ile delege token alır. Sonra hedefi çağırır.

Ajan istemcisini oluşturun

Projede bir uygulama (örneğin Order Assistant) oluşturun. Client credentials grant türünü kullanan gizli bir API istemcisi order-assistant oluşturun. Bir client secret oluşturun ve istemciyi etkinleştirin. Uygulamayı deploy edin.

Yeni bir uygulama İstemci Kimlik Bilgileri grant türüyle başlar. Uygulama zaten varsa uygulamayı açın, Token Ayarları sekmesine gidin, grant türü olarak İstemci Kimlik Bilgileri seçin ve kaydedin. Bu grant türü yoksa token değişimi unauthorized_client hatası ve "this client may not use token exchange" mesajı döndürür.

İzin verilen ajanları kontrol edin

order-assistant değerinin Order Service API proxy'sinin İzin verilen ajanlar listesinde olduğunu kontrol edin. Değeri Hedef API'yi Hazırlayın bölümünde eklediniz.

Subject token'ı alın

ella.moore kullanıcısının Order Service Tools proxy'sinden aldığı tarayıcı girişi access token'ını kullanın. Proxy ACL'den Yönet modunu ve /credential uç nokta ailesini kullanmalıdır.

Token'ı değiştirin

Token exchange isteğini gönderin. Ajan client kimliği ve client secret ile kimlik doğrular. subject_token değerini gövdede gönderin:

curl -s -X POST https://gateway.example.com/credential/token \
  -u "order-assistant:<client secret>" \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  --data-urlencode "subject_token=<kullanıcı access token'ı>" \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  --data-urlencode "resource=https://gateway.example.com/apigateway/order-service"

Yanıt delege token'ı içerir:

{"access_token":"…","issued_token_type":"urn:ietf:params:oauth:token-type:access_token","token_type":"Bearer","expires_in":899}

Hedefi çağırın

Hedefi delege token ile çağırın. Yanıt HTTP 200 olur:

curl -H "Authorization: Bearer <delege token>" \
  "https://gateway.example.com/apigateway/order-service/orders?status=open"

Delege token, A yolundakiyle aynı claim'lere sahiptir. sub kullanıcıdır, act ise order-assistant olur.

Token servisi yalnız bazı subject token'ları kabul eder. Tam liste için bkz. Token Exchange. Şu subject token'lar reddedilir:

Bu Politikadan Yönet modundaki (/auth) bir proxy'nin tarayıcı girişi token'ı.
Opaque token.
İptal edilmiş token.
Sıradan (MCP olmayan) bir API proxy'nin token'ı.

Hata Yanıtları

Yanıt	Neden
`{"error_description":"subject_token is not valid","error":"invalid_grant"}`	Token servisi subject token'ı kabul etmiyor. Token sıradan bir API proxy'den geliyor, opaque, iptal edilmiş ya da süresi dolmuş. Kullanıcı ya da kullanıcının istemcisi devre dışı.
`{"error_description":"the target does not accept this delegation","error":"invalid_target"}`	Hedef politika delege token'ları kabul etmiyor. Ajan İzin verilen ajanlar listesinde değil. Zincir, Yetki devri zinciri derinliği ayarının izin verdiğinden uzun.
`{"error_description":"URL has sensitive data! You must use 'application/x-www-form-urlencoded' header and form-data!","error":"invalid_request"}`	`subject_token` değerini URL sorgusunda gönderdiniz. Gövdede gönderin.
`{"error_description":"this client may not use token exchange","error":"unauthorized_client"}`	Ajanın API istemcisi client credentials grant'ını kullanamıyor.

Kullanıcının Rolleri

İstek kullanıcının güncel rolleriyle çalışır. Delege token'ın scope'u bu rolleri yalnız daraltabilir. OAuth Scope Adı olmayan rol taşınmaz.

Kurulumu Kontrol Etme

Hedef delege token'ları kabul etmiyorsa MCP proxy'sinin kaydı reddediliyor mu?
tools/list yanıtı list_orders aracını gösteriyor mu?
list_orders için tools/call hedefin siparişlerini döndürüyor mu?
Arka ucun aldığı token kullanıcı token'ından farklı mı; sub değeri ella.moore ve act değeri order-tools-gateway mi?
Delege token'ın exp değeri kullanıcı token'ının exp değerine eşit mi?
order-assistant token exchange isteği bir access_token döndürüyor mu?
Delege token ile /orders?status=open çağrısı HTTP 200 döndürüyor mu?
Sıradan bir API proxy'nin subject token'ı invalid_grant ile reddediliyor mu?
order-assistant değerini İzin verilen ajanlar listesinden kaldırınca token exchange invalid_target döndürüyor mu?
ella.moore kullanıcısının Order Service API ACL satırını kaldırınca çağrı reddediliyor mu?

Ne Kuracaksınız​

Ön Koşullar​

Hedef API'yi Hazırlayın​

Kullanıcının ACL satırı​

A. MCP Gateway'in Delege Kullanıcı Modu​

curl ile doğrulama​

B. Kendi Ajanınız Token'ı Değiştirir​

Hata Yanıtları​

Kullanıcının Rolleri​

Kurulumu Kontrol Etme​