Chaque équipe API se heurte au même mur. Les points d'accès fonctionnent de manière isolée, puis quelqu'un active OAuth 2.0 et la moitié de la suite de tests commence à renvoyer des 401. Soudain, vous jonglez avec des serveurs d'autorisation, des jetons d'accès de courte durée et des étendues (scopes), et copier manuellement des jetons d'une réponse curl vers un champ d'en-tête devient fastidieux dès la troisième exécution.
La solution n'est pas de sauter l'authentification dans vos tests. C'est de faire de la gestion des jetons une partie de la configuration des tests afin que cela cesse d'être un travail manuel. Ce guide couvre les deux flux que vous rencontrerez dans presque tous les plans de test : le flux de code d'autorisation OAuth (avec PKCE) pour les API agissant au nom d'un utilisateur, et le flux d'informations d'identification du client pour les appels de machine à machine. Si vous voulez d'abord la carte complète des octrois, notre aperçu des flux OAuth 2.0 les passe tous en revue.
Ensuite, nous passons à la pratique : configurer l'authentification OAuth 2.0 dans Apidog, récupérer un jeton une seule fois et le réutiliser pour plusieurs requêtes, laisser les jetons expirés se rafraîchir automatiquement, hériter de l'authentification au niveau des dossiers, et tester les chemins d'échec que votre examen de sécurité demandera.
Les deux flux qui comptent pour les tests d'API
OAuth 2.0 définit plusieurs types d'octroi, mais pour les tests d'API quotidiens, vous passerez la plupart de votre temps avec deux d'entre eux. Choisissez en fonction d'une question : l'API agit-elle au nom d'un utilisateur, ou au nom d'un service ?
Flux de code d'autorisation, avec PKCE
Le flux de code d'autorisation est le moyen standard d'obtenir un jeton lié à un utilisateur. Le client envoie l'utilisateur au serveur d'autorisation, l'utilisateur se connecte et consent, le serveur redirige avec un code à usage unique, et le client échange le code contre un jeton d'accès au point de terminaison de jeton. La RFC 6749 définit l'ensemble du processus dans la section 4.1.
PKCE (Proof Key for Code Exchange, RFC 7636) renforce l'échange. Le client génère un vérificateur aléatoire, envoie un défi haché avec la demande d'autorisation, puis prouve qu'il détient le vérificateur original lors du rachat du code. Un attaquant qui intercepte le code ne peut pas l'utiliser. PKCE a commencé comme une solution pour les applications mobiles, mais les directives actuelles de oauth.net le recommandent pour chaque échange de code d'autorisation, y compris les clients confidentiels.
Testez avec ce flux chaque fois que le comportement du point de terminaison dépend de l'identité de l'utilisateur : GET /orders ne renvoyant que les commandes de l'appelant, les points de terminaison d'administration à accès restreint par rôle, les limites de débit par utilisateur.
Flux d'informations d'identification du client
L'octroi d'informations d'identification du client OAuth 2.0 ignore entièrement l'utilisateur. Le client s'authentifie avec son propre ID et secret et reçoit un jeton représentant l'application elle-même. Un POST au point de terminaison de jeton, pas de navigateur, pas de redirection :
curl -X POST https://auth.example.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=orders_service \
-d client_secret=s3cr3t_value \
-d scope="orders:read orders:write"
C'est le flux pour les API de machine à machine : microservices internes, tâches cron, pipelines CI appelant une API de déploiement. C'est aussi le cheval de bataille des tests automatisés, car il ne nécessite aucune intervention humaine. Si votre environnement de test vous permet de provisionner un client de test, utilisez les informations d'identification du client pour tout, sauf les cas où l'identité de l'utilisateur est l'objet du test.
Configuration de l'authentification OAuth 2.0 dans Apidog
Apidog traite OAuth 2.0 comme un type d'authentification de première classe. Vous le configurez une fois, dans l'onglet "Auth" d'une requête ou d'un dossier, et la plateforme gère la récupération, l'attachement et le rafraîchissement des jetons. Les types d'octroi pris en charge incluent le Code d'autorisation, le Code d'autorisation (avec PKCE), les Identifiants client, les Identifiants de mot de passe et Implicite.
Voici la configuration des deux flux ci-dessus, en utilisant une API de gestion de commandes fictive.
Configuration des informations d'identification du client
Ouvrez la requête (ou mieux, le dossier ; plus d'informations ci-dessous), changez le type d'authentification en OAuth 2.0 et choisissez "Client Credentials" comme type d'octroi. Remplissez :
- URL du jeton d'accès :
https://auth.example.com/oauth/token - ID client :
orders_service - Secret client : votre secret provisionné
- Étendue (Scope) :
orders:read orders:write(défini sous les options avancées)
Apidog vous offre deux façons de fournir les informations d'identification : en tant qu'en-tête Basic Auth ou dans le corps de la requête. Adaptez-vous à ce que votre serveur d'autorisation attend ; Auth0 et Okta acceptent les deux, mais certains serveurs internes ne parsènt que le corps.
Cliquez sur Obtenir le jeton. Apidog appelle le point de terminaison du jeton, stocke le résultat et affiche le jeton ainsi que sa période de validité. À partir de ce moment, chaque envoi l'attache à l'en-tête Authorization avec le préfixe Bearer. Pas de copier-coller, pas de plomberie de variable {{token}}.
Configuration du code d'autorisation avec PKCE
Pour les tests de contexte utilisateur, choisissez "Authorization Code (With PKCE)" comme type d'octroi. PKCE est une option d'octroi distincte dans Apidog, pas une case à cocher. Vous aurez besoin de quelques champs supplémentaires :
- URL d'authentification :
https://auth.example.com/oauth/authorize - URL du jeton d'accès :
https://auth.example.com/oauth/token - URL de rappel : l'URI de redirection enregistrée auprès de votre fournisseur
- ID client et Secret client : de votre enregistrement d'application OAuth
Cliquez sur Obtenir le jeton et Apidog ouvre une fenêtre de navigateur pointant vers la page de connexion. Connectez-vous en tant qu'utilisateur de test, approuvez l'écran de consentement, et le jeton est renvoyé et atterrit dans le même emplacement géré qu'auparavant. Si votre fournisseur renvoie un jeton d'identification OpenID Connect en même temps que le jeton d'accès, une option "Type de jeton utilisé" vous permet de choisir lequel est attaché ; utile lorsque l'API testée valide les jetons d'identification.
Un conseil pratique : conservez un utilisateur de test dédié par rôle que vous devez couvrir (acheteur, administrateur, auditeur en lecture seule). Récupérer un jeton pour chaque utilisateur et réexécuter le même scénario est le moyen le plus rapide de vérifier les règles d'accès basées sur les rôles.
Réutilisation et rafraîchissement automatique des jetons
Les jetons d'accès expirent, généralement en moins d'une heure. Avant qu'Apidog ne gère cela, un jeton expiré signifiait un échec d'exécution et une nouvelle récupération manuelle, ce qui est exactement le genre d'échec instable que les équipes apprennent à ignorer.
Maintenant, Apidog rafraîchit les jetons OAuth 2.0 par lui-même lorsque le serveur d'autorisation a émis un jeton de rafraîchissement, une fonctionnalité livrée dans la mise à jour de juin. Lorsque le jeton d'accès stocké expire, Apidog utilise le jeton de rafraîchissement pour en obtenir un nouveau et le remplace avant l'envoi. Vous pouvez également pointer vers une URL de jeton de rafraîchissement personnalisée dans les paramètres avancés si votre fournisseur sépare les deux points de terminaison.
Pour les informations d'identification du client, de nombreux serveurs ignorent entièrement les jetons de rafraîchissement (la spécification l'autorise, car le client peut se réauthentifier à tout moment). En pratique, cela ne pose pas de problème : une nouvelle récupération avec Obtenir le jeton se fait en un clic, et les exécutions planifiées ou CI peuvent demander un nouveau jeton au début de chaque exécution.
Hériter de l'authentification au niveau du dossier
Configurer OAuth sur chaque requête n'est pas la bonne approche. Apidog vous permet de définir l'authentification sur un dossier, et les requêtes qu'il contient héritent de la configuration de leur parent. Définissez OAuth 2.0 une fois sur votre dossier "API Commandes" et toutes les requêtes qu'il contient, y compris les nouvelles que vos coéquipiers ajouteront au prochain sprint, enverront le même jeton géré.
Ceci est particulièrement important dans les scénarios de test en plusieurs étapes. Un scénario de paiement pourrait enchaîner POST /carts, POST /carts/{id}/items et POST /orders. Avec l'authentification au niveau du dossier, les trois étapes partagent un seul jeton et une seule configuration. Lorsque le jeton expire au milieu du scénario, le rafraîchissement automatique le prend en charge. Et lorsque votre équipe de sécurité fait pivoter le secret client, vous mettez à jour un seul dossier au lieu de quarante requêtes.
Les requêtes conservent la possibilité de remplacer le parent, ce qui est exactement ce que vous voulez pour les tests négatifs. Plus d'informations à ce sujet maintenant.
Tester les chemins d'échec
Les tests OAuth "chemin heureux" prouvent que votre pipeline de jetons fonctionne. Les tests "chemin d'échec" prouvent que votre API applique l'authentification. Si vous les ignorez, vous vous fiez aux paramètres par défaut du framework. Voici les trois cas qu'il est utile d'automatiser ; pour un rappel sur la signification de chaque code d'état, consultez notre comparaison des clés API et des jetons Bearer.
Jeton expiré ou manquant : attendez un 401
Dupliquez une requête dans votre scénario et remplacez son authentification héritée par aucune authentification ou un jeton Bearer codé en dur, longtemps expiré, tel que Bearer expired_token_do_not_rotate. Affirmez sur :
- Le code d'état est égal à
401 - L'en-tête de réponse
WWW-Authenticateest présent (la RFC 6750, compagnon de la RFC 6749, l'attend) - Le corps ne divulgue pas de traces de pile ou de noms d'hôtes internes
Un 200 ici est une erreur critique. Un 403 est une mauvaise conception qui mérite un ticket : le serveur doit distinguer "Je ne sais pas qui vous êtes" de "Je vous connais, et non."
Mauvaise étendue (scope) : attendez un 403
Provisionnez un second client de test limité à orders:read, récupérez son jeton et appelez un point de terminaison d'écriture comme POST /orders. Affirmez que le statut est 403 et, si votre API suit la RFC 6750, l'en-tête WWW-Authenticate inclut error="insufficient_scope". Ce test détecte la mauvaise configuration classique où les étendues sont vérifiées à la passerelle pour certaines routes et oubliées sur d'autres. Si les étendues sont nouvelles pour votre équipe, l'explication des étendues OAuth 2.0 couvre comment les découper.
Client invalide : attendez une erreur propre du point de terminaison de jeton
Dirigez une requête directement vers https://auth.example.com/oauth/token avec un client_secret bidon. Conformément à la section 5.2 de la RFC 6749, le serveur doit renvoyer un 400 (ou 401 pour une authentification client échouée) avec un corps JSON contenant "error": "invalid_client". Affirmez les deux. Les serveurs d'autorisation sont aussi des API, et leur contrat d'erreur fait partie de votre surface.
Affirmer sur les réponses de jetons dans les scénarios de test
Le point de terminaison de jeton mérite sa propre couverture au-delà du cas du client invalide. Ajoutez une étape dans votre scénario de test appelant directement le point de terminaison de jeton, puis attachez des assertions à la réponse :
access_tokenexiste et n'est pas videtoken_typeest égal àbearer(insensible à la casse selon la spécification)expires_inest supérieur à 0 et conforme à votre politique, par exemple pas plus de 3600scopecorrespond à ce qui a été demandé, détectant les serveurs qui réduisent silencieusement les octrois
Les scénarios de test d'Apidog vous permettent d'ajouter ces assertions visuelles sur le JSON de la réponse, sans nécessiter de script, et vous pouvez extraire access_token dans une variable pour une étape de suivi lorsque vous souhaitez tester la négociation brute au lieu d'utiliser l'authentification gérée. Intégrez le scénario à votre exécution CI et un serveur d'autorisation défaillant fera échouer la construction au lieu d'apparaître comme un mystérieux 401 en production.
La boucle complète ressemble à ceci : configuration OAuth 2.0 au niveau du dossier pour le chemin heureux, surcharges par requête pour les cas 401 et 403, et un scénario martelant le contrat du point de terminaison de jeton. Cela couvre les API de contexte utilisateur via le code d'autorisation avec PKCE et les API de service à service via les informations d'identification du client, avec un rafraîchissement de jeton géré pour vous. Téléchargez Apidog et essayez-le gratuitement ; le type d'authentification OAuth 2.0 fonctionne sur le plan gratuit, vous pouvez donc le pointer vers votre propre point de terminaison de jeton en quelques minutes.
FAQ
Quel flux OAuth dois-je utiliser pour les tests d'API ?
Utilisez les informations d'identification du client pour tout ce qui concerne la machine à machine et pour la plupart des suites automatisées, car cela ne nécessite aucune interaction avec le navigateur. Utilisez le flux de code d'autorisation avec PKCE lorsque le test dépend de l'identité de l'utilisateur : isolation des données par utilisateur, vérifications de rôles ou comportement de consentement. Évitez les octrois implicites et de mot de passe dans les nouveaux plans de test ; les deux sont déconseillés dans les directives OAuth actuelles.
Comment rafraîchir automatiquement un jeton expiré dans Apidog ?
Configurez OAuth 2.0 dans l'onglet "Auth" et récupérez un jeton avec "Obtenir le jeton". Lorsque le serveur d'autorisation renvoie un jeton de rafraîchissement, Apidog rafraîchit le jeton d'accès à l'expiration sans que vous ayez à vous réauthentifier, et vous pouvez définir une URL de jeton de rafraîchissement distincte dans les paramètres avancés si votre fournisseur en utilise une. Pour les configurations d'informations d'identification client sans jetons de rafraîchissement, réexécuter "Obtenir le jeton" en émet un nouveau.
Chaque requête dans un scénario peut-elle partager un seul jeton OAuth ?
Oui. Définissez la configuration OAuth 2.0 sur le dossier parent et les requêtes à l'intérieur l'hériteront, de sorte qu'un scénario en plusieurs étapes s'exécute sous un seul jeton géré. Les requêtes individuelles peuvent toujours remplacer la configuration du dossier, ce qui est la manière d'insérer des tests négatifs (jeton expiré, étendue incorrecte) dans le même scénario.
Que devraient signifier un 401 versus un 403 dans les API protégées par OAuth ?
Renvoie 401 lorsque l'authentification a échoué : le jeton est manquant, expiré ou mal formé. Renvoie 403 lorsque le jeton est valide mais ne dispose pas des autorisations nécessaires, comme une étendue manquante. Les mélanger perturbe la logique de nouvelle tentative du client, car un 401 indique au client de se réauthentifier tandis qu'un 403 lui dit d'arrêter. Notre guide sur le test de l'authentification JWT approfondit la validation du jeton lui-même.