La correction de la configuration OpenID pour les connecteurs MCP
Cette semaine, j'ai passé trop de temps à réparer un connecteur MCP distant.
Le connecteur ne parvenait pas à trouver mon serveur OAuth. Le serveur fonctionnait pourtant parfaitement. Le problème venait d'une seule route manquante et d'une redirection.
Lorsque vous utilisez OAuth avec MCP, vous vous attendez à ce que les documents de découverte fonctionnent. La plupart des outils recherchent ces deux chemins :
- /.well-known/oauth-authorization-server
- /.well-known/oauth-protected-resource
Ceux-ci indiquent aux clients où trouver les points de terminaison d'autorisation et de jeton.
Le problème est que de nombreux clients ne recherchent pas ces chemins spécifiques. À la place, ils cherchent /.well-known/openid-configuration.
Il s'agit d'un chemin OpenID Connect. C'est une spécification différente, mais elle se trouve au même endroit. Mon package n'enregistrait pas ce chemin car il suit la spécification OAuth, et non la spécification OIDC.
Le client frappe à une porte qui n'existe pas. Il reçoit une erreur 404 et s'arrête.
J'avais deux choix :
Utiliser une redirection via un reverse-proxy dans Nginx. C'est une solution de facilité. Cela déplace votre logique hors de votre code pour la placer dans votre infrastructure. C'est difficile à tester et facile à casser lors d'un déploiement.
Corriger le problème à l'intérieur de l'application. C'est la meilleure approche.
J'ai choisi de faire en sorte que l'application réponde à la requête. J'ai créé un alias qui redirige le chemin OpenID vers le chemin d'autorisation OAuth.
J'ai utilisé une redirection permanente 308.
Une redirection 302 peut transformer une requête POST en une requête GET. Une redirection 308 est stricte. Elle indique au client de se rendre sur la nouvelle URL tout en conservant la même méthode et le même corps. C'est la manière correcte de gérer un déplacement permanent.
J'ai également placé cela derrière un drapeau de configuration. Cela permet aux utilisateurs de le désactiver s'ils gèrent leur propre découverte OIDC.
En faisant cela dans le code, je peux écrire des tests :
- Un test vérifie si la redirection s'effectue correctement.
- Un test suit la redirection pour s'assurer que les métadonnées sont valides.
Cela garantit que si la structure des métadonnées change, mes tests échouent immédiatement. Je détecte l'erreur dans mon pipeline plutôt que de la découvrir lorsqu'un utilisateur ne parvient pas à se connecter.
En pratique, les spécifications diffèrent souvent. Même lorsque deux standards partagent des objectifs similaires, les clients choisiront des chemins différents. En tant que développeur de serveur, vous devriez répondre aux deux portes.
Dirigez-les vers la même pièce, utilisez le bon code de redirection et appuyez le tout par des tests.
L'alias bien connu .well-known/openid-configuration qui permet aux connecteurs MCP de fonctionner sans accroc
Si vous travaillez sur le Model Context Protocol (MCP) ces derniers temps, vous avez peut-être remarqué que l'authentification est un obstacle de taille. Pour qu'un connecteur MCP soit vraiment utile, il doit souvent accéder à des ressources protégées, ce qui signifie qu'il doit gérer l'authentification et l'autorisation.
La manière la plus simple de le faire est d'utiliser OpenID Connect (OIDC). Mais comment faciliter la configuration des fournisseurs d'identité pour les utilisateurs ?
La réponse est le point de terminaison .well-known/openid-configuration.
Qu'est-ce que la découverte OIDC ?
OpenID Connect (OIDC) est une couche d'identité au-dessus du protocole OAuth 2.0. L'une de ses fonctionnalités les plus puissantes est la « découverte » (Discovery).
La découverte permet à un client (comme un connecteur MCP) de trouver automatiquement les détails de configuration d'un fournisseur d'identité (IdP) en interrogeant un point de terminaison bien connu.
Au lieu de demander à l'utilisateur :
- L'URL du point de terminaison d'autorisation (
authorization endpoint) - L'URL du point de terminaison de jeton (
token endpoint) - L'URI JWKS (pour vérifier les signatures)
- Les scopes, etc.
Vous n'avez besoin de demander que l'URL de l'émetteur (Issuer URL).
En ajoutant .well-known/openid-configuration à l'URL de l'émetteur, le client peut récupérer un document JSON qui contient toutes les métadonnées nécessaires.
Comment cela fonctionne avec MCP
Lorsque vous construisez un connecteur MCP, vous voulez que le processus de configuration soit aussi fluide que possible.
Si vous implémentez la découverte OIDC, le flux utilisateur ressemble à ceci :
- L'utilisateur fournit l'URL de son fournisseur d'identité (par exemple,
https://accounts.google.com). - Le connecteur MCP récupère
https://accounts.google.com/.well-known/openid-configuration. - Le connecteur sait désormais exactement où envoyer l'utilisateur pour se connecter et où échanger le code contre un jeton.
Cela permet à votre connecteur de « fonctionner sans accroc » avec presque n'importe quel fournisseur moderne compatible avec OIDC.
Résumé
L'alias .well-known/openid-configuration est un élément petit mais puissant de la spécification OIDC. Pour les développeurs MCP, l'exploitation de ce mécanisme de découverte est la clé pour construire des flux d'authentification fluides et prêts pour l'entreprise.