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

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 ya usanidi wa OpenID inayojulikana inayofanya viunganishi vya MCP kufanya kazi kwa urahisi

Je, umewahi kujiuliza kwa nini baadhi ya mifumo ya utambulisho (identity systems) inaonekana rahisi sana kuunganishwa? Siri haipo kwenye utata, bali ipo kwenye urahisi wa kiwango cha kimataifa kinachoitwa OpenID Connect (OIDC) Discovery.

Katika muktadha wa Model Context Protocol (MCP), uwezo huu wa "kujigundua" ni muhimu sana kwa viunganishi (connectors) kufanya kazi bila hitaji la kuingiza mipangilio mingi kwa mkono.

Ugunduzi wa OpenID Connect (OIDC) ni nini?

Kawaida, unapotaka kuunganisha programu yako na mfumo wa utambulisho (kama vile Google, Okta, au Auth0), unahitaji taarifa kadhaa:

  • URL ya kutoa uthibitisho (Authorization endpoint)
  • URL ya kutoa tokeni (Token endpoint)
  • URL ya funguo za umma (JWKS URI)
  • Mbinu zinazokubalika (Supported scopes/methods)

Badala ya kuomba taarifa hizi zote moja baada ya nyingine, OIDC inatoa njia moja rahisi. Ikiwa unajua URL ya msingi ya mfumo (Issuer URL), unaweza kupata kila kitu kwa kutembelea endpoint maalum:

/.well-known/openid-configuration

Hii ni hati ya JSON inayobeba metadata yote inayohitajika ili mteja (client) aweze kuwasiliana na mfumo wa utambulisho kwa usahihi.

Kwa nini ni muhimu kwa MCP?

Model Context Protocol (MCP) inalenga kuunganisha mifumo ya AI na vyanzo vya data kwa urahisi. Viunganishi vya MCP mara nyingi vinahitaji utambulisho wa salama ili kupata ufikiaji wa data.

Bila OIDC Discovery, kila kiunganishi cha MCP kingehitaji kuandikwa kwa mkono (hardcoded) mipangilio yote ya utambulisho. Hii ingesababisha:

  1. Makosa mengi: Mipangilio isiyo sahihi ingesababisha kushindwa kwa muunganisho.
  2. Ugumu wa kusasisha: Ikiwa mfumo wa utambulisho utabadilisha URL zake, kila kiunganishi kingehitaji kusasishwa.
  3. Utegemezi mkubwa: Kutokuwa na uwezo wa kuunganishwa na mifumo mipya kwa urahisi.

Kwa kutumia alias ya .well-known/openid-configuration, kiunganishi cha MCP kinaweza kuchukua tu issuer_url na kisha "kujigundulia" mipangilio mingine yote inayohitajika. Hii inafanya mchakato wa kuunganisha kuwa wa "plug-and-play".

Inavyofanya kazi (Mchakato)

Huu hapa ni mchakato wa jinsi kiunganishi cha MCP kinavyotumia alias hii:

  1. Kupata Issuer URL: Mtumiaji anatoa URL ya msingi (mfano: https://auth.example.com).
  2. Kuunda Endpoint: Kiunganishi kinachukua URL hiyo na kuongeza /.well-known/openid-configuration mwishoni.
  3. Kusoma Metadata: Kiunganishi kinapata hati ya JSON na kusoma thamani kama token_endpoint, userinfo_endpoint, n.k.
  4. Kuanza Utambulisho: Kiunganishi sasa kinaweza kuanza mchakato wa OAuth2/OIDC kwa kutumia njia sahihi zilizogunduliwa.

Hitimisho

Alias ya .well-known/openid-configuration inaonekana kama kitu kidogo, lakini ni injini inayowezesha mifumo ya kisasa ya utambulisho kufanya kazi kwa urahisi na usalama. Kwa MCP, hii inamaanisha viunganishi vinaweza kuwa nafuu zaidi, salama zaidi, na rahisi zaidi kutumia kwa watumiaji wa AI.