401 Unauthorized : ce que ça signifie et comment le corriger

Ce que signifie 401 Unauthorized

La RFC 9110 définit le 401 comme une requête qui exige une authentification, soit parce qu'aucune n'a été fournie, soit parce que ce qui a été fourni n'a pas été accepté. Une réponse 401 doit inclure un en-tête WWW-Authenticate nommant le schéma que le serveur attend, comme Basic, Bearer, ou Digest. Cet en-tête est l'indice que la plupart des gens sautent : il vous dit exactement quel type d'identifiant le serveur veut, ce qui est généralement plus rapide que de deviner.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

Comment l'erreur apparaît

Dans un navigateur, un 401 protégé par une authentification HTTP Basic déclenche l'invite native de nom d'utilisateur et mot de passe, pas une page affichée par le site. Un 401 venant d'une API JSON, en revanche, n'apparaît généralement que dans un onglet réseau ou une notification d'erreur que l'application a construite pour cela, puisqu'il n'existe pas de chrome de navigateur par défaut pour un échec de jeton Bearer. Depuis la ligne de commande, l'identifiant et l'en-tête sont tous deux visibles en une requête :

curl -i -H "Authorization: Bearer eyJhbGciOi..." https://api.example.com/v1/account
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="token is expired"

Les journaux serveur et applicatifs enregistrent généralement aussi la raison, par exemple « token expired », « signature invalid », ou « no Authorization header », ce qui cerne la cause plus vite que le seul code de statut générique.

Ce qui provoque un 401 Unauthorized

À peu près dans l'ordre où chacune se révèle être la cause :

• Aucun identifiant envoyé du tout. Une session déconnectée, une clé d'API manquante, ou un client qui n'a jamais attaché l'en-tête Authorization au départ.
• Un jeton expiré. Les cookies de session, les jetons d'accès OAuth, et les JWT portent tous une durée de vie, et un client utilisant un jeton périmé obtient 401 même s'il fonctionnait quelques minutes plus tôt.
• Un décalage d'horloge entre le client et le serveur. Les revendications exp et nbf d'un JWT sont évaluées par rapport à l'horloge du serveur. Un serveur ou un client avec la mauvaise heure peut rejeter un jeton qui, selon les propres calculs du jeton, est encore valide, ou accepter un jeton déjà expiré.
• Le mauvais schéma d'authentification. Envoyer Authorization: Basic ... à un point de terminaison qui attend Bearer, ou l'inverse, échoue même si un en-tête est présent.
• Une clé d'API placée au mauvais endroit. Certaines API attendent la clé dans un en-tête personnalisé comme X-API-Key, d'autres dans Authorization, et d'autres encore comme paramètre de requête. Mettre une clé valide au mauvais endroit ressemble en tout point à n'envoyer aucune clé du tout.
• Un reverse proxy ou une passerelle qui retire l'en-tête Authorization. Certaines configurations de proxy et de CDN abandonnent les en-têtes qu'ils ne transmettent pas explicitement, et un identifiant parfaitement valide n'atteint jamais l'origine.
• Des identifiants révoqués. Un utilisateur a changé son mot de passe, un administrateur a fait tourner une clé d'API, ou un jeton a été explicitement invalidé à la déconnexion.

401 face à 403

Les deux sont souvent confondus car les deux refusent la requête, mais la spécification trace une ligne claire. Un 401 signifie que le serveur a besoin que vous vous authentifiiez, et qu'un identifiant valide pourrait changer le résultat ; il doit porter WWW-Authenticate. Un 403 signifie que le serveur a parfaitement compris qui vous êtes et refuse quand même, pour une raison que l'authentification ne peut pas corriger, comme une restriction de rôle ou de forfait. Si se reconnecter aiderait plausiblement, ce devrait être 401. Si l'utilisateur est déjà connecté et n'est simplement pas autorisé, ce devrait être 403, bien qu'en pratique beaucoup d'API utilisent 401 de façon lâche pour les deux cas.

Comment savoir de qui vient la faute

Si c'est vous qui appelez l'API, reproduisez la requête avec un identifiant frais depuis un environnement propre ; si un jeton nouvellement émis réussit, l'ancien avait simplement expiré ou avait été révoqué. Si un jeton tout neuf échoue aussi, vérifiez le schéma et le nom de l'en-tête par rapport à la documentation de l'API avant de supposer que le serveur est cassé. Si vous gérez le service et que des utilisateurs signalent des 401 que vous ne pouvez pas reproduire avec votre propre compte, le moyen le plus rapide de distinguer « le serveur va bien, des jetons individuels sont périmés » de « l'authentification elle-même est cassée pour tout le monde » est de lancer une vérification HTTP avec un identifiant connu pour être valide depuis plusieurs emplacements à la fois et de comparer les résultats.

Comment corriger un 401 Unauthorized

Si vous êtes visiteur

