𝗧𝗵𝗲 𝗢𝗽𝗲𝗻𝗜𝗗 𝗖𝗼𝗻𝗳𝗶𝗴𝘂𝗿𝗮𝘁𝗶𝗼𝗻 𝗙𝗶𝘅 𝗙𝗼𝗿 𝗠𝗖𝗣 𝗖𝗼𝗻𝗻𝗲𝗰𝘁𝗼𝗿𝘀
Bu hafta uzak bir MCP bağlayıcısını düzeltmek için çok fazla zaman harcadım.
Bağlayıcı, OAuth sunucumu bulmakta sürekli başarısız oluyordu. Sunucu sorunsuz çalışıyordu. Sorun, tek bir eksik rota ve bir yönlendirmeydi.
MCP ile OAuth kullandığınızda, keşif belgelerinin (discovery documents) çalışmasını beklersiniz. Çoğu araç şu iki yolu arar:
- /.well-known/oauth-authorization-server
- /.well-known/oauth-protected-resource
Bunlar, istemcilere yetkilendirme ve token uç noktalarını (endpoints) nerede bulacaklarını söyler.
Sorun şu ki, birçok istemci bu özel yolları aramıyor. Bunun yerine /.well-known/openid-configuration yolunu arıyorlar.
Bu bir OpenID Connect yoludur. Farklı bir spesifikasyondur ancak aynı yerde bulunur. Paketim bu yolu kaydetmemişti çünkü OIDC spesifikasyonunu değil, OAuth spesifikasyonunu takip ediyordu.
İstemci, var olmayan bir kapıyı çalıyor. 404 hatası alıyor ve duruyor.
İki seçeneğim vardı:
Nginx'te bir reverse-proxy yönlendirmesi kullanmak. Bu tembelce bir çözümdür. Mantığınızı kodunuzdan çıkarıp altyapınıza taşır. Test etmesi zordur ve dağıtım (deployment) sırasında bozulmaya müsaittir.
Uygulama içinde düzeltmek. Bu daha iyi bir yoldur.
Uygulamanın bu sorguya yanıt vermesini sağlamayı seçtim. OpenID yolunu OAuth yetkilendirme yoluna yönlendiren bir takma ad (alias) oluşturdum.
308 Permanent Redirect kullandım.
302 yönlendirmesi bir POST isteğini GET isteğine dönüştürebilir. 308 yönlendirmesi ise katıdır. İstemciye yeni URL'ye gitmesini ve aynı metodu ve gövdeyi (body) korumasını söyler. Kalıcı bir taşıma işlemini yönetmenin doğru yolu budur.
Ayrıca bunu bir yapılandırma bayrağının (configuration flag) arkasına koydum. Bu, kullanıcıların kendi OIDC keşiflerini çalıştırıyorlarsa bunu kapatmalarına olanak tanır.
Bunu kod içinde yaparak testler yazabiliyorum:
- Bir test, yönlendirmenin doğru şekilde gerçekleşip gerçekleşmediğini kontrol eder.
- Bir test, meta verilerin geçerli olduğundan emin olmak için yönlendirmeyi takip eder.
Bu, meta veri yapısı değişirse testlerimin anında başarısız olmasını sağlar. Hatayı, bir kullanıcı bağlanamadığında değil, kendi pipeline'ımda bulurum.
Spesifikasyonlar pratikte genellikle farklılık gösterir. İki standart benzer hedefleri paylaşsa bile, istemciler farklı yollar seçebilir. Bir sunucu geliştiricisi olarak, her iki kapıya da yanıt vermelisiniz.
Onları aynı odaya yönlendirin, doğru yönlendirme kodunu kullanın ve bunu testlerle destekleyin.
MCP konektörlerinin sorunsuz çalışmasını sağlayan .well-known/openid-configuration takma adı
MCP (Model Context Protocol), yapay zeka modellerinin harici araçlar ve veri kaynaklarıyla etkileşime girmesine olanak tanıyan yeni bir standarttır. Ekosistem büyüdükçe, kimlik doğrulama (authentication) kritik bir parça haline geliyor.
Modern web uygulamalarında kimlik doğrulamayı yönetmenin en yaygın yollarından biri OpenID Connect (OIDC) kullanmaktır. Peki, tamamen farklı bir ortamda çalışıyor olabilecek bir MCP konektörü, bir OIDC sağlayıcısı ile nasıl iletişim kuracağını nasıl bilebilir?
Cevap, "well-known" (bilinen) bir gelenekte yatıyor: .well-known/openid-configuration uç noktası.
OIDC Discovery Nedir?
OIDC Discovery, istemcilerin bir OpenID Sağlayıcısının (OP) yapılandırmasını otomatik olarak keşfetmesine olanak tanıyan bir mekanizmadır. Her bir uç noktayı (yetkilendirme uç noktası, token uç noktası vb.) tek tek kod içine yazmak (hardcoding) yerine, istemcinin yalnızca sağlayıcının (issuer) temel URL'sini bilmesi yeterlidir.
Nasıl Çalışır?
Bir MCP konektörü, örneğin https://auth.example.com gibi bir sağlayıcı URL'si ile yapılandırıldığında, işlem burada bitmez. Otomatik olarak bu URL'nin sonuna /.well-known/openid-configuration ekler ve bir GET isteği gerçekleştirir.
Yanıt, şuna benzer bir JSON nesnesidir:
{
"issuer": "https://auth.example.com",
"authorization_endpoint": "https://auth.example.com/authorize",
"token_endpoint": "https://auth.example.com/token",
"userinfo_endpoint": "https://auth.example.com/userinfo",
"jwks_uri": "https://auth.example.com/keys",
"scopes_supported": ["openid", "profile", "email"],
"response_types_supported": ["code", "id_token"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256"]
}
Bu MCP İçin Neden Önemli?
MCP konektörleri genellikle genel (generic) ve yeniden kullanılabilir olacak şekilde tasarlanır. .well-known/openid-configuration uç noktasına güvenerek, geliştiriciler her farklı kimlik sağlayıcısı (Okta, Auth0, Google vb.) için özel mantık yazmak zorunda kalmazlar.
Bir sağlayıcı OIDC discovery spesifikasyonuna uyduğu sürece, MCP konektörü şunları yapabilir:
- Doğru uç noktaları bulabilir.
- Token'ları doğrulamak için genel anahtarları (JWKS) alabilir.
- Hangi kapsamların (scopes) mevcut olduğunu anlayabilir.
Bu "sorunsuz çalışma" (just works) deneyimi, protokolü sağlam ve benimsenmesi kolay kılan temel unsurdur.