# Documentation Django 5.2.8

# Protection contre le « Cross site request forgery » (CSRF)

L’intergiciel et les balises de gabarit CSRF permettent de se protéger facilement contre les attaques de type Cross Site Request Forgeries. Ce type d’attaque se produit quand un site Web malveillant contient un lien, un bouton de formulaire ou un peu de JavaScript qui est destiné à effectuer une action sur votre site web, en utilisant les informations d’identification d’un utilisateur connecté qui visite le site malveillant dans son navigateur. Un type d’attaque liée est également couverte : celle du « login CSRF », où un site attaquant piège le navigateur d’un utilisateur en se connectant à un site avec les informations d’identification de quelqu’un d’autre.

La première ligne de défense contre les attaques CSRF est de s’assurer que les requêtes GET (et les autres méthodes « sûres », telles que définies par RFC 9110 Section 9.2.1) sont sans effet de bord. Les appels par des méthodes « non sûres », comme POST, PUT et DELETE, peuvent ensuite être protégés en suivant les étapes décrites dans Comment utiliser la protection CSRF de Django.

## Fonctionnement

La protection CSRF est basée sur les éléments suivants :

1. Un cookie CSRF qui est une valeur secrète aléatoire auquel les autres sites n’auront pas accès.

   `CsrfViewMiddleware` envoie ce cookie avec la réponse chaque fois que `django.middleware.csrf.get_token()` est appelée. Il peut aussi l’envoyer dans d’autres cas. Pour des raisons de sécurité, la valeur de la partie secrète est modifiée chaque fois qu’un utilisateur se connecte.

2. Un champ de formulaire masqué avec le nom « csrfmiddlewaretoken » est présent dans tous les formulaires POST affichés.

   Afin de protéger contre les attaques de type BREACH, la valeur de ce champ ne correspond pas simplement à la valeur secrète. Elle est obscurcie différemment pour chaque réponse à l’aide d’un masque. Le masque est généré aléatoirement lors de chaque appel à `get_token()` afin que la valeur du champ de formulaire soit différente à chaque fois.

   Cette action est effectuée par la balise de gabarit `csrf_token`.

3. Pour toutes les requêtes entrantes qui n’utilisent pas les méthodes HTTP GET, HEAD, OPTIONS ou TRACE, un cookie CSRF doit être présent, et le champ « csrfmiddlewaretoken » doit être présent et correct. Si ce n’est pas le cas, l’utilisateur obtiendra une erreur 403.

   Lors de la validation de la valeur de champ `csrfmiddlewaretoken`, seule la valeur secrète, et non pas le jeton complet, est comparée avec la valeur secrète du contenu du cookie. Cela permet d’utiliser des jetons qui changent constamment. Alors que chaque requête peut utiliser son propre jeton, la valeur secrète reste commune à toutes.

   Cette vérification est effectuée par l’intergiciel `CsrfViewMiddleware`.

4. `CsrfViewMiddleware` compare l’en-tête Origin, si fourni par le navigateur, avec l’hôte actuel et le réglage `CSRF_TRUSTED_ORIGINS`. Cela ajoute une protection contre les attaques de sous-domaines croisés.

5. De plus, pour les requêtes HTTPS, si l’en-tête `Origin` n’est pas présent, le `CsrfViewMiddleware` effectue un contrôle strict du référant. Cela signifie que même si un sous-domaine peut définir ou modifier des cookies pour votre domaine, il ne peut pas forcer un utilisateur à envoyer des données à votre application car cette requête ne viendrait pas de votre domaine exact.

   Cela protège aussi contre une attaque de type « Man-In-The-Middle » qui est possible sous HTTPS lors de l’utilisation d’une valeur secrète indépendante de la session, parce que les en-têtes HTTP `Set-Cookie` sont (malheureusement) acceptés par les clients, même quand ils parlent à un site en HTTPS. (La vérification du référant n’est pas faite pour les requêtes HTTP car la présence de l’en-tête `Referer` n’est pas suffisamment fiable sous HTTP.)

   Si le réglage `CSRF_COOKIE_DOMAIN` est défini, le référant est comparé avec lui. Il est possible d’autoriser les requêtes inter-domaines en incluant un point en premier. Par exemple, `CSRF_COOKIE_DOMAIN = '.exemple.com'` autorise les requêtes POST depuis `www.exemple.com` et `api.exemple.com`. Si le réglage n’est pas défini, le référant doit alors correspondre à l’en-tête HTTP `Host`.

   L’extension des référants acceptés au-delà de l’hôte courant ou du domaine du cookie peut se faire avec le réglage `CSRF_TRUSTED_ORIGINS`.

Cela garantit que seuls les formulaires originaires de domaines de confiance peuvent être utilisés pour renvoyer des données avec une requête POST.

Les requêtes GET sont volontairement ignorées (ainsi que les autres requêtes définies comme « sûres » par la RFC 9110 Section 9.2.1). Ces requêtes ne devraivent jamais avoir d’effets secondaires potentiellement dangereux, et de cette manière une attaque CSRF avec une requête GET doit être inoffensive. La RFC 9110 Section 9.2.1 définit les méthodes POST, PUT et DELETE comme « non sûres », et toutes les autres méthodes sont aussi supposées être dangereuses, pour que la protection soit maximale.

La protection CRSF ne peut pas protéger contre les attaques de « l’homme du milieu », c’est pourquoi il faut utiliser HTTPS avec Sécurité de transport HTTP stricte (HSTS). Il suppose également la validation de l’en-tête HOST et que le site ne comporte pas de vulnérabilités de scripts inter-sites (parce que ce type de vulnérabilité permet déjà à un attaquant de faire ce qu’une vulnérabilité CSRF permet de faire, et plus encore).

