Bien maîtriser l’authentification CLI : le guide complet des 4 méthodes

Chaque CLI pour développeurs propose la commande login comme première instruction. Et chacune résout l’auth différemment.

GitHub affiche un code et ouvre le navigateur pour le vérifier. AWS lance un navigateur pour un SSO basé sur PKCE. Stripe vous fait confirmer un code d’appairage dans le tableau de bord. Les nouveaux outils d’IA (Claude Code, OpenAI Codex CLI, Cursor) ont aussi chacun leur méthode.

Si tu construis une CLI, l’authentification est l’une des toutes premières questions à régler. Te tromper de méthode et tu t’en rendras vite compte : utilisateurs frustrés, audits de sécurité, ou bien les deux. Et avec la vague récente d’agents IA qui appellent les outils CLI de façon programmatique, l’enjeu est monté d’un cran : il ne s’agit plus seulement d’authentifier un humain. Tu pourrais confier des identifiants à un processus autonome.

Voici les quatre méthodes d’auth qui comptent, comment les plus grands outils les mettent en pratique, et les erreurs à éviter à tout prix.

Les quatre méthodes en un coup d’œil#

Avant d’entrer dans les détails, voici une comparaison rapide :

Chaque méthode a ses compromis. Voici ce qu’il faut comprendre pour chacune.

1. OAuth device code flow (RFC 8628)#

C’est celle où la CLI te montre un code comme ABCD-1234 et une URL, et te dit d’ouvrir l’URL sur n’importe quel appareil pour entrer le code.

Utilisée par : GitHub CLI (par défaut), Azure CLI (via --use-device-code), Vercel CLI (a récemment adopté par défaut), OpenAI Codex CLI (en option bêta)

Fonctionnement#

1. Tu exécutes cli login
2. La CLI demande un device code au serveur d’auth, en envoyant son client_id et ses scopes demandés
3. Le serveur renvoie : un device_code (identifiant interne), un user_code (le code court à saisir), et une verification_uri (le lien)
4. La CLI affiche le code et l’URL, puis commence à sonder le serveur d’auth toutes les 5+ secondes
5. Tu ouvres l’URL sur n’importe quel appareil (téléphone, laptop, un autre ordi), entres le code, et t’authentifies (mot de passe, SSO, passkey, MFA…)
6. Une fois approuvé, le prochain sondage renvoie un access token et refresh token
7. La CLI les stocke et c’est bon, tu es connecté

Pourquoi les développeurs aiment cette méthode#

Le gros avantage : ça fonctionne partout. Session SSH sur un serveur distant ? Ok. Dans un conteneur Docker ? Ok. Cloud IDE sans navigateur local ? Ok. Le navigateur n’a pas besoin d’être sur la même machine que la CLI.

Cela supporte toute la gamme des auths d’entreprise (SAML, OIDC, MFA) parce que tout se passe côté navigateur, pas dans le terminal. La CLI ne voit jamais ton mot de passe.

Le piège de sécurité qu’on ne voit pas venir#

Le device code flow a un problème de phishing. Un attaquant peut lancer une demande de device code, obtenir un user code légitime, et te pousser à le saisir, autorisant ainsi sa session. Ce n’est pas théorique : des chercheurs ont documenté l’attaque contre l’auth AWS SSO par device code.

C’est une préoccupation suffisante pour que AWS ait modifié son comportement par défaut. Depuis la version v2.22.0 de l’AWS CLI, le chemin par défaut de aws sso login est passé du device code flow à une autorisation PKCE. Le device code flow est encore accessible via --use-device-code mais ce n’est plus le chemin principal.

De son côté, le tenant Microsoft commence à bloquer la méthode via des politiques d’accès conditionnelles, un signe clair du risque associé.

On observe donc un clivage intéressant : Vercel adopte le device code flow comme défaut en septembre 2025, tandis qu’AWS s’en détourne. En résumé, le device code est top là où on ne peut vraiment pas ouvrir de navigateur, sinon (si c’est possible) il vaut mieux choisir PKCE.

