Identifiants par utilisateur avec une passerelle OAuth

Cette page explique comment laisser chaque personne utiliser votre serveur avec ses propres droits sur votre API, grâce à une passerelle OAuth placée devant Voozeo. Voozeo ne stocke aucun identifiant.

Principe

Par défaut, un serveur appelle votre API avec un secret unique, partagé par tous. Avec le type d'authentification « Transmis par l'appelant », Voozeo transmet à la place à votre API, pour chaque appel d'outil, un en-tête reçu sur l'appel MCP : même nom, même valeur.

1. L'IA se connecte à une passerelle OAuth, pas à Voozeo.
2. Sur la page de consentement de la passerelle, la personne saisit son propre identifiant pour votre API (un jeton, une clé).
3. Pour chaque appel, la passerelle le relaie vers l'URL de votre serveur qui contient la clé (https://mcp.example.com/k/<clé>/mcp), en ajoutant l'en-tête, par exemple Authorization: Bearer <jeton>.
4. Voozeo transmet cet en-tête tel quel à votre API : chaque utilisateur agit avec ses propres droits. Rien n'est stocké, ni l'identifiant ni une copie.

Réglage

1. Dans l'onglet « API cible », choisissez « Transmis par l'appelant ». Le champ « Nom de l'en-tête » est prérempli avec authorization ; saisissez un autre nom si votre API attend un autre en-tête (par exemple X-User-Token). Certains noms, gérés par Voozeo ou par le réseau, sont refusés (host, cookie, content-type, user-agent, les noms commençant par x-forwarded-, x-amz-, x-amzn- ou mcp-…). Cliquez sur « Enregistrer ».
2. Si le serveur utilisait OAuth 2.0 auparavant, il n'a plus de clé MCP active après le changement et l'onglet « Connexion » l'indique : régénérez la clé. La clé reste indispensable : la passerelle l'envoie dans l'URL.
3. Dans l'onglet « Connexion », le bloc « Passerelle OAuth » donne l'URL https://mcp.example.com/k/<clé>/mcp à déclarer dans la passerelle (la vraie est dans l'onglet, avec <YOUR_KEY> tant que vous n'avez pas régénéré la clé).

Cette URL contient la clé du serveur : ne la donnez pas aux utilisateurs, seulement à la passerelle. Si l'en-tête est Authorization, seule cette URL peut transmettre l'identifiant : sur l'URL où la clé voyage dans l'en-tête Authorization, cet en-tête est la clé MCP et n'est jamais transmis. L'onglet « Connexion » masque alors les blocs qui utilisent cette URL. Avec un autre en-tête, les deux URL fonctionnent.

Exemple avec CKOAuth

Dans CKOAuth, créez un connecteur en mode bearer (ou en mode header si votre API attend un autre en-tête) dont la cible est l'URL https://mcp.example.com/k/<clé>/mcp. En mode header, saisissez le nom d'en-tête réglé dans Voozeo ; ajoutez le préfixe facultatif attendu par votre API, par exemple Bearer . L'IA se connecte à CKOAuth en OAuth, la personne saisit son identifiant sur la page de consentement, et CKOAuth l'injecte à chaque appel.

Dans le bac à sable

Pour un serveur à identifiant transmis, l'onglet « Test » affiche un champ masqué « Identifiant transmis » pour les outils de l'API : saisissez la valeur exacte attendue par votre API, par exemple Bearer abc123. Elle est envoyée pour cette exécution seulement et gardée dans la mémoire de l'onglet : elle n'est pas stockée et disparaît quand vous quittez la page. Sans valeur, l'outil de l'API est refusé (CREDENTIAL_REQUIRED) sans compter dans votre quota. Les outils documents n'en ont pas besoin.

Limites

• Un serveur n'a qu'une seule clé : la passerelle l'utilise pour tous les utilisateurs. Les quotas sont partagés par tous les utilisateurs du serveur.
• Un identifiant changé ou révoqué apparaît comme une erreur d'outil appel_http avec le statut 401 ou 403 dans le Journal des appels.
• Quand l'en-tête manque à l'appel, l'IA reçoit une erreur d'outil Missing credential: the "<name>" header is required by this server. ; l'appel n'est pas compté.
• Le mode diagnostic du journal ne capture jamais l'identifiant : il est masqué.