En-tête Set-Cookie

Syntaxe

Set-Cookie: <cookie-name>=<cookie-value>
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>
Set-Cookie: <cookie-name>=<cookie-value>; Expires=<date>
Set-Cookie: <cookie-name>=<cookie-value>; HttpOnly
Set-Cookie: <cookie-name>=<cookie-value>; Max-Age=<number>
Set-Cookie: <cookie-name>=<cookie-value>; Partitioned
Set-Cookie: <cookie-name>=<cookie-value>; Path=<path-value>
Set-Cookie: <cookie-name>=<cookie-value>; Secure

Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Strict
Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Lax
Set-Cookie: <cookie-name>=<cookie-value>; SameSite=None; Secure

// L'usage d'attributs multiples est également possible, par exemple :
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly

Attributs

<cookie-name>=<cookie-value>

Définit le nom du cookie et sa valeur. Une définition de cookie commence par une paire nom-valeur.

Un <cookie-name> peut contenir n'importe quel caractère US-ASCII à l'exception des caractères de contrôle (caractères ASCII 0 à 31 et caractère ASCII 127) ou des caractères séparateurs (espace, tabulation et les caractères : ( ) < > @ , ; : \ " / [ ] ? = { })

Une <cookie-value> peut éventuellement être entourée de guillemets et inclure n'importe quel caractère US-ASCII à l'exception des caractères de contrôle (caractères ASCII 0 à 31 et caractère ASCII 127), espaces blancs, guillemets, virgules, points-virgules et barres obliques inverses.

Encodage : De nombreuses implémentations effectuent un encodage en pourcentage sur les valeurs de cookie. Cependant, cela n'est pas requis par la spécification RFC. L'encodage en pourcentage aide à satisfaire les exigences des caractères autorisés pour <cookie-value>.

Note : Certains noms de cookie contiennent des préfixes qui imposent des restrictions spécifiques sur les attributs du cookie dans les agents utilisateurs qui les prennent en charge. Voir Préfixes de cookie pour plus d'informations.

Domain=<domain-value> Facultatif

Définit les hôtes auxquels le cookie est envoyé.

Définir le domaine rend le cookie disponible pour ce domaine et tous ses sous-domaines. Si omis, le cookie n'est retourné qu'à l'hôte qui l'a envoyé (c'est-à-dire qu'il devient un « cookie réservé à l'hôte »). Cela est plus restrictif que de définir le nom de l'hôte, car le cookie n'est pas rendu disponible pour les sous-domaines de l'hôte.

La valeur doit être le domaine du serveur qui envoie l'en-tête de réponse Set-Cookie, ou un domaine parent de ce domaine. Il ne peut pas s'agir d'un suffixe public ^(angl.) tel que com, co.uk ou github.io. Par exemple, une réponse de api.example.com peut définir Domain=api.example.com ou Domain=example.com, mais pas Domain=beta.api.example.com, Domain=other.example.com ou Domain=com. De même, une réponse de shop.example.co.uk peut définir Domain=shop.example.co.uk ou Domain=example.co.uk, mais pas Domain=co.uk, car co.uk est un suffixe public. Les cookies qui enfreignent ces règles sont ignorés.

Contrairement aux spécifications antérieures, les points initiaux dans les noms de domaine (.example.com) sont ignorés.

Plusieurs valeurs d'hôte/domaine ne sont pas autorisées, mais si un domaine est définit, alors les sous-domaines sont toujours inclus.

Expires=<date> Facultatif

Indique la durée de vie maximale du cookie sous la forme d'un horodatage de date HTTP. Voir Date pour le format requis.

Si cette valeur n'est pas définie, le cookie devient un cookie de session. Une session prend fin lorsque le client se déconnecte, après quoi le cookie de session est supprimé.

Attention : De nombreux navigateurs web disposent d'une fonctionnalité de restauration de session qui enregistre tous les onglets et les restaure la prochaine fois que le navigateur est utilisé. Les cookies de session sont également restaurés, comme si le navigateur n'avait jamais été fermé.

Le serveur définit l'attribut Expires avec une valeur relative à sa propre horloge interne, qui peut différer de celle du navigateur client. Firefox et les navigateurs basés sur Chromium utilisent en interne une valeur d'expiration (max-age) ajustée pour compenser le décalage des horloges, et enregistrent puis suppriment les cookies en fonction de l'heure prévue par le serveur. Le calcul de l'ajustement du décalage des horloges utilise la valeur de l'en-tête DATE. Notez que la spécification explique comment analyser l'attribut, mais n'indique pas si ni comment le destinataire doit corriger la valeur.

HttpOnly Facultatif

Interdit à JavaScript d'accéder au cookie, par exemple, par le biais de la propriété Document.cookie. Notez qu'un cookie créé avec HttpOnly est toujours envoyé avec les requêtes initiées par JavaScript, par exemple lors de l'appel à XMLHttpRequest.send() ou à fetch(). Cela atténue les attaques de type XSS.

Max-Age=<number> Facultatif

Indique le nombre de secondes avant l'expiration du cookie. Une valeur nulle ou négative expire immédiatement le cookie. Si Expires et Max-Age sont tous deux définis, Max-Age est prioritaire.

Partitioned Facultatif

Indique que le cookie doit être enregistré dans un stockage partitionné. Notez que si cet attribut est défini, la directive Secure doit également être définie. Consultez l'article Cookies à état partitionné indépendant (CHIPS) pour plus de détails.

Path=<path-value> Facultatif

Indique le chemin qui doit figurer dans l'URL demandée pour que le navigateur envoie l'en-tête Cookie.

S'il est omis, cet attribut prend par défaut la partie chemin de l'URL de la requête. Par exemple, si un cookie est défini par une requête vers https://example.com/docs/Web/HTTP/index.html, le chemin par défaut est /docs/Web/HTTP/.

Le caractère barre oblique (/) est interprété comme un séparateur de répertoires, et les sous-répertoires correspondent également. Par exemple, pour Path=/docs,

• les chemins de requête /docs, /docs/, /docs/Web/ et /docs/Web/HTTP correspondent tous.
• les chemins de requête /, /docsets et /fr/docs ne correspondent pas.

Note : L'attribut path vous permet de contrôler les cookies que le navigateur envoie en fonction des différentes parties d'un site. Il ne constitue pas une mesure de sécurité et ne protège pas contre la lecture non autorisée du cookie depuis un autre chemin.

SameSite=<samesite-value> Facultatif

Contrôle si un cookie est envoyé ou non avec les requêtes inter-sites : c'est-à-dire les requêtes provenant d'un site différent, schéma compris, du site qui a défini le cookie. Cela offre une certaine protection contre certaines attaques inter-sites, notamment les attaques par falsification de requête inter-site (CSRF).

Les valeurs d'attribut possibles sont :

Strict

Envoie le cookie uniquement pour les requêtes provenant du même site que celui qui a défini le cookie.

Lax

Envoie le cookie uniquement pour les requêtes provenant du même site que celui qui a défini le cookie, ainsi que pour les requêtes inter-sites qui répondent aux deux critères suivants :

• La requête correspond à une navigation de premier niveau : en pratique, cela signifie qu'elle modifie l'URL affichée dans la barre d'adresse du navigateur.

  • Cela exclut, par exemple, les requêtes effectuées avec l'API fetch(), les requêtes de ressources intégrées provenant d'éléments HTML <img> ou <script>, ainsi que les navigations dans des éléments HTML <iframe>.

  • Cela inclut les requêtes effectuées lorsque l'utilisateur·ice clique sur un lien dans le contexte de navigation de premier niveau pour passer d'un site à un autre, une affectation à document.location ou l'envoi d'un élément <form>.

• La requête utilise une méthode sûre : cela exclut notamment POST, PUT et DELETE.

Certains navigateurs utilisent Lax comme valeur par défaut si SameSite n'est pas défini : consultez la section Compatibilité des navigateurs pour plus de détails.

Note : Lorsque Lax est appliqué par défaut, une version plus permissive est utilisée. Dans cette version, les cookies sont également inclus dans les requêtes POST, à condition qu'ils soient définis au plus deux minutes avant la requête.

None

Envoie le cookie avec les requêtes inter-sites et les requêtes de même site. L'attribut Secure doit également être défini avec cette valeur.

Secure Facultatif

Indique que le cookie est envoyé au serveur uniquement lorsqu'une requête est effectuée avec le schéma https: (sauf sur localhost), et qu'il est donc plus résistant aux attaques du manipulateur du milieu (MITM).

Note : Ne supposez pas que Secure empêche tout accès aux informations sensibles des cookies (clés de session, identifiants de connexion, etc.). Les cookies avec cet attribut peuvent toujours être lus ou modifiés depuis le disque dur du client ou depuis JavaScript si l'attribut de cookie HttpOnly n'est pas défini.

Les sites non sécurisés (http:) ne peuvent pas définir de cookies avec l'attribut Secure. Les exigences relatives à https: sont ignorées lorsque l'attribut Secure est défini par localhost.

Préfixes de cookie

Certains noms de cookie contiennent des préfixes qui imposent des restrictions particulières sur les attributs des cookies dans les agents utilisateurs qui les prennent en charge. Tous les préfixes de cookie commencent par deux traits de soulignement (__) et se terminent par un tiret (-). Les préfixes suivants sont définis :

• __Secure- : Les cookies dont le nom commence par __Secure- doivent être définis avec l'attribut Secure par une page sécurisée (HTTPS).
• __Host- : Les cookies dont le nom commence par __Host- doivent être définis avec l'attribut Secure par une page sécurisée (HTTPS). De plus, ils ne doivent pas avoir d'attribut Domain défini, et l'attribut Path doit prendre la valeur /. Cela garantit que ces cookies sont envoyés uniquement à l'hôte qui les a définis, et non à un autre hôte du domaine. Cela garantit également qu'ils sont définis pour tout l'hôte et qu'ils ne peuvent pas être remplacés sur un chemin de cet hôte. Cette combinaison produit un cookie qui traite l'origine presque comme une limite de sécurité.
• __Http- : Les cookies dont le nom commence par __Http- doivent être définis avec l'indicateur Secure par une page sécurisée (HTTPS) et doivent également avoir l'attribut HttpOnly défini pour prouver qu'ils sont définis par l'en-tête Set-Cookie (ils ne peuvent pas être définis ou modifiés par des fonctionnalités JavaScript telles que Document.cookie ou l'API Cookie Store).
• __Host-Http- : Les cookies dont le nom commence par __Host-Http- doivent être définis avec l'indicateur Secure par une page sécurisée (HTTPS) et doivent avoir l'attribut HttpOnly défini pour prouver qu'ils sont définis par l'en-tête Set-Cookie. De plus, ils ont les mêmes restrictions que les cookies préfixés par __Host-. Cette combinaison produit un cookie qui traite l'origine presque comme une frontière de sécurité, tout en veillant à ce que les personnes chargées du développement et de l'exploitation des serveurs sachent que la portée du cookie se limite aux requêtes HTTP.

Exemples

Cookie de session

Les cookies de session sont supprimés quand le client s'éteint. Les cookies sont des cookies de session s'ils n'ont pas de directive Expires ou Max-Age.

Set-Cookie: sessionId=38afes7a8

Cookie permanent

Les cookies permanents sont supprimés à une date spécifique (Expires) ou après une durée spécifique (Max-Age) et non lorsque le client est fermé.

Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT

Set-Cookie: id=a3fWa; Max-Age=2592000

Domaines invalides

Un cookie pour un domaine qui n'inclut pas le serveur qui le définit doit être rejeté par l'agent utilisateur ^(angl.).

Le cookie suivant est rejeté si le serveur est hébergé sur original-company.com :

Set-Cookie: qwerty=219ffwef9w0f; Domain=some-company.co.uk

Un cookie pour un sous-domaine du domaine servi est rejeté.

Le cookie suivant est rejeté si le serveur est hébergé sur example.com :

Set-Cookie: sessionId=e8bb43229de9; Domain=foo.example.com

Préfixes de cookie

Les noms de cookies préfixés par __Secure- ou __Host- ne peuvent être utilisés que s'ils sont définis avec l'attribut Secure à partir d'une origine sécurisée (HTTPS).

Les noms de cookies préfixés par __Http- ou __Host-Http- ne peuvent être utilisés que s'ils sont définis avec l'attribut Secure à partir d'une origine sécurisée (HTTPS) et doivent en outre comporter l'attribut HttpOnly pour prouver qu'ils ont été définis par l'en-tête Set-Cookie et non côté client par JavaScript.

De plus, les cookies préfixés par __Host- ou __Host-Http- doivent avoir un chemin de type / (ce qui signifie n'importe quel chemin sur l'hôte) et ne doivent pas posséder d'attribut Domain.

// Les deux sont acceptés s'ils viennent d'une origine sécurisée (HTTPS)
Set-Cookie: __Secure-ID=123; Secure; Domain=example.com
Set-Cookie: __Host-ID=123; Secure; Path=/

// Rejeté, car l'attribut Secure est manquant
Set-Cookie: __Secure-id=1

// Rejeté, car l'attribut Path=/ est manquant
Set-Cookie: __Host-id=1; Secure

// Rejeté, car un attribut Domain est défini
Set-Cookie: __Host-id=1; Secure; Path=/; Domain=example.com

// Ne peut être défini que par Set-Cookie
Set-Cookie: __Http-ID=123; Secure; Domain=example.com
Set-Cookie: __Host-Http-ID=123; Secure; Path=/

Cookies partitionnés

Set-Cookie: __Host-example=34d8g; SameSite=None; Secure; Path=/; Partitioned;

Spécifications

Compatibilité des navigateurs

Voir aussi

• Cookies HTTP
• L'en-tête Cookie
• La propriété API Document.cookie
• Les cookies SameSite expliqués ^(angl.) (blog web.dev)