Du côté des fournisseurs d’auth, la demande explose : Logto vient d’ajouter le support OAuth 2.0 Device Authorization Grant pour apps natives en v1.38.0 (open source) et Logto Cloud—tu peux donc désormais activer le device flow pour n’importe quelle appli native. C’est crucial si tu construis ta CLI : bien implémenter la RFC 8628 (expiration code, limitation/rythme, UX de connexion sur la page de vérif) demande plus d’effort que prévu, donc si ton provider le gère, à toi les bons appels HTTP.

Points techniques selon la RFC#

Quelques points clefs de la RFC 8628 :

• La valeur expires_in pour le device code est définie par le serveur d’auth. La RFC propose 1800 s (30 min) mais ce n’est pas figé.
• Si le serveur ne précise pas d’interval de sondage, le client doit par défaut attendre 5 secondes.
• Si tu reçois une erreur slow_down, ajoutes 5 secondes à ton intervalle.
• Les device codes doivent être à usage unique et expirer vite.
• Toute l’échange doit se faire en HTTPS.

2. OAuth par navigateur (redirect sur localhost)#

C’est la méthode la plus courante pour une CLI installée sur la machine d’un développeur. Tu tapes login, ton navigateur s’ouvre, tu t’authentifies, et le navigateur redirige vers un serveur local éphémère démarré par la CLI. Les versions modernes ajoutent PKCE (prononce "pixie") par-dessus, rendant le flux beaucoup plus difficile à détourner.

Utilisée par : Claude Code, gcloud CLI, Terraform CLI, AWS CLI v2.22+ (pour le SSO, avec PKCE par défaut)

Fonctionnement#

