𝗧𝗵𝗲 𝗢𝗽𝗲𝗻𝗜𝗗 𝗖𝗼𝗻𝗳𝗶𝗴𝘂𝗿𝗮𝘁𝗶𝗼𝗻 𝗙𝗶𝘅 𝗙𝗼𝗿 𝗠𝗖𝗣 𝗖𝗼𝗻𝗻𝗲𝗰𝘁𝗼𝗿𝘀

I spent too much time this week fixing a remote MCP connector.

The connector kept failing to find my OAuth server. The server was working fine. The issue was a single missing route and a redirect.

When you use OAuth with MCP, you expect discovery documents to work. Most tools look for these two paths:

  • /.well-known/oauth-authorization-server
  • /.well-known/oauth-protected-resource

These tell clients where to find authorization and token endpoints.

The problem is that many clients do not look for those specific paths. Instead, they look for /.well-known/openid-configuration.

This is an OpenID Connect path. It is a different spec, but it lives in the same place. My package did not register this path because it follows the OAuth spec, not the OIDC spec.

The client knocks on a door that does not exist. It gets a 404 error and quits.

I had two choices:

  1. Use a reverse-proxy redirect in Nginx. This is a lazy fix. It moves your logic out of your code and into your infrastructure. It is hard to test and easy to break during a deployment.

  2. Fix it inside the application. This is the better way.

I chose to make the app answer the probe. I created an alias that redirects the OpenID path to the OAuth authorization path.

I used a 308 Permanent Redirect.

A 302 redirect can change a POST request into a GET request. A 308 redirect is strict. It tells the client to go to the new URL and keep the same method and body. This is the correct way to handle a permanent move.

I also put this behind a configuration flag. This allows users to turn it off if they run their own OIDC discovery.

By doing this in the code, I can write tests:

  • One test checks if the redirect happens correctly.
  • One test follows the redirect to ensure the metadata is valid.

This ensures that if the metadata structure changes, my tests fail immediately. I find the error in my pipeline instead of finding it when a user cannot connect.

Specs often differ in practice. Even when two standards share similar goals, clients will pick different paths. As a server developer, you should answer both doors.

Point them to the same room, use the right redirect code, and back it up with tests.

Alias ของการตั้งค่า OpenID ที่เป็นที่รู้จักกันดี ซึ่งช่วยให้ MCP connectors ใช้งานได้ทันที

หากคุณเคยพยายามเชื่อมต่อ MCP (Model Context Protocol) connector เข้ากับ Identity Provider (IdP) คุณอาจจะพบว่าการต้องระบุ URL ของ endpoint ต่างๆ ด้วยตนเองนั้นเป็นเรื่องที่น่ารำคาญและเสี่ยงต่อความผิดพลาด

แต่มี "ทางลัด" หนึ่งที่ทำให้ทุกอย่างง่ายขึ้นมาก นั่นคือการใช้ endpoint .well-known/openid-configuration

ปัญหา: การตั้งค่าด้วยตนเอง (Manual Configuration)

เมื่อคุณต้องการให้ MCP connector ทำงานร่วมกับระบบ Authentication เช่น Auth0, Okta หรือ Google คุณจำเป็นต้องทราบข้อมูลสำคัญหลายอย่าง เช่น:

  • authorization_endpoint
  • token_endpoint
  • jwks_uri
  • issuer

หากไม่มีระบบอัตโนมัติ ผู้ใช้จะต้องคัดลอก URL เหล่านี้มาใส่ในไฟล์การตั้งค่าทีละรายการ ซึ่งนอกจากจะเสียเวลาแล้ว หาก IdP มีการเปลี่ยนแปลง URL เหล่านี้ในอนาคต Connector ของคุณก็จะใช้งานไม่ได้ทันที

ทางออก: OpenID Connect Discovery

OpenID Connect (OIDC) มีมาตรฐานที่เรียกว่า Discovery ซึ่งช่วยให้ Client (ในกรณีนี้คือ MCP connector) สามารถค้นหาข้อมูลการตั้งค่าทั้งหมดได้โดยอัตโนมัติจาก URL เพียง URL เดียว

ความมหัศจรรย์นี้เกิดขึ้นผ่าน endpoint ที่เป็นมาตรฐานคือ: https://<your-issuer-url>/.well-known/openid-configuration

มันทำงานอย่างไร?

เมื่อ MCP connector ได้รับ URL ของ Issuer (เช่น https://accounts.google.com) มันจะทำการส่งคำขอ GET ไปยัง https://accounts.google.com/.well-known/openid-configuration

Server จะตอบกลับมาเป็น JSON object ที่บรรจุข้อมูลการตั้งค่าทั้งหมดที่จำเป็น เช่น:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

ด้วยข้อมูลนี้ MCP connector ไม่จำเป็นต้องถามผู้ใช้ว่า "token endpoint คืออะไร?" หรือ "ต้องใช้ key ไหนในการตรวจสอบ signature?" มันสามารถอ่านค่าจาก JSON นี้และเริ่มทำงานได้ทันที

ทำไมสิ่งนี้ถึงสำคัญสำหรับ MCP?

MCP (Model Context Protocol) กำลังกลายเป็นมาตรฐานใหม่ในการเชื่อมต่อ AI models เข้ากับข้อมูลและเครื่องมือต่างๆ เมื่อเราต้องการเพิ่มความปลอดภัยให้กับเครื่องมือเหล่านี้ การใช้ OIDC เพื่อทำ Authentication จึงเป็นเรื่องจำเป็น

การรองรับ .well-known/openid-configuration ช่วยให้:

  1. ลดความซับซ้อน (Reduced Complexity): ผู้ใช้เพียงแค่ระบุ Issuer URL เท่านั้น
  2. เพิ่มความทนทาน (Increased Robustness): หาก IdP เปลี่ยนแปลง endpoint การตั้งค่าจะอัปเดตโดยอัตโนมัติ
  3. ประสบการณ์ผู้ใช้ที่ดีขึ้น (Better UX): การตั้งค่าทำได้รวดเร็วและแทบไม่ต้องใช้ความรู้ทางเทคนิคเชิงลึก

สรุป

การใช้ alias .well-known/openid-configuration อาจดูเหมือนเป็นเรื่องเล็กน้อย แต่สำหรับนักพัฒนา MCP connectors มันคือสิ่งที่เปลี่ยนจาก "การตั้งค่าที่ยุ่งยาก" ให้กลายเป็น "การเชื่อมต่อที่ใช้งานได้ทันที"