إصلاح إعدادات OpenID لموصلات MCP
قضيت الكثير من الوقت هذا الأسبوع في إصلاح موصل MCP عن بُعد.
استمر الموصل في الفشل في العثور على خادم OAuth الخاص بي. كان الخادم يعمل بشكل جيد، لكن المشكلة كانت تكمن في مسار واحد مفقود وإعادة توجيه.
عندما تستخدم OAuth مع MCP، تتوقع أن تعمل مستندات الاكتشاف (discovery documents). تبحث معظم الأدوات عن هذين المسارين:
- /.well-known/oauth-authorization-server
- /.well-known/oauth-protected-resource
تخبر هذه المسارات العملاء (clients) بمكان العثور على نقاط نهاية التفويض (authorization endpoints) والرموز (token endpoints).
المشكلة هي أن العديد من العملاء لا يبحثون عن تلك المسارات المحددة، بل يبحثون بدلاً من ذلك عن /.well-known/openid-configuration.
هذا مسار OpenID Connect. إنه مواصفة (spec) مختلفة، لكنها توجد في نفس المكان. لم تقم الحزمة (package) الخاصة بي بتسجيل هذا المسار لأنها تتبع مواصفات OAuth وليس مواصفات OIDC.
يطرق العميل باباً غير موجود، فيتلقى خطأ 404 ويتوقف عن العمل.
كان أمامي خياران:
استخدام إعادة توجيه عبر وكيل عكسي (reverse-proxy redirect) في Nginx. هذا حل كسول، لأنه ينقل المنطق (logic) من الكود الخاص بك إلى البنية التحتية (infrastructure). كما أنه يصعب اختباره ومن السهل تعطيله أثناء عملية النشر (deployment).
إصلاحه داخل التطبيق. وهذا هو الحل الأفضل.
اخترت جعل التطبيق يستجيب للاستعلام. قمت بإنشاء اسم مستعار (alias) يعيد توجيه مسار OpenID إلى مسار تفويض OAuth.
استخدمت 308 Permanent Redirect.
يمكن لإعادة التوجيه 302 أن يحول طلب POST إلى طلب GET، أما إعادة التوجيه 308 فهي صارمة؛ حيث تخبر العميل بالانتقال إلى عنوان URL الجديد مع الحفاظ على نفس الطريقة (method) وجسم الطلب (body). هذه هي الطريقة الصحيحة للتعامل مع الانتقال الدائم.
كما وضعت هذا خلف علامة تكوين (configuration flag)، مما يسمح للمستخدمين بإيقافه إذا كانوا يقومون بتشغيل عملية اكتشاف OIDC الخاصة بهم.
من خلال القيام بذلك في الكود، يمكنني كتابة اختبارات:
- اختبار يتحقق مما إذا كانت إعادة التوجيه تتم بشكل صحيح.
- اختبار يتبع إعادة التوجيه للتأكد من أن البيانات الوصفية (metadata) صالحة.
يضمن ذلك أنه في حال تغير هيكل البيانات الوصفية، ستفشل اختباراتي فوراً. وبذلك أكتشف الخطأ في خط أنابيب العمل (pipeline) الخاص بي بدلاً من اكتشافه عندما لا يتمكن المستخدم من الاتصال.
غالباً ما تختلف المواصفات في الممارسة العملية. فحتى عندما يتشارك معياران أهدافاً متشابهة، قد يختار العملاء مسارات مختلفة. كمطور خادم، يجب عليك أن تستجيب لكلا البابين.
وجههم إلى نفس الغرفة، واستخدم رمز إعادة التوجيه الصحيح، وادعم ذلك بالاختبارات.
الاسم المستعار لتكوين OpenID المعروف الذي يجعل موصلات MCP تعمل بسلاسة
إذا كنت قد حاولت من قبل بناء موصل MCP (Model Context Protocol) لمزود هوية، فأنت تدرك حجم المعاناة. ستحتاج إلى تكوين نقطة نهاية المصادقة (authorization endpoint)، ونقطة نهاية الرمز (token endpoint)، وURI الخاص بـ JWKS، والمزيد يدويًا. إنها عملية مرهقة وعرضة للأخطاء.
ولكن هناك طريقة أفضل، وهي استخدام نقطة النهاية .well-known/openid-configuration.
تعد نقطة النهاية هذه جزءًا من مواصفات اكتشاف OpenID Connect. فهي تتيح للعملاء اكتشاف تكوين مزود OpenID (OP) تلقائيًا.
باستخدام نقطة النهاية هذه، يمكن أن تصبح موصلات MCP أكثر قوة وأسهل في التنفيذ. فبدلاً من مطالبة المستخدمين بمجموعة من عناوين URL المختلفة، يمكنك ببساطة طلب عنوان URL الخاص بالمُصدر (issuer URL) ثم جلب التكوين من .well-known/openid-configuration.
هذا يجعل عملية التكامل سلسة ويقلل من العقبات أمام كل من المطورين والمستخدمين.