1. Tu fais cli login
2. La CLI démarre un serveur HTTP temporaire sur un port local (par exemple http://127.0.0.1:8742)
3. Elle ouvre le navigateur sur l’endpoint d’autorisation OAuth du fournisseur, avec ce port localhost comme URI de redirection
4. Tu t’authentifies dans le navigateur (SSO, passe, passkey…)
5. Le fournisseur redirige vers http://127.0.0.1:8742/callback?code=XXXX&state=YYYY
6. Le serveur local capte le code d’autorisation, l’échange contre des tokens via une requête HTTPS
7. Le navigateur affiche "Succès ! Tu peux fermer cet onglet."
8. La CLI stocke les tokens et arrête le serveur local

L’expérience utilisateur est très fluide. Pas de code à saisir, pas d’URL à recopier. Juste un onglet qui s’ouvre, puis se ferme.

Quand ça ne fonctionne pas#

Ça demande que la CLI puisse ouvrir un navigateur et se binder sur localhost. C’est donc exclu pour :

• Sessions SSH sur serveur distant
• Conteneurs Docker (sauf fausses manipulations de port forwarding)
• Pipelines CI/CD
• Serveurs tête-less
• Certains environnements corporatifs restreints

C’est pourquoi la plupart des outils qui privilégient OAuth navigateur proposent aussi une alternative, typiquement le device code flow ou les clés API.

Trois pièges de sécurité récurrents#

Piège 1 : Ecouter sur 0.0.0.0 au lieu de 127.0.0.1

L’erreur la plus fréquente, et très grave : si ton serveur de callback écoute sur toutes les interfaces, n’importe qui du réseau peut intercepter le code d’autorisation.

Ce bug existe dans des CLI en production. C’est facile à faire à cause des paramètres par défaut des lib HTTP.

Piège 2 : Validation manquante du paramètre state

Le paramètre state protège du CSRF. Sans lui, un attaquant peut forcer la CLI à accepter un code d’une session malveillante.

Piège 3 : PKCE non utilisé

Sans PKCE (Proof Key for Code Exchange), un attaquant peut intercepter et rejouer le code d’autorisation.

En auth code flow standard, si quelqu’un capte ton code OAuth (ou lit l’URL de redirection), il peut échanger contre des tokens. PKCE contourne ça en imposant une preuve générée par le client d’origine.

Voici ce qu’ajoute PKCE :

1. La CLI génère un code_verifier (chaîne très entropique) avant de commencer
2. Elle crée un code_challenge en hashant ce code avec SHA-256
3. Elle envoie le challenge dans la requête d’autorisation initiale
4. Lors de l’échange du code, la CLI fournit le code_verifier
5. Le serveur d’auth vérifie l’association challenge/verifier

Un attaquant interceptant le code n’aura pas le verifier et ne pourra pas finir l’échange.

C’est pour ça que l’AWS CLI v2.22+ force PKCE pour le SSO, laissant de côté le device code flow. Quand la CLI peut ouvrir un navigateur local, OAuth navigateur + PKCE est meilleur que le device code flow : même UX, garanties de sécurité supérieures, et pas de vecteur phishing. Le device code reste pertinent là où le navigateur ne peut pas tourner localement (SSH, containers, dev distant), mais ce n’est plus le cas général sur poste de dev.

3. Clés API et tokens d’accès personnels#

L’approche la plus simple. Tu crées un token sur un dashboard web, tu le colles dans la conf CLI ou une variable d’environnement, et c’est fini.

Utilisé par : Stripe CLI (comme option de connexion), npm, pip, la plupart des outils IA en fallback (Claude Code via ANTHROPIC_API_KEY, OpenAI via OPENAI_API_KEY, Aider)

Fonctionnement#

1. Connecte-toi sur le dashboard web du service
2. Va dans paramètres → API keys (ou personal access tokens)
3. Génère une clé, généralement une longue chaîne aléatoire préfixée (ex : sk_live_, ghp_, npm_)
4. Stocke-la dans un fichier de conf (~/.config/stripe/config.toml, ~/.aws/credentials) ou une variable d’environnement

La CLI la lit au démarrage et l’envoie dans le header Authorization sous forme de token Bearer.

Pourquoi cela reste populaire malgré les risques#

Pour l’automatisation, difficile de faire plus simple que les API keys. Ça marche dans le CI/CD, les containers, en scripts ou cron jobs. Partout où une variable d’environnement est lisible. Zéro navigateur, zéro saisie interactive, zéro refresh token.

Pour les workflows agents IA, c’est la voie royale. Quand Claude Code ou Cursor doit appeler une API, une variable d’environnement API key est le point d’intégration le plus facile.

Les risques sont bien réels#

• Fuites. Les API keys finissent dans des commits git, logs, messages d’erreur, sorties CI. GitHub détecte chaque année plus d’un million de secrets exposés.
• Trop de droits. La plupart accordent des droits larges. En cas de fuite, le rayon d’impact est gros.
• Pas de MFA. Les API keys court-circuitent tous tes MFA soigneusement configurés.
• Rotation difficile. À chaque rotation, il faut tout mettre à jour partout où c’est stocké—un vrai casse-tête en équipe.

Amélioration moderne : échange temporaire de tokens#

La bonne pratique avec des clés API : s’en servir pour obtenir à la volée des tokens temporaires.

AWS a ouvert la voie avec STS (Security Token Service). Tes creds longue durée ne servent qu’à demander des creds temporaires valables 1h. Des outils comme aws-vault automatisent tout ça.

Même si tu pars avec des API keys, pense à intégrer ce pattern : tu limites ainsi la fenêtre de dégâts d’une clé compromise de "jusqu’à ce qu’on s’en rende compte" à "une heure".

4. Client credentials flow#

Ce flux OAuth 2.0 est fait pour l’auth machine à machine : services qui causent entre eux, sans humain.

Utilisé dans : Pipelines CI/CD, services en arrière-plan, outils automatisés

Fonctionnement#

Le service envoie directement ses client_id et client_secret au serveur d’auth, qui renvoie un access token temporaire. Zéro navigateur, aucune interaction humaine, ni redirection.

Quand l’utiliser#

À utiliser si :

• Un service ou bot doit s’authentifier sans humain
• On est dans un pipeline CI/CD
• Accès automatisé et non-interactif requis
• Le "user" est l’application elle-même

À ne pas utiliser pour l’auth humaine : il n’y a ni MFA ni SSO ni vérification interactive.

Ce qu’utilisent réellement les CLI populaires#

Voici un état des lieux corrigé d’après la doc et le code. Beaucoup d’articles font erreur parce que les outils changent vite de défauts.

La tendance : OAuth navigateur en défaut pour le dev local, device code flow en fallback headless, API keys pour l’automatisation. PKCE gagne du terrain côté sécurité dès qu’un browser est là.

Stockage des tokens : que faire, que fuir#

Un bon flow d’auth ne sert à rien si tu stockes mal tes tokens.

La bonne méthode : trousseaux système#

Chaque OS moderne a un coffre fort crypté intégré :

• macOS : Keychain (GitHub CLI, Claude Code, ...)
• Windows : Credential Manager
• Linux : Secret Service API (GNOME Keyring, KDE Wallet)

Cela t’apporte du chiffrement natif, des contrôles d’accès, une intégration du matériel (puce TPM, TouchID…). Inutile de coder ta propre crypto.

Solution de repli : fichiers de config chiffrés#

Quand le trousseau n’est pas dispo (container, Linux minimal), utilise des fichiers conf chiffrés à permissions restreintes :

À éviter absolument#

Fichiers texte en clair. Ça devrait être banni, mais beaucoup d’outils l’utilisent encore. Un token clair est lisible par tout process de l’utilisateur, n’importe quel outil de backup, toute personne ayant accès temporairement à la machine.

Variables d’environnement pour un stockage de long terme. Elles sont visibles dans les process et souvent logguées/inclues par des reporters ou héritées par les enfants. Ok pour CI/CD (quand le runner gère la secret), mais risqué en local.

localStorage navigateur. Si ta CLI a une partie web, n’y stocke jamais de tokens. Une faille XSS les expose tous d’un coup.

Gestion du cycle de vie des tokens#

Access tokens#

Fais-les vivre une heure maxi. Quand le token expire, la CLI doit le rafraîchir discrètement. L’utilisateur ne doit pas devoir se reconnecter sans raison.

Refresh tokens#

Ces tokens longue durée permettent d’obtenir de nouveaux access tokens sans réauth. Cibles précieuses en cas d’attaque puisqu’ils vivent plusieurs jours ou mois.

Rotation automatique des refresh tokens#

Les systèmes modernes renouvellent le refresh token à chaque usage :

1. La CLI utilise le refresh token pour renouveler l’access token
2. Le serveur d’auth renvoie un nouvel access token et un nouveau refresh token
3. L’ancien refresh token est invalidé immédiatement
4. La CLI stocke les deux nouveaux tokens

Ça limite l’impact d’un refresh token volé. Si un attaquant tente d’utiliser un refresh déjà consommé, le serveur détecte la réutilisation et invalide toute la famille de tokens. L’utilisateur et l’attaquant devront alors se réauthentifier, ce qui coupe court à une persistance malicieuse.

Les pièges classiques (exemples de code)#

1. Serveur callback qui écoute sur toutes les interfaces#

Déjà vu plus haut, mais à marteler : toujours binder sur 127.0.0.1, jamais 0.0.0.0.

2. Logguer les tokens#

On le croit rare, mais cette bourde est courante : debug trop bavard, handler dupliquant les headers, etc.

3. Credential inclus dans l’image Docker#

Une image Docker n’est PAS un coffre-fort, chaque layer est extrait facilement.

4. Mal gérer l’expiration des tokens#

Quand un token expire pendant une opération, ne crashe pas avec une erreur 401, tente un refresh et reprompte pour login seulement si le refresh a aussi expiré.

5. Oublier le principe de moindre privilège#

Ne demande pas admin:* si tu as juste besoin de repo:read : c’est valable sur les scopes OAuth ET permissions des API keys.

Avec un agent IA qui utilise ta CLI, c’est crucial. Tu ne veux probablement pas qu’un assistant IA puisse supprimer des repos alors qu’il devrait juste lire du code.

Le cas particulier des agents IA#

C’est ce qui distingue 2026 de 2023 : les CLIs ne sont plus que pour les humains au clavier. Des agents IA (Claude Code, Codex, Cursor agent mode) utilisent les CLI de façon programmatique. Cela pose de nouveaux défis :

Permissions déléguées. Quand Claude Code lance gh pr create pour toi, c’est avec tes identifiants GitHub. Mais l’agent IA devrait-il avoir tes droits complets ? Non selon le principe du moindre privilège, mais la plupart des outils n’ont aucun moyen de réduire le scope agent.

Exposition des credentials. Si ton API key est en variable d’environnement, tout process peut la lire, y compris le sous-processus agent IA. Claude Code a corrigé en utilisant des scripts apiKeyHelper générant des tokens temporaires, mais c’est loin d’être la norme.

Auth headless pour les agents. Un agent IA dans un bac à sable ne peut ouvrir de navigateur. Le device code flow marche (l’humain approuve sur un autre appareil), mais les API keys restent la solution la plus fréquente car sans interaction.

Traces d’audit. Quand l’agent IA utilise tes creds API, les logs d’audit montrent que tu as agi. Il n’existe pas encore de standard pour distinguer "l’humain" de "l’agent agissant pour l’humain".

C’est un secteur en évolution rapide. Les meilleures pratiques actuelles sont :

• Utilise uniquement des tokens de scope minimal pour les workflows agent
• Privilégie les creds courte durée (tokens temporaires, pas d’API keys longue durée)
• Utilise des creds dédiés aux agents distincts de tes creds persos
• Surveille l’usage API pour déceler les comportements inhabituels

Schéma d’aide à la décision#

Besoin de choisir une méthode d’auth ? Résumé rapide :

"Mes users sont développeurs sur leur machine" → OAuth navigateur avec PKCE (UX fluide + sécurité maximale)

"Ma CLI doit marcher en SSH ou en container" → Device code en fallback, OAuth navigateur en primaire

"Ça tourne en CI/CD, sans humain" → Client credentials flow ou API keys restreintes

"Il me faut la solution la plus rapide à implémenter" → API keys (ajoute la rotation plus tard)

"Clients entreprise avec SSO et MFA demandés" → Un flux OAuth quelconque (device code ou navigateur) couvre tout le spectre

"Des agents IA vont utiliser cette CLI" → Supporte clés API (intégration facile agent) + OAuth navigateur (pour les humains), avec scopes restreints et tokens courts

FAQ#

Le device code flow est-il sûr ?#

Il protège contre la plupart des attaques, mais a une faiblesse phishing connue. Un attaquant peut initier un device code et tromper un user pour qu’il l’autorise. Voilà pourquoi AWS a basculé sur PKCE pour le SSO par défaut. Pour les environnements "headless" où PKCE n’est pas faisable, le device code flow reste la meilleure option. Il faut juste connaître le risque.

Faut-il stocker des tokens en variables d’environnement ?#

En CI/CD : oui, le runner chiffre à l’arrêt et injecte à l’exécution. En dev local : non. Préfère ton trousseau OS. Les variables d’environnement sont visibles dans les process et peuvent fuiter ou être logguées par accident.

Différence entre API key et personal access token ?#

Il y en a peu : les deux sont des creds longue durée pour authentifier les appels API. La distinction est surtout organisationnelle : les API keys sont souvent liées à un projet/app, les PAT à un compte utilisateur. Certains services les confondent.

À quelle fréquence dois-je changer mes credentials ?#

Access tokens : chaque heure ou moins (le refresh est automatique). Refresh tokens : à chaque usage (le serveur doit gérer). API keys : tous les 90 jours au moins, ou immédiatement en cas de doute. En pratique, beaucoup d’équipes attendent un incident… C’est trop tard alors.

Auth CLI en container Docker, comment faire ?#

Trois solutions préférentielles :

1. Device code flow pour l’interactif (marche car le browser peut être sur une autre machine)
2. Variables d’environnement passées à l’exécution (docker run -e API_KEY=${API_KEY}) pour CI/CD
3. Volume de credentials monté (docker run -v ~/.config/tool:/root/.config/tool:ro) en dev local

Jamais de creds dans l’image. Jamais.

Et l’auth MCP (Model Context Protocol) ?#

MCP est la nouvelle norme pour connecter des agents IA à des outils externes. Ça ajoute une couche : l’agent a besoin d’un credential pour parler à MCP, qui a besoin de credentials pour les API derrière. C’est encore en standardisation. La plupart des implémentations actuelles utilisent clés API ou tokens OAuth passés dans la conf du MCP. Attends-toi à de rapides évolutions.

L’auth CLI évolue vite. Ce qui était best practice il y a deux ans (device code par défaut, fichiers credentials textes) est déjà dépassé. Si tu ajoutes l’auth à une CLI aujourd’hui, pars sur OAuth navigateur + PKCE pour les humains, clés API pour l’automatisation, et prépare-toi au jour où les agents IA seront tes utilisateurs principaux.