Pourquoi les fichiers de jetons de rafraîchissement OAuth sont-ils des identifiants de production ?

Un fichier auth.json copié n'est pas un simple résidu de configuration. S'il contient un jeton de rafraîchissement, c'est un identifiant de production qui peut continuer à créer des jetons d'accès après le départ de la personne qui l'a copié. Le fait que la machine fonctionne sans interface ne change rien. Cela supprime seulement la demande du navigateur qui aurait rappelé à quelqu'un de réfléchir à la responsabilité du jeton.

J'ai vu des équipes protéger soigneusement une clé d'API, puis envoyer un fichier de jeton de rafraîchissement à un hôte de build en pièce jointe dans une conversation, parce que le jeton d'accès qu'il contenait expirait rapidement. C'est l'inverse qu'il faut faire. Le jeton d'accès à courte durée de vie est généralement la partie la moins intéressante du fichier. Le chemin de renouvellement est la partie qu'un attaquant, un agent doté de permissions excessives ou une tâche nocturne sans responsable peut continuer à utiliser.

Un fichier de jeton de rafraîchissement est un paquet d'identifiants

Un fichier de jeton de rafraîchissement OAuth est un paquet d'identifiants, car il contient souvent suffisamment d'informations pour obtenir un nouveau jeton bearer sans intervention humaine. Les champs précis varient selon la bibliothèque cliente, mais la combinaison dangereuse est connue : un jeton de rafraîchissement, un identifiant client, un point de terminaison de jeton, des périmètres accordés et parfois un secret client ou une assertion propre à l'appareil.

Ne laissez pas l'extension du fichier minimiser le risque. JSON n'est qu'une enveloppe. Un fichier nommé .cache/session.json, token-store.json ou auth.json mérite la même protection qu'une clé SSH privée lorsqu'il peut renouveler l'accès à un service de production.

L'OAuth 2.0 Authorization Framework, RFC 6749, décrit les jetons de rafraîchissement comme des identifiants utilisés pour obtenir des jetons d'accès. Il précise aussi que le serveur d'autorisation peut émettre un nouveau jeton de rafraîchissement et que le client doit supprimer l'ancien. Cette dernière phrase est facile à écarter comme un simple détail de protocole. Dans un système sans surveillance, c'est une exigence opérationnelle : deux workers qui pensent détenir le fichier actuel peuvent désormais se disputer l'identité d'un identifiant.

Séparez ces trois éléments dans votre inventaire :

• Un jeton d'accès autorise une requête pendant une durée limitée.
• Un jeton de rafraîchissement autorise le renouvellement, souvent pendant plusieurs durées de vie de jetons d'accès.
• Un client OAuth identifie le logiciel qui demande le renouvellement.

Les équipes confondent souvent les deux premiers éléments, puis avancent un mauvais argument sur l'expiration. Un jeton d'accès valable cinq minutes ne rend pas un jeton de rafraîchissement copié sûr. Cela peut seulement signifier que le fichier copié fournit à un intrus de nouveaux jetons par tranches de cinq minutes.

Une entrée d'inventaire de production doit répondre à plus que « quel service utilise ceci ? ». Notez le serveur d'autorisation, l'identifiant du client OAuth, le serveur de ressources, le sujet ou le compte de service, les périmètres accordés précisément, l'environnement, la date d'émission si elle est disponible, le responsable du renouvellement, le chemin d'exécution approuvé et la méthode de révocation. Si vous ne pouvez pas renseigner ces champs, vous ne disposez pas d'un identifiant prêt pour une utilisation autonome. Vous avez un fichier qui a fonctionné par hasard pendant les tests.

Le travail sans interface fait facilement perdre la responsabilité

Un agent sans interface a besoin d'un dispositif de renouvellement qui désigne un responsable clairement identifiable. L'échec commence souvent ainsi : un développeur autorise un outil local avec son propre compte, puis copie son cache sur un serveur parce que celui-ci ne peut pas effectuer le parcours dans le navigateur. La tâche fonctionne, et la copie devient permanente.

