Comment tester les APIs OAuth 2.0 dans Apidog (Code d'autorisation, Identifiants client, Actualisation de jeton)

Tester OAuth 2.0 dans vos API avec Apidog : PKCE, client credentials et cas d’échec

Chaque équipe API finit par rencontrer le même problème : les endpoints fonctionnent séparément, puis OAuth 2.0 est activé et la moitié de la suite de tests renvoie soudain des 401. Entre les serveurs d’autorisation, les jetons à courte durée de vie et les scopes, copier manuellement un jeton depuis une réponse curl vers un en-tête devient vite pénible.

Essayez Apidog dès aujourd’hui

La solution n’est pas de contourner l’authentification, mais d’intégrer la gestion des jetons à la configuration des tests. Ce guide couvre les deux flux les plus utiles :

• le flux de code d’autorisation avec PKCE, pour les API qui agissent au nom d’un utilisateur ;
• le flux client_credentials, pour les appels de machine à machine.

Pour une vue d’ensemble, consultez l’aperçu des flux OAuth 2.0.

Nous verrons ensuite comment configurer OAuth 2.0 dans Apidog, réutiliser un jeton sur plusieurs requêtes, gérer son expiration, hériter de l’authentification au niveau d’un dossier et tester les cas d’échec.

Les deux flux OAuth utiles pour les tests d’API

OAuth 2.0 définit plusieurs types d’octroi. Pour les tests quotidiens, le choix dépend surtout d’une question :

L’API agit-elle au nom d’un utilisateur ou au nom d’un service ?

Code d’autorisation avec PKCE

Le flux de code d’autorisation permet d’obtenir un jeton associé à un utilisateur :

1. le client redirige l’utilisateur vers le serveur d’autorisation ;
2. l’utilisateur se connecte et donne son consentement ;
3. le serveur redirige le navigateur avec un code à usage unique ;
4. le client échange ce code contre un jeton d’accès.

La RFC 6749 décrit ce processus dans la section 4.1.

PKCE (Proof Key for Code Exchange) sécurise davantage l’échange. Le client génère un vérificateur aléatoire, envoie une empreinte lors de la demande d’autorisation, puis prouve qu’il possède le vérificateur original lors de l’échange du code. Un attaquant qui intercepte le code ne peut donc pas l’utiliser.

Initialement conçu pour les applications mobiles, PKCE est désormais recommandé pour les échanges de code d’autorisation, y compris avec les clients confidentiels, conformément aux directives actuelles d’OAuth.

Utilisez ce flux lorsque le comportement de l’endpoint dépend de l’identité de l’utilisateur :

• GET /orders ne renvoie que les commandes de l’utilisateur connecté ;
• un endpoint d’administration dépend du rôle ;
• les limites de débit sont appliquées par utilisateur ;
• le consentement utilisateur fait partie du scénario testé.

Informations d’identification du client

Le flux client_credentials ne représente aucun utilisateur. Le client s’authentifie avec son propre identifiant et son secret, puis reçoit un jeton représentant l’application.

L’échange s’effectue directement avec le endpoint de jeton, sans navigateur ni redirection :

curl -X POST https://auth.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=orders_service \
  -d [REDACTED CREDENTIAL]3t_value \
  -d scope="orders:read orders:write"

C’est le flux adapté aux :

• microservices internes ;
• tâches cron ;
• pipelines CI ;
• appels vers une API de déploiement ;
• suites de tests automatisées.

Si votre environnement de test permet de provisionner un client dédié, utilisez ce flux par défaut, sauf lorsque l’identité de l’utilisateur est précisément ce que vous devez tester. Consultez aussi la documentation sur les informations d’identification du client OAuth 2.0.

Configurer OAuth 2.0 dans Apidog

Apidog traite OAuth 2.0 comme un type d’authentification natif. Configurez-le dans l’onglet Auth d’une requête ou, de préférence, d’un dossier. Apidog se charge ensuite de récupérer, d’attacher et de rafraîchir les jetons.

Les types d’octroi disponibles incluent notamment :

• Authorization Code ;
• Authorization Code with PKCE ;
• Client Credentials ;
• Password Credentials ;
• Implicit.

Les exemples suivants utilisent une API fictive de gestion de commandes.

Configurer client_credentials

Ouvrez une requête ou un dossier, sélectionnez OAuth 2.0, puis choisissez Client Credentials. Renseignez les champs suivants :

• URL du jeton d’accès : https://auth.example.com/oauth/token
• ID client : orders_service
• Secret client : le secret provisionné pour les tests
• Scope : orders:read orders:write, dans les options avancées

Apidog permet d’envoyer les identifiants :

• dans un en-tête Basic Auth ;
• dans le corps de la requête.

Choisissez le format attendu par votre serveur d’autorisation. Auth0 et Okta acceptent généralement les deux, mais certains serveurs internes ne lisent que les identifiants présents dans le corps.

Cliquez sur Obtenir le jeton. Apidog appelle le endpoint, stocke la réponse et affiche le jeton ainsi que sa durée de validité. Les requêtes suivantes ajoutent automatiquement :

[REDACTED CREDENTIAL] <access_token>

Vous n’avez donc plus besoin de copier-coller un jeton ni de maintenir une variable {{token}} manuellement.

Configurer le code d’autorisation avec PKCE

Pour les tests liés au contexte utilisateur, sélectionnez Authorization Code (With PKCE). Dans Apidog, PKCE est un type d’octroi distinct, et non une simple case à cocher.

Renseignez :

• 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 du fournisseur
• ID client et Secret client : ceux de l’application OAuth

Cliquez sur Obtenir le jeton. Apidog ouvre une fenêtre de navigateur vers la page de connexion. Connectez-vous avec un utilisateur de test, approuvez le consentement, puis laissez Apidog récupérer le jeton.

Si le fournisseur renvoie également un jeton d’identité OpenID Connect, l’option Type de jeton utilisé permet de sélectionner le jeton envoyé à l’API. Cette option est utile lorsque l’API valide le jeton d’identité plutôt que le jeton d’accès.

Pour tester les autorisations par rôle, créez un utilisateur dédié pour chaque profil nécessaire :

• acheteur ;
• administrateur ;
• auditeur en lecture seule.

Récupérez un jeton pour chaque utilisateur, puis exécutez le même scénario. Vous vérifierez rapidement les règles d’accès sans modifier les requêtes.

Réutiliser et rafraîchir automatiquement les jetons

Les jetons d’accès expirent souvent en moins d’une heure. Sans gestion automatique, leur expiration provoque un échec de test et impose une nouvelle récupération manuelle.

Lorsqu’un serveur d’autorisation fournit un jeton de rafraîchissement, Apidog peut renouveler automatiquement le jeton d’accès. Cette fonctionnalité a été ajoutée dans la mise à jour de juin.

Lorsque le jeton stocké expire, Apidog :

1. utilise le refresh token ;
2. demande un nouveau jeton d’accès ;
3. remplace le jeton stocké ;
4. envoie la requête avec le nouveau jeton.

Si votre fournisseur utilise un endpoint distinct, vous pouvez également définir une URL personnalisée pour le rafraîchissement dans les paramètres avancés.

Avec client_credentials, les serveurs ignorent souvent les refresh tokens. La spécification l’autorise puisque le client peut s’authentifier de nouveau à tout moment. Dans ce cas :

• cliquez sur Obtenir le jeton pour en récupérer un nouveau ;
• dans un scénario CI ou planifié, demandez un nouveau jeton au début de chaque exécution.

Hériter de l’authentification au niveau du dossier

Configurer OAuth 2.0 requête par requête crée rapidement de la duplication. Définissez plutôt l’authentification sur un dossier, par exemple API Commandes. Les requêtes qu’il contient hériteront automatiquement de cette configuration, y compris celles ajoutées ultérieurement.

Cette organisation est particulièrement utile pour les scénarios en plusieurs étapes :

POST /carts
POST /carts/{id}/items
POST /orders

Les trois appels partagent ainsi la même configuration et le même jeton géré. Si le jeton expire au milieu du scénario, le rafraîchissement automatique s’en charge. Si le secret client est renouvelé, une seule modification du dossier suffit au lieu de modifier des dizaines de requêtes.

Chaque requête peut toutefois remplacer la configuration héritée. Cette possibilité est essentielle pour les tests négatifs.

Tester les chemins d’échec OAuth

Les tests du chemin nominal vérifient que l’obtention du jeton fonctionne. Les tests du chemin d’échec vérifient que l’API refuse correctement les requêtes invalides.

Pour les codes d’état, reportez-vous à la comparaison entre clés API et jetons Bearer.

Jeton manquant ou expiré : attendre 401

Dupliquez une requête, puis remplacez son authentification héritée par :

• aucune authentification ;
• ou un jeton Bearer [REDACTED] expiré, par exemple Bearer [REDACTED].

Vérifiez que :

• le code d’état vaut 401 ;
• l’en-tête de réponse WWW-Authenticate est présent, comme le prévoit la RFC 6750 ;
• le corps ne révèle ni trace de pile ni nom d’hôte interne.

Un 200 est une erreur critique. Un 403 indique également une conception problématique : le serveur doit distinguer « je ne sais pas qui vous êtes » de « je vous connais, mais vous n’avez pas accès à cette ressource ».

Scope insuffisant : attendre 403

Provisionnez un second client limité à orders:read, récupérez son jeton, puis appelez un endpoint d’écriture :

POST /orders

Vérifiez que :

• le statut vaut 403 ;
• l’en-tête WWW-Authenticate contient error="insufficient_scope" si votre API suit la RFC 6750.

Ce test détecte une erreur fréquente : les scopes sont contrôlés pour certaines routes à la passerelle, mais oubliés pour d’autres. Pour aller plus loin, consultez l’explication des scopes OAuth 2.0.

Client invalide : vérifier le contrat du endpoint de jeton

Envoyez une requête directement au endpoint de jeton avec un client_secret incorrect :

https://auth.example.com/oauth/token

Conformément à la section 5.2 de la RFC 6749, le serveur doit renvoyer :

• 400, ou 401 si l’authentification du client échoue ;
• un corps JSON contenant "error": "invalid_client".

Les serveurs d’autorisation sont eux-mêmes des API. Leur contrat d’erreur doit donc être testé comme n’importe quel autre endpoint.

Ajouter des assertions sur la réponse de jeton

Le endpoint de jeton mérite une couverture dédiée, au-delà du seul cas invalid_client. Ajoutez une étape qui l’appelle directement, puis vérifiez :

• access_token existe et n’est pas vide ;
• token_type vaut bearer, sans tenir compte de la casse ;
• expires_in est supérieur à 0 et respecte votre politique, par exemple inférieur ou égal à 3600 ;
• scope correspond à la valeur demandée, afin de détecter les serveurs qui réduisent silencieusement les autorisations.

Les scénarios de test Apidog permettent d’ajouter ces assertions visuellement, sans écrire de script. Vous pouvez aussi extraire access_token dans une variable pour tester l’échange manuellement au lieu d’utiliser l’authentification gérée.

Intégrez ensuite le scénario à votre pipeline CI. Un problème du serveur d’autorisation fera ainsi échouer la construction, plutôt que d’apparaître plus tard sous la forme d’un mystérieux 401 en production.

La stratégie complète

Une stratégie OAuth 2.0 de test efficace combine :

1. une configuration OAuth au niveau du dossier pour le chemin nominal ;
2. des remplacements par requête pour les cas 401 et 403 ;
3. un scénario dédié au contrat du endpoint de jeton ;
4. le flux Authorization Code avec PKCE pour les tests dépendant de l’utilisateur ;
5. le flux Client Credentials pour les appels de service à service ;
6. le rafraîchissement automatique lorsque le fournisseur émet des refresh tokens.

Téléchargez Apidog et testez-le gratuitement. L’authentification OAuth 2.0 est disponible dans le plan gratuit : vous pouvez la connecter à votre propre endpoint de jeton en quelques minutes.

FAQ

Quel flux OAuth utiliser pour les tests d’API ?

Utilisez client_credentials pour les appels de machine à machine et la plupart des suites automatisées, car ce flux ne nécessite aucune interaction avec un navigateur.

Utilisez le code d’autorisation avec PKCE lorsque le test dépend de l’identité de l’utilisateur, par exemple pour :

• l’isolation des données ;
• les vérifications de rôles ;
• le consentement ;
• les limites de débit par utilisateur.

Évitez les octrois implicites et password dans les nouveaux plans de test : ils sont déconseillés par les directives OAuth actuelles.

Comment rafraîchir automatiquement un jeton expiré dans Apidog ?

Configurez OAuth 2.0 dans l’onglet Auth, puis cliquez sur Obtenir le jeton. Si le serveur d’autorisation renvoie un refresh token, Apidog renouvelle automatiquement le jeton d’accès à son expiration.

Si votre fournisseur utilise un endpoint de rafraîchissement distinct, indiquez-le dans les paramètres avancés. Pour une configuration client_credentials sans refresh token, cliquez de nouveau sur Obtenir le jeton ou demandez un nouveau jeton au début de chaque exécution CI.

Les requêtes d’un scénario peuvent-elles partager un seul jeton OAuth ?

Oui. Définissez OAuth 2.0 sur le dossier parent : les requêtes qu’il contient hériteront d’un même jeton géré.

Les requêtes individuelles peuvent toujours remplacer la configuration du dossier. Utilisez ce mécanisme pour insérer dans le même scénario des tests avec un jeton expiré ou un scope insuffisant.

Quelle est la différence entre 401 et 403 avec OAuth ?

Renvoyez 401 lorsque l’authentification échoue : jeton absent, expiré ou mal formé.

Renvoyez 403 lorsque le jeton est valide, mais ne possède pas les autorisations requises, par exemple lorsqu’un scope manque.

Cette distinction est importante pour les clients : un 401 indique qu’ils doivent se réauthentifier, tandis qu’un 403 leur indique d’arrêter. Pour approfondir la validation des jetons, consultez le guide Apidog sur le test de l’authentification JWT.