Suppression de l’en-tête `Referer`

Pour éviter de divulguer l’URL référent à des sites tiers, il peut être souhaitable de désactiver le référent dans les balises `<a>` de votre site. Par exemple, il est possible d’utiliser la balise `<meta name="referrer" content="no-referrer">` ou d’inclure l’en-tête `Referrer-Policy: no-referrer`. En raison du contrôle strict du référent dans la protection CSRF pour les requêtes HTTPS, ces techniques produisent des échecs CSRF pour les requêtes de méthodes « non sûres ». Il est préférable d’utiliser des alternatives telles que `<a rel="noreferrer" ...>"` pour les liens vers des sites tiers.

## Limitations

Les sous-domaines d’un site peuvent placer des cookies sur le client pour l’ensemble du domaine. En définissant le cookie et en utilisant le jeton correspondant, les sous-domaines seront en mesure de contourner la protection CSRF. La seule façon d’éviter cela est de s’assurer que les sous-domaines sont contrôlés par des utilisateurs de confiance (ou, au moins ne sont pas en mesure de définir des cookies). Notez que même sans CSRF, il existe d’autres vulnérabilités, comme la fixation de session, qui font que donner des sous-domaines à des tierces parties non sûres est une mauvaise idée ; ces vulnérabilités ne peuvent pas facilement être résolues avec les navigateurs actuels.

## Utilitaires

Les exemples ci-dessous s’appliquent à des vues basées sur des fonctions. Si vous utilisez des vues fondées sur les classes, vous pouvez vous référer à la Décoration des vues fondées sur les classes.

csrf_exempt(view)

  Ce décorateur marque une vue comme étant exempte de la protection assurée par l’intergiciel. Exemple :

      from django.http import HttpResponse
      from django.views.decorators.csrf import csrf_exempt

      @csrf_exempt
      def my_view(request):
          return HttpResponse("Hello world")

csrf_protect(view)

  Décorateur qui fournit la protection `CsrfViewMiddleware` pour une vue.

  Utilisation :

      from django.shortcuts import render
      from django.views.decorators.csrf import csrf_protect

      @csrf_protect
      def my_view(request):
          c = {}
          # ...
          return render(request, "a_template.html", c)

requires_csrf_token(view)

  Normalement, la balise de gabarit `csrf_token` ne fonctionnera pas si `CsrfViewMiddleware.process_view` ou un équivalent comme `csrf_protect` n’a pas été utilisé. Le décorateur de vue `requires_csrf_token` peut être utilisé pour s’assurer que la balise de gabarit fonctionne. Ce décorateur fonctionne de façon similaire à `csrf_protect`, mais ne rejette jamais une demande entrante.

  Exemple :

      from django.shortcuts import render
      from django.views.decorators.csrf import requires_csrf_token

      @requires_csrf_token
      def my_view(request):
          c = {}
          # ...
          return render(request, "a_template.html", c)

ensure_csrf_cookie(view)

  Ce décorateur force une vue à envoyer le cookie CSRF.

## Réglages

Un certain nombre de réglages peuvent être utilisés pour contrôler le comportement anti-CSRF de Django :

- `CSRF_COOKIE_AGE`

- `CSRF_COOKIE_DOMAIN`

- `CSRF_COOKIE_HTTPONLY`

- `CSRF_COOKIE_NAME`

- `CSRF_COOKIE_PATH`

- `CSRF_COOKIE_SAMESITE`

- `CSRF_COOKIE_SECURE`

- `CSRF_FAILURE_VIEW`

- `CSRF_HEADER_NAME`

- `CSRF_TRUSTED_ORIGINS`

- `CSRF_USE_SESSIONS`

## Questions fréquentes

### Est-ce que l’envoi d’une paire de jetons CSRF arbitraires (cookie et données POST) est une vulnérabilité ?

Non, délibérément pas. Sans attaque de « l’homme du milieu », il n’existe aucune possibilité pour un attaquant d’envoyer un cookie de jeton CSRF à destination du navigateur de sa victime ; une attaque réussie devrait pouvoir obtenir le cookie du navigateur de la victime par XSS ou autre moyen similaire, auquel cas l’attaquant n’a généralement pas besoin d’attaquer par CSRF.

Certains outils d’audit de sécurité le signalent comme un problème, mais comme mentionné ci-dessus, un attaquant ne peut pas voler un cookie CSRF du navigateur d’un utilisateur. Pouvoir « voler » ou modifier son propre jeton à l’aide de Firebug, des outils de développement Chrome, etc. ne signifie pas qu’il s’agit d’une vulnérabilité.

### Est-il problématique que la protection CSRF de Django n’est pas liée à une session par défaut ?

Non, délibérément pas. Le fait de ne pas lier la protection CSRF à une session permet d’utiliser la protection sur des sites tels que pastebin qui autorisent des envois de données par des utilisateurs anonymes et qui n’ont pas de session.

Si vous souhaitez stocker le jeton CSRF dans la session de l’utilisateur, définissez le réglage `CSRF_USE_SESSIONS`.

### Pourquoi un utilisateur peut-il recevoir une erreur de validation CSRF après s’être connecté ?

Pour des raisons de sécurité, les jetons CSRF subissent une rotation lors de chque connexion d’utilisateur. Toute page contenant un formulaire généré avant une connexion possédera un ancien jeton CSRF non valide et devra être rechargée. Cela peut arriver si un utilisateur utilise le bouton « Retour » après une connexion ou s’il se connecte dans un autre onglet du navigateur.