Posez ensuite les questions que l'on évite parce qu'elles sont gênantes. Le jeton représente-t-il le développeur, l'équipe ou la tâche ? Qui peut le révoquer sans interrompre le travail de quelqu'un d'autre ? Quel dépôt ou quelle instruction de l'agent indique à la tâche où le trouver ? Un salarié qui quitte l'entreprise peut-il invalider l'identité qui se trouve derrière ? La page de consentement du fournisseur affiche-t-elle un compte personnel alors que la tâche se comporte comme un service ?

« Le compte de la plateforme en est responsable » n'est pas une réponse, sauf si ce compte possède un administrateur documenté, une procédure de récupération et des privilèges limités. Un jeton copié depuis une connexion personnelle est pire qu'une clé d'API visible sur un point : il arrive souvent sous la forme d'un fichier de cache opaque. Les réviseurs ne peuvent donc pas voir quelles permissions ont été emportées.

Utilisez une identité de service dédiée lorsque le fournisseur le permet. Donnez-lui le plus petit ensemble de permissions sur les ressources permettant à la tâche d'aller au bout. Enregistrez un client OAuth distinct pour chaque frontière de confiance importante, par exemple le développement, la préproduction et la production. N'utilisez pas un client étendu et une autorisation étendue simplement parce que cela facilite le renouvellement.

Une distinction mérite d'être bien maintenue : l'identité du client OAuth et l'identité de la ressource sont deux contrôles différents. L'identifiant du client indique quel logiciel a demandé un jeton. Le sujet et les périmètres indiquent à quelles ressources le jeton peut accéder et ce qu'il peut y faire. Une équipe qui crée un client dédié, mais continue à l'autoriser comme administrateur humain améliore un peu l'attribution, tout en laissant le problème des privilèges intact.

Pour un agent, rédigez une fiche de responsabilité simple à côté de la documentation du déploiement, pas dans le fichier de jeton :

Credential name: billing-export-prod
OAuth client: agent-billing-prod
Resource identity: svc-billing-export
Scopes: reports.read, exports.write
Renewal owner: platform-oncall
Execution path: production job runner through credential broker
Revocation: authorization server admin console and RFC 7009 endpoint

Cette fiche est volontairement banale. C'est ce qui la rend utile à 2 heures du matin. Elle permet à un opérateur de révoquer la bonne autorisation sans avoir à deviner si le fichier appartenait à l'ancien ordinateur portable d'un développeur, à un test de préproduction ou à la tâche qui vient de le réveiller.

Conservez le chemin de renouvellement hors de l'espace de travail de l'agent

Le processus de l'agent ne devrait jamais lire un fichier de jeton de rafraîchissement. Si un agent peut lire la chaîne, il peut l'afficher, l'écrire dans un journal, l'intégrer à un correctif, l'envoyer à un outil distant ou la laisser dans un rapport d'incident. Des instructions demandant de ne pas divulguer le secret ne changent rien à la capacité du processus à exfiltrer les données auxquelles il peut accéder.

Les permissions du système de fichiers restent importantes, mais elles servent de couche de confinement après le choix architectural. Un mode tel que 0600 empêche les autres comptes locaux d'accéder au fichier sur un hôte Unix classique. Il n'empêche pas le processus d'agent autorisé, ses extensions, ses processus enfants, son débogueur ou une tâche de sauvegarde de lire le fichier. Il n'explique pas non plus pourquoi cet hôte possède un identifiant de renouvellement de production.

Placez le jeton de rafraîchissement dans un gestionnaire de secrets, un coffre d'identifiants du système d'exploitation ou un courtier local que l'agent ne peut pas interroger pour obtenir la valeur brute. Le courtier doit accepter une demande d'action limitée, récupérer ou actualiser l'identifiant en interne, appeler le point de terminaison de ressource approuvé et renvoyer le résultat dont l'agent a besoin. Une requête peut ressembler à ceci :

{
  "action": "create_export",
  "target": "billing-api",
  "parameters": {
    "report_date": "2026-07-23"
  }
}

L'agent reçoit une réponse comme celle-ci, et non un jeton :

{
  "status": "accepted",
  "export_id": "exp_4821",
  "report_date": "2026-07-23"
}

