WWW-Authenticate

Utilisation

Lorsqu’un client demande une ressource protégée sans identifiants valides, le serveur répond avec un code de statut 401 et inclut l’en-tête WWW-Authenticate. Cet en-tête transporte un ou plusieurs défis d’authentification, chacun indiquant un schéma ainsi que les paramètres dont le client a besoin pour construire des identifiants valides.

Après réception du défi, le client resoumet la requête avec un en-tête Authorization contenant les identifiants formatés selon le schéma retenu. Le serveur valide les identifiants et renvoie la ressource demandée en cas de succès.

Plusieurs défis dans une même réponse permettent au serveur de proposer simultanément plusieurs schémas. Le client sélectionne le schéma le plus robuste pris en charge par les deux parties. Les défis apparaissent sur des lignes d’en-tête distinctes ou sur une seule ligne séparée par des virgules.

L’en-tête équivalent pour l’authentification au niveau du proxy est Proxy-Authenticate, qui déclenche une réponse 407 au lieu d’une 401.

scheme

Le schéma identifie la méthode d’authentification. Les schémas enregistrés sont tenus à jour par l’IANA. Les schémas les plus courants en pratique sont décrits ci-dessous.

Basic envoie un couple username:password encodé en Base64. Le schéma accepte un paramètre realm et un paramètre charset facultatif (généralement UTF-8).

Bearer authentifie à l’aide d’un jeton d’accès opaque, le plus souvent émis via un flux OAuth. Le schéma prend en charge les paramètres realm, scope et error. Le paramètre scope énumère les autorisations que le jeton doit porter. Le paramètre error communique des motifs d’échec précis comme invalid_token ou insufficient_scope.

Digest améliore Basic en hachant les identifiants avec un nonce fourni par le serveur, ce qui évite que le mot de passe circule en clair. Les paramètres requis comprennent realm, nonce et qop (quality of protection). Les paramètres facultatifs comprennent algorithm, opaque et stale.

Negotiate amorce une authentification basée sur SPNEGO, généralement adossée à Kerberos ou NTLM dans les environnements d’entreprise. Le schéma transporte un jeton SPNEGO encodé en Base64 lorsque la négociation est en cours.

realm

Le paramètre realm est une chaîne facultative définissant l’espace de protection. Sa valeur aide les utilisateurs à identifier quels identifiants sont nécessaires. Un serveur protégeant différentes zones attribue à chacune une valeur de realm distincte.

token68

La syntaxe token68 est un encodage d’identifiants alternatif autorisé par le cadre d’authentification HTTP. La valeur utilise un jeu de caractères restreint (caractères alphanumériques, -, ., _, ~, +, /) avec un remplissage = facultatif en fin de chaîne.

Exemple

Un serveur protégeant une ressource par authentification Basic renvoie un défi incluant le nom de realm affiché à l’utilisateur.

WWW-Authenticate: Basic realm="Staging Environment"

Un défi de jeton Bearer communique le scope requis et signale un jeton expiré au moyen du paramètre error.

WWW-Authenticate: Bearer realm="api.example.re", scope="read write", error="invalid_token"

Un défi Digest comprend le nonce généré par le serveur et le réglage de quality of protection.

WWW-Authenticate: Digest realm="admin@example.re", nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v", qop="auth", algorithm=SHA-256

Un serveur proposant plusieurs schémas les énumère afin que le client choisisse l’option la plus robuste.

WWW-Authenticate: Negotiate
WWW-Authenticate: Bearer realm="api.example.re"
WWW-Authenticate: Basic realm="api.example.re"

Un échange complet d’authentification Basic. Le client demande d’abord une ressource protégée sans identifiants :

GET /admin HTTP/1.1
Host: example.re

Le serveur répond avec un 401 et un défi Basic :

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="API"

Le client réessaie avec un en-tête Authorization contenant le couple username:password encodé en Base64 :

GET /admin HTTP/1.1
Host: example.re
Authorization: Basic dXNlcjpwYXNz

Le serveur valide les identifiants et renvoie la ressource :

HTTP/1.1 200 OK
Content-Type: text/html