Déboguer un token JWT en décodant son payload Base64
Les problèmes d'authentification avec des tokens JWT sont parmi les bugs les plus fréquents en développement web. Token expiré ? Mauvais claim ? Audience incorrecte ? La première étape du débogage est de décoder le payload du JWT pour voir exactement ce qu'il contient. L'Encodeur Base64 de WikiPlus permet de faire cela en quelques secondes, localement, sans envoyer votre token d'authentification à un service tiers.
Structure d'un JWT et comment décoder chaque partie
Un JWT ressemble à eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c — trois parties séparées par des points. La première partie est le header (type de token et algorithme). La deuxième est le payload (les claims, la partie utile). La troisième est la signature cryptographique (non décodable sans la clé secrète). Pour déboguer, copiez uniquement la deuxième partie (payload). Dans l'Encodeur Base64, sélectionnez le mode Base64url et collez cette valeur. Vous obtenez le JSON des claims : {"sub": "1234567890", "name": "John Doe", "iat": 1516239022}. Passez les timestamps iat et exp dans le Convertisseur de Timestamp pour voir les dates lisibles. C'est la méthode la plus rapide pour diagnostiquer un problème d'expiration ou de claim incorrect.
Claims JWT standard et leur signification
La RFC 7519 définit un ensemble de claims JWT standardisés que les applications d'authentification OAuth 2.0 et OpenID Connect utilisent. Le claim `sub` (subject) identifie l'utilisateur, typiquement son ID en base de données. Le claim `iss` (issuer) identifie le serveur d'autorisation qui a émis le token. Le claim `aud` (audience) identifie le destinataire prévu — votre API doit vérifier que l'audience correspond à son propre identifiant. Le claim `exp` (expiration time) est le timestamp Unix après lequel le token n'est plus valide. Le claim `iat` (issued at) est le timestamp d'émission. Le claim `nbf` (not before) est le timestamp avant lequel le token ne doit pas être accepté. Les claims personnalisés peuvent contenir des rôles, permissions, email, nom d'affichage, ID de tenant et n'importe quelle autre information utile à l'application. Lors du débogage d'une erreur 401, commencez toujours par décoder le payload JWT pour vérifier que tous ces claims ont les valeurs attendues.
Sécurité JWT : ce que Base64 ne protège pas
Une idée reçue critique concernant les JWTs : le payload Base64url peut être lu par n'importe qui en possession du token. Il n'est PAS chiffré. Seule la signature garantit qu'il n'a pas été modifié. Ce principe a plusieurs implications importantes. Ne jamais stocker de mots de passe, de tokens de session, de numéros de carte bancaire ou d'informations médicales dans le payload JWT. Les données dans le JWT voyagent en clair sur le réseau (lisibles dans un proxy, un log, un cache) sauf si HTTPS protège la transmission. Si vous avez besoin de chiffrer le payload, utilisez JWE (JSON Web Encryption) plutôt que JWT simple. Pour les tokens d'accès API, le payload devrait contenir uniquement des identifiants opaques et les permissions nécessaires, jamais des données sensibles brutes. L'Encodeur Base64 de WikiPlus est utile précisément pour cette vérification : décoder votre propre JWT en production vous permet de confirmer qu'il ne contient pas de données qui ne devraient pas y être.
Tokens OAuth 2.0 et OIDC : inspecter les access tokens et ID tokens
OAuth 2.0 et OpenID Connect utilisent des JWTs pour les access tokens et les ID tokens. Un ID token OpenID Connect contient des informations sur l'utilisateur authentifié : sub, email, name, picture, locale et les claims de profil demandés via le scope openid profile email. Un access token peut être opaque (une chaîne aléatoire) ou structuré (JWT), selon l'implémentation du serveur d'autorisation. Google, Microsoft Azure AD, Auth0, Okta et la plupart des fournisseurs d'identité modernes émettent des JWTs pour leurs ID tokens. Pour inspecter ce qu'un fournisseur d'identité inclut dans ses tokens, décodez le payload avec l'Encodeur Base64. C'est essentiel lors du développement d'une intégration SSO pour comprendre quels claims sont disponibles et quelle valeur utiliser comme identifiant utilisateur unique dans votre base de données.
Questions fréquemment posées
- Comment décoder manuellement un token JWT ?
- Séparez le token par les points (.). Prenez la deuxième partie (payload). Remplacez - par + et _ par / (Base64url vers Base64 standard). Ajoutez des = pour atteindre une longueur multiple de 4. Décodez depuis Base64. Le résultat est un objet JSON avec les claims du token.
- Est-ce risqué de décoder un token JWT sur un site tiers ?
- Oui, si le site envoie le token à son serveur. L'Encodeur Base64 de WikiPlus décode entièrement dans votre navigateur — aucun token ne quitte votre appareil. Mais évitez de décoder des tokens d'accès de production valides sur des outils en ligne qui effectuent des requêtes serveur.
- Pourquoi mon token JWT se termine-t-il parfois par un ou deux signes = ?
- Les signes = sont du rembourrage Base64 pour aligner la longueur sur un multiple de 4. JWT utilise la variante Base64url qui omet ce rembourrage. Si vous voyez des = dans un JWT, il a peut-être été encodé par une bibliothèque qui ajoute le rembourrage — certaines vérifications de signature échouent dans ce cas. Les = dans un header HTTP Authorization sont normaux et attendus.