Cette frontière évite une erreur fréquente : monter un répertoire de secrets dans chaque conteneur de tâche, puis parler d'accès contrôlé. Le montage rend le secret accessible à chaque bibliothèque, commande shell, extension et vidage de diagnostic accidentel dans ce conteneur. Un courtier peut rejeter les cibles inconnues, associer lui-même le bon identifiant et garder l'état du renouvellement hors de la mémoire de l'agent.

Sur macOS, Sallyport applique ce modèle à ses actions HTTP et SSH prises en charge : les identifiants restent dans son coffre chiffré et l'agent reçoit les résultats des actions plutôt que des secrets en clair. Cette conception est utile, car elle traite la requête comme l'élément à autoriser, et non le fichier de jeton comme une commodité à transmettre.

Ne placez pas les fichiers de jetons de rafraîchissement dans des répertoires de dépôts, des espaces de travail CI, des dossiers réseau partagés, des fichiers cachés du répertoire personnel, des images de conteneurs ou des chemins de sauvegarde génériques. Chaque emplacement crée un mécanisme de copie différent, et chaque copie ajoute un futur problème de révocation. Si un outil ancien exige un chemin, donnez-lui un répertoire d'exécution isolé et à courte durée de vie, appartenant à un assistant d'identifiants. L'assistant doit alors créer et supprimer le fichier. Traitez cela comme une exception de compatibilité avec une date d'expiration, pas comme votre modèle standard.

Les périmètres doivent décrire une tâche, pas un service entier

Un agent sans interface doit disposer de périmètres qui décrivent sa tâche unique. Un jeton autorisé à lire tous les projets parce que l'agent pourrait en avoir besoin un jour finira par être utilisé dans un contexte que personne n'avait prévu. Les périmètres larges sont populaires parce que les écrans d'autorisation et la documentation des fournisseurs peuvent être frustrants. Le coût apparaît plus tard, lors d'un incident, quand la révocation d'un jeton d'automatisation interrompt aussi des activités sans rapport.

Commencez par les appels API finaux, pas par la liste des périmètres disponibles chez le fournisseur. Notez les verbes et les ressources dont la tâche a besoin. Une tâche qui récupère des factures et téléverse un export terminé peut avoir besoin d'un accès en lecture aux factures et d'un accès en écriture à un emplacement d'export. Elle n'a pas besoin de gérer les utilisateurs, de supprimer des dépôts, de modifier la facturation ou de gérer les permissions parce qu'une personne a utilisé ces droits lors de la configuration initiale.

Les périmètres OAuth ne suffisent pas. Les permissions appliquées au niveau des ressources peuvent élargir l'effet d'un périmètre qui semble modeste. Un jeton doté de files.write peut tout de même endommager un vaste ensemble de données si son sujet a accès à tous les dossiers d'équipe. Limitez l'identité de service à un projet, un dossier, une unité organisationnelle ou un dépôt lorsque le fournisseur le permet. Testez ensuite les cas négatifs : une action contre une ressource de production voisine doit échouer pour une raison de permission, pas simplement parce que l'agent n'a pas encore essayé.

Créez des autorisations distinctes pour des responsabilités distinctes, même lorsque le fournisseur accepte une liste combinée. Par exemple, séparez une tâche de collecte de données en lecture seule d'une tâche qui publie les résultats. Un identifiant de publication divulgué n'a pas le même impact, le même rythme de rotation ni le même responsable d'approbation qu'un identifiant de lecture. Les combiner économise un parcours de renouvellement, mais rend chaque enquête plus difficile.

Évitez les périmètres fondés sur la session d'un administrateur humain. Les administrateurs acceptent souvent des permissions étendues parce qu'ils en ont besoin pour la configuration. L'agent en fonctionnement n'hérite pas de leur jugement. Il hérite de leur autorisation.

Un test utile consiste à lire la fiche de consentement et à essayer de décrire la tâche en une phrase. Si la description devient « il peut gérer plusieurs choses dont nous pourrions avoir besoin », l'autorisation n'est pas prête. Réduisez le périmètre de la tâche ou séparez-la. Le travail supplémentaire nécessaire pour gérer deux identifiants coûte moins cher que la découverte d'un agent d'export capable de modifier les paramètres d'identité.

Les jetons qui se renouvellent seuls ont besoin d'un responsable unique