1. Reconnectez-vous. La plupart des 401 venant d'une application web sont simplement une session expirée, et se connecter la rafraîchit.
2. Vérifiez l'horloge système sur votre appareil si la même connexion continue d'échouer immédiatement après vous être authentifié. Une horloge décalée de plusieurs minutes peut invalider des jetons basés sur le temps sur certains clients.
3. Régénérez une clé d'API ou un jeton depuis les réglages du compte si vous soupçonnez qu'il a été renouvelé ou révoqué, plutôt que de supposer que votre code d'intégration a un bug.
4. Confirmez que l'en-tête Authorization est réellement envoyé, en utilisant l'onglet réseau de votre navigateur ou un simple appel curl, puisque certaines bibliothèques clientes HTTP abandonnent silencieusement les en-têtes personnalisés lors d'une redirection.

Si vous gérez le site

1. Lisez l'en-tête WWW-Authenticate et vos propres journaux pour la raison précise du rejet avant de changer quoi que ce soit ; « expired », « invalid signature », et « missing header » pointent chacun vers une correction différente.
2. Vérifiez la synchronisation d'horloge sur les serveurs qui émettent et valident les jetons. Une dérive NTP de part et d'autre est une cause classique et intermittente de rejets de JWT qui paraîtraient sinon aléatoires.
3. Vérifiez que le proxy ou l'équilibreur de charge transmet l'en-tête Authorization. Une règle ajoutée pour une raison sans rapport peut le retirer silencieusement pour chaque requête derrière ce saut.
4. Documentez clairement le schéma et le nom d'en-tête attendus dans votre documentation d'API, et renvoyez une error_description précise dans l'en-tête WWW-Authenticate pour que les intégrateurs n'aient pas à deviner.
5. Distinguez 401 de 403 dans vos propres réponses là où cela compte pour les appelants, afin que le code client puisse distinguer « rafraîchissez votre jeton » de « vous ne serez jamais autorisé à faire cela ».

Comment prévenir une panne 401 silencieuse

Un 401 causé par un certificat de signature expiré, une horloge qui a dérivé hors synchronisation, ou un changement de proxy qui a commencé à retirer l'en-tête Authorization ne ressemblera pas à un plantage. Le service répond instantanément et correctement selon ses propres règles, donc il peut rester cassé pour chaque appelant jusqu'à ce que quelqu'un le remarque. Une vérification HTTP avec une assertion sur le code de statut attendu, lancée avec un identifiant réel contre un point de terminaison authentifié, détecte cela dès que ça commence à se produire. Pour les API en particulier, associer cela à une surveillance d'API qui vérifie les corps de réponse en plus des codes de statut détecte aussi un jeton qui s'authentifie mais renvoie des données mal formées.

Erreurs associées

Voir 403 Forbidden pour les requêtes que le serveur a comprises et refusées quels que soient les identifiants, l'aperçu des 4xx pour la famille plus large des erreurs client, et les autres guides de ce lot : 405 Method Not Allowed, 422 Unprocessable Content.

Questions fréquentes

Pourquoi obtiens-je 401 juste après m'être connecté avec succès ?

Généralement une incompatibilité d'horloge entre votre appareil et le serveur, ou un client qui a mis en cache l'ancien jeton, maintenant invalide, au lieu d'utiliser celui fraîchement émis. Confirmez que l'heure de votre système est correcte et que le nouveau jeton est réellement envoyé.

Un 401 signifie-t-il que mon compte a été piraté ?

Pas en soi. Cela signifie presque toujours une session expirée, une clé révoquée, ou un en-tête envoyé incorrectement. Ne traitez cela comme un problème de sécurité que si vous ne vous attendiez pas à ce que l'identifiant cesse de fonctionner et ne pouvez pas expliquer pourquoi c'est arrivé.

Quelle est la différence entre 401 et un échec d'authentification au niveau de la couche TLS ?

Un échec de certificat client TLS empêche la connexion de s'établir du tout, donc aucun code de statut HTTP n'est jamais renvoyé. Un 401 signifie que la connexion a réussi et que le serveur a reçu une requête HTTP complète, puis l'a rejetée au niveau de la couche applicative pour manque d'identifiants valides.

Un formulaire de connexion lui-même devrait-il jamais renvoyer 401 ?

Non. Un point de terminaison de connexion évaluant un nom d'utilisateur et un mot de passe n'authentifie pas une requête existante ; un mauvais mot de passe là est conventionnellement un 400 ou un 200 avec une charge utile d'erreur, puisque tout l'objet du point de terminaison est d'accepter des tentatives non authentifiées et de les juger.

Une clé d'API valide peut-elle quand même produire un 401 ?

Oui, si elle est envoyée dans le mauvais en-tête ou le mauvais schéma, si elle a été renouvelée après que votre intégration ait mis en cache l'ancienne, ou si la requête a atteint le serveur à travers un proxy qui a retiré l'en-tête avant de la transmettre.