La rotation des jetons de rafraîchissement crée un problème de gestion d'état que les workers sans surveillance doivent résoudre volontairement. De nombreux serveurs d'autorisation effectuent une rotation : après un rafraîchissement réussi, le serveur renvoie un remplacement et peut invalider le jeton précédent. La RFC 9700, OAuth 2.0 Security Best Current Practice, recommande la rotation des jetons de rafraîchissement ou des jetons liés à l'émetteur pour les clients publics afin de détecter les rejeux. C'est une recommandation de sécurité solide, mais elle ne rend pas un fichier partagé sûr.

Prenons un échec courant. Le worker A et le worker B démarrent avec le même auth.json monté. Le worker A effectue le rafraîchissement en premier et reçoit R2 ; le fournisseur invalide R1. Avant que A n'écrive R2, le processus s'arrête ou l'écriture du système de fichiers atterrit sur une couche locale que B ne peut pas voir. Le worker B envoie R1, reçoit invalid_grant et réessaie. Un opérateur constate l'échec de la tâche, copie un cache plus ancien depuis une sauvegarde et la réponse à l'incident crée alors encore davantage de copies de l'identifiant.

Utilisez l'un des dispositifs suivants :

1. Un courtier d'identifiants unique gère les renouvellements et enregistre le remplacement de manière transactionnelle.
2. Un worker planifié gère une autorisation donnée, avec un verrou explicite et sans répliques parallèles partageant l'état du jeton.
3. Des autorisations distinctes existent pour les workers distincts, afin que chaque jeton de rafraîchissement n'ait qu'un seul écrivain.

Le premier dispositif est généralement le plus propre. Le deuxième peut convenir à une petite tâche contrôlée, mais l'expiration du verrou et la récupération après incident doivent être conçues sérieusement. Le troisième demande davantage de travail de consentement et de gestion du cycle de vie, mais il contient bien les défaillances.

Ne résolvez pas le problème de concurrence en désactivant la rotation si le fournisseur le permet. Cette recommandation est séduisante parce qu'elle dissimule le bug de concurrence. Elle donne aussi à un jeton de rafraîchissement volé davantage de temps pour agir sans être détecté. Corrigez plutôt le modèle de responsabilité.

Votre mécanisme de persistance doit mettre à jour le nouveau jeton de manière atomique et conserver suffisamment de métadonnées pour détecter un écrivain obsolète. Au minimum, stockez une version, l'heure du dernier rafraîchissement réussi et un identifiant stable du jeton qui peut être enregistré sans danger. Le coffre de secrets doit refuser une mise à jour qui tente de remplacer la version 14 alors que la version 15 existe déjà. Un simple écrasement permet à un worker lent de ressusciter un état obsolète.

Lorsque le serveur d'autorisation propose des jetons liés à l'émetteur, comprenez ce qui est lié. Un mécanisme de preuve peut rendre un jeton copié moins utile sans la clé détenue par le client correspondant. Il ne remplace pas le contrôle d'accès autour de cette clé et ne transforme pas une autorisation humaine en véritable identité de service. Considérez-le comme une barrière supplémentaire, pas comme une raison de distribuer des fichiers de cache.

La rotation est une procédure, pas un rappel de calendrier

Une politique de rotation n'est crédible que si quelqu'un peut l'appliquer sans improviser. La rotation fondée sur le calendrier a son utilité, mais un changement de responsable, une activité suspecte, la compromission d'un hôte, l'exposition d'un dépôt et des erreurs invalid_grant inattendues doivent déclencher la même séquence préparée. N'attendez pas la date prévue si vous soupçonnez qu'un jeton copié s'est échappé.

Une procédure opérationnelle efficace comporte cinq actions :

1. Geler l'agent ou le chemin du courtier concerné afin qu'il ne puisse plus continuer à effectuer des renouvellements pendant la modification.
2. Identifier le client OAuth, l'identité de ressource, les périmètres et la version de l'identifiant à partir de la fiche de responsabilité et des journaux.
3. Révoquer le jeton de rafraîchissement ou l'autorisation auprès du serveur d'autorisation, en utilisant la console du fournisseur ou son point de terminaison de révocation compatible avec la RFC 7009 lorsque celui-ci est disponible.
4. Supprimer toutes les copies d'exécution connues et invalider tout processus de sauvegarde ou de cache capable de les restaurer.
5. Réinscrire l'identité dédiée, tester l'action minimale autorisée et consigner la version de remplacement.

La RFC 7009 définit la révocation des jetons et permet délibérément aux serveurs de révoquer des jetons et des autorisations associés lors du traitement d'une demande. L'opérateur doit donc connaître le périmètre de l'impact avant d'appuyer sur le bouton de révocation. Un fournisseur peut invalider le jeton d'accès actuel, la famille de jetons de rafraîchissement ou l'autorisation entière. La bonne réponse n'est pas d'éviter la révocation. Il faut documenter les tâches qui partagent une autorisation afin qu'elles ne partagent pas la même par accident.

Testez la rotation avec une identité de préproduction jetable. Vérifiez qu'un nouveau remplacement fonctionne, que l'ancien jeton échoue et qu'un worker obsolète ne peut pas écraser le nouvel état. Exercez-vous ensuite à gérer une réponse à un jeton révoqué. La tâche doit échouer de manière sécurisée, avec une erreur reconnaissable et une identité pouvant faire l'objet d'un ticket, sans revenir discrètement à la connexion mise en cache d'un développeur.

Les sauvegardes demandent une attention particulière. Même chiffrées, elles conservent un jeton de rafraîchissement jusqu'à la fin de leur période de rétention. Vous ne pourrez peut-être pas supprimer immédiatement les blocs historiques, mais vous pouvez révoquer immédiatement l'autorisation exposée. Documentez l'emplacement de rétention afin qu'un enquêteur sache que les supports de récupération contiennent un secret obsolète, même si celui-ci ne fonctionne plus.

Auditez séparément les actions et les renouvellements

Les journaux d'audit doivent montrer les événements de renouvellement ainsi que les actions effectuées avec les jetons d'accès qui en résultent. Un événement de rafraîchissement indique qu'un identifiant est resté actif. Il ne dit pas si l'agent a lu un rapport ou modifié mille enregistrements. À l'inverse, un journal d'actions API sans version de l'identifiant ne permet pas de savoir quel chemin de renouvellement l'a autorisée.

Pour chaque rafraîchissement, enregistrez des métadonnées sans danger : l'horodatage, l'identifiant du jeton, la version du jeton avant et après, l'identifiant du client OAuth, l'identifiant du sujet, le périmètre demandé ou renvoyé si le fournisseur l'expose, l'hôte d'exécution ou l'identité du courtier et le résultat. Pour chaque action protégée, enregistrez les métadonnées sûres suivantes : l'identifiant de session de l'agent ou de la tâche, la cible demandée, l'opération, l'identifiant de la ressource, la décision d'autorisation, le code de résultat et l'identifiant de corrélation.

N'enregistrez jamais le jeton de rafraîchissement, le jeton d'accès, le code d'autorisation, le secret client, l'URL complète de rappel ou l'en-tête Authorization brut. Une fois la journalisation effectuée, la rédaction arrive trop tard si un collecteur, un enregistreur de terminal ou un outil de surveillance des erreurs a déjà reçu l'événement. Concevez des appels de journalisation qui n'acceptent jamais ces champs, au lieu de compter sur chaque appelant pour se souvenir d'utiliser un filtre.

Une requête d'incident utile part d'une action sur une ressource et remonte le chemin. Supposons qu'un export soit apparu au mauvais endroit. Vous devez pouvoir répondre aux questions suivantes : quelle tâche l'a demandé, quel processus a exécuté la tâche, quel client OAuth a été utilisé, quelle version de l'identifiant a fourni l'accès, quand cette version a été émise et si un autre hôte a utilisé la même version. Si un lien dépend de la lecture de la valeur du jeton, la conception de l'audit est défaillante.

La résistance à la falsification compte lorsque les agents agissent sans supervision constante. Un journal en ajout uniquement sur le même hôte vaut mieux que le silence, mais un attaquant qui contrôle l'hôte peut modifier le cache et l'enregistrement. Conservez les données d'audit dans un système protégé et vérifiez leur intégrité indépendamment. Pour les systèmes capables de conserver un enregistrement chiffré et chaîné par hachage, une vérification hors ligne permet à l'enquêteur de vérifier si des entrées ont changé sans exposer d'abord les secrets sous-jacents.

Placez l'approbation sur les actions, pas sur l'exposition du jeton

L'approbation humaine est la plus utile à la frontière où un agent tente d'agir sur un système extérieur. Demander à quelqu'un d'approuver une fois un fichier de jeton de rafraîchissement, puis laisser n'importe quel processus l'utiliser pendant des semaines donne une apparence de contrôle tout en mettant la chaîne sensible en circulation.

Choisissez les approbations selon les conséquences. Une récupération en lecture seule peut s'exécuter dans une session préapprouvée et strictement limitée. L'envoi de données vers une nouvelle destination, la modification de permissions, la suppression d'une ressource ou l'utilisation d'un identifiant en dehors de sa tâche habituelle doivent attendre une décision humaine. La personne qui approuve doit voir le processus demandeur, la cible, l'opération et suffisamment de paramètres pour comprendre l'effet. Une demande générique du type « autoriser OAuth » est presque inutile.

Ne confondez pas fréquence des demandes et sécurité. Si chaque appel inoffensif demande un consentement, les utilisateurs approuvent par automatisme. Définissez une limite de session raisonnable pour le travail courant, puis exigez une approbation distincte pour les opérations aux conséquences importantes. La décision doit rester visible lorsque l'agent fonctionne sur une table de cuisine, via une connexion de voyage ou dans une tâche nocturne.

Le test est simple : si une instruction de l'agent devient hostile ou si une extension se comporte mal, peut-elle transformer l'accès en action sur le monde extérieur sans franchir un contrôle qui montre à un humain ce qui va se passer ? Si la réponse est oui parce qu'elle détient déjà auth.json, placez l'identifiant derrière un courtier et repensez l'interface de demande.

Traitez les anciens fichiers auth.json comme un projet de migration

Les caches de jetons existants disparaissent rarement en un après-midi, mais les laisser sans documentation parce que la migration est contraignante garantit leur maintien. Commencez par trouver chaque consommateur, puis classez le fichier selon le service, le sujet, les périmètres, l'environnement, le nombre d'écrivains et le chemin de stockage. Révoquez les copies que vous ne pouvez pas attribuer. Un jeton dont personne n'est responsable n'a aucune raison de continuer à se renouveler.

Déplacez un workflow à la fois. Créez d'abord une identité de ressource et un client dédiés. Placez ensuite son jeton de rafraîchissement derrière le coffre de secrets ou le courtier choisi. Modifiez ensuite la tâche afin qu'elle soumette une demande d'action autorisée et comparez le nouvel enregistrement d'audit avec le résultat de l'ancienne tâche. Ce n'est qu'une fois le remplacement fonctionnel que vous devez révoquer l'ancienne autorisation personnelle.

Attendez-vous à quelques résistances de la part des outils. Certains SDK partent du principe qu'ils gèrent un cache JSON local et effectuent discrètement un renouvellement dès qu'ils le voient. Gardez ces outils dans un wrapper de compatibilité limité, avec un seul processus autorisé à lire le fichier et aucun accès général pour l'agent. Ajoutez la suppression de ce wrapper à la liste de tâches du responsable du service. « La bibliothèque l'exige » explique une exception temporaire, mais ne justifie pas une voie permanente de fuite de secrets.

Votre première cible de migration doit être le fichier dont le périmètre est le plus large ou dont le responsable est le moins clairement désigné, pas le fichier le plus facile à déplacer. Ce sont ces identifiants qui transforment une erreur d'agent par ailleurs contenue en incident de production. Une fois un workflow déplacé proprement, rendez l'ancien modèle difficile à reproduire grâce à la revue des déploiements, aux modifications des modèles et au refus de monter des caches d'identifiants bruts dans les environnements d'exécution des agents.

Un jeton de rafraîchissement doit avoir un responsable clairement désigné, un seul chemin de renouvellement contrôlé et une piste d'audit qui nomme chaque action extérieure qu'il a autorisée. Si votre auth.json actuel ne respecte pas ces conditions, révoquez-le une fois que le nouveau chemin a prouvé son fonctionnement.