🌐 django-cors-headers — CORS propre et sécurisé sur Django

Same-Origin Policy (SOP) : le “mur” navigateur

Par défaut, un script JavaScript exécuté sur https://app.example.com n’a pas le droit de lire la réponse d’une requête faite vers https://api.example.com (origine différente). C’est la Same-Origin Policy.

CORS : une permission contrôlée par des headers

CORS est un mécanisme standard du web où le serveur indique au navigateur “tu peux autoriser ce JavaScript à lire cette réponse”. Le navigateur envoie un header Origin et le serveur répond avec des headers Access-Control-Allow-*.

Headers qui comptent le plus

Point clé : CORS n’est pas une auth

CORS ne “protège” pas vos endpoints contre un attaquant. Il contrôle seulement si le navigateur laisse un script lire la réponse. Un attaquant peut toujours appeler votre API depuis un serveur (curl, scripts) sans CORS.

Quand tu as besoin de django-cors-headers ?

• Ton frontend (React/Vue/Angular) est sur un autre domaine/port que ton backend Django.
• Tu utilises un API Gateway / domaine api.* séparé.
• Tu sers l’API sur localhost:8000 et le frontend sur localhost:5173.
• Tu as un backoffice / admin séparé d’un front grand public.

Le piège n°1 : “ça marche avec Postman”

Postman / curl ne sont pas soumis à la Same-Origin Policy. Donc l’API “répond” mais le navigateur bloque la lecture. Résultat : console “CORS error” alors que le backend fonctionne.

Le piège n°2 : préflight invisible

Tu vois ton POST échouer mais la vraie erreur est souvent sur le OPTIONS envoyé juste avant. Regarde dans DevTools → Network → requête OPTIONS.

Ressources de référence

- Page PyPI (description) : pypi.org/project/django-cors-headers
- Repo GitHub : github.com/adamchainz/django-cors-headers
- README (raw) : README.rst

Config DEV (rapide, contrôlée)

Objectif : autoriser uniquement ton front local (Vite/Next) + éventuellement un domaine de staging.

# settings_dev.py

INSTALLED_APPS += ["corsheaders"]

MIDDLEWARE = ["corsheaders.middleware.CorsMiddleware"] + MIDDLEWARE

CORS_ALLOWED_ORIGINS = [
    "http://localhost:5173",   # Vite
    "http://localhost:3000",   # Next.js/React dev
]

# Souvent utile quand tu as Authorization: Bearer ...
CORS_ALLOW_HEADERS = [
    "accept",
    "authorization",
    "content-type",
    "origin",
    "user-agent",
    "x-csrftoken",
    "x-requested-with",
    "x-request-id",
]

# Si tu utilises cookies de session en dev (rare pour API token)
CORS_ALLOW_CREDENTIALS = True

Config PROD (restrictive, robuste)

Objectif : autoriser précisément tes origines frontend, gérer credentials si besoin, et expliciter ce qui est exposé.

# settings_prod.py

INSTALLED_APPS += ["corsheaders"]
MIDDLEWARE = ["corsheaders.middleware.CorsMiddleware"] + MIDDLEWARE

CORS_ALLOWED_ORIGINS = [
    "https://app.example.com",
    "https://admin.example.com",
]

# Autoriser cookies / auth HTTP seulement si nécessaire
CORS_ALLOW_CREDENTIALS = True

# Headers que le browser est autorisé à envoyer
CORS_ALLOW_HEADERS = [
    "accept",
    "authorization",
    "content-type",
    "origin",
    "user-agent",
    "x-csrftoken",
    "x-requested-with",
    "x-request-id",
]

# Headers que le browser a le droit de lire côté JS
CORS_EXPOSE_HEADERS = [
    "content-disposition",  # download filename
    "x-request-id",         # corr_id
]

# Cache preflight (perf)
CORS_PREFLIGHT_MAX_AGE = 86400  # 24h

Quand un préflight est déclenché ?

Le navigateur déclenche souvent un OPTIONS avant la requête “réelle” quand :

• Méthode ≠ GET/HEAD/POST “simple” (PUT/PATCH/DELETE…)
• Content-Type non “simple” (souvent application/json)
• Headers custom (ex: Authorization, X-Request-ID)

Cache preflight

# Django
CORS_PREFLIGHT_MAX_AGE = 86400

Ce paramètre se traduit en Access-Control-Max-Age. Attention : certains navigateurs imposent des plafonds.

Préflight qui échoue : symptômes typiques

Reproduire un préflight en curl

curl -i -X OPTIONS https://api.example.com/v1/items \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type, authorization, x-request-id"

Clarification ultra importante

Pièges sécurité (top)

1. ALLOW_ALL en prod : expose ton API au JS de n’importe quel site (mauvais signe).
2. Cookies + CORS mal réglé : fuite de session potentielle, confusion avec SameSite.
3. Origines trop larges : regex permissive = attaque par sous-domaine contrôlé.
4. “CORS = firewall” : faux. Les requêtes serveur‑à‑serveur passent.
5. Réponses d’erreur sans CORS : tu débogues à l’aveugle (CORS error masque le vrai code).

Le cas “cookies cross-site” (le plus risqué)

Si ton API utilise session cookies, un navigateur peut envoyer ces cookies automatiquement sur des requêtes cross-site selon la politique SameSite/secure. CORS intervient seulement pour la lecture de la réponse par le script.

Checklist “safe-ish” si cookies nécessaires

• Origines explicitement listées (pas de wildcard)
• CORS_ALLOW_CREDENTIALS=True
• CSRF_TRUSTED_ORIGINS configuré (si POST authentifiés via cookie)
• Cookies marqués Secure en HTTPS
• SameSite ajusté selon architecture

Rappel : “CORS error” ≠ sécurité compromise

Un “CORS error” indique le plus souvent une configuration manquante ou trop restrictive. Ce n’est pas un “hack”, juste le browser qui applique SOP/CORS.

Recommandation générale

Mets CORS dans Django via django-cors-headers : la logique est proche de l’app, versionnée, testable, et cohérente avec les routes.

Anti‑patterns courants

1. Doubles headers : Django ajoute, Nginx ajoute → incohérences.
2. Nginx répond au OPTIONS mais pas Django → ok en prod, KO en dev/staging.
3. Cache/CDN qui sert une réponse avec mauvais Access-Control-Allow-Origin.

Snippet Nginx (si tu centralises)

Exemple “minimal” (à adapter ; préfère une whitelist stricte).

# location /api/ {
#   if ($request_method = OPTIONS) {
#     add_header Access-Control-Allow-Origin "https://app.example.com" always;
#     add_header Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS" always;
#     add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Request-ID" always;
#     add_header Access-Control-Max-Age 86400 always;
#     return 204;
#   }
#   add_header Access-Control-Allow-Origin "https://app.example.com" always;
#   add_header Access-Control-Allow-Credentials "true" always;
#   proxy_pass http://upstream_django;
# }

Pattern A : API publique + backoffice privé

- API publique consommée par plusieurs frontends → liste d’origines
- Admin interne → origine séparée + credentials

CORS_ALLOWED_ORIGINS = [
  "https://app.example.com",
  "https://admin.example.com",
  "https://partner.example.com",
]
CORS_ALLOW_CREDENTIALS = True

Pattern B : multi-environnements (dev/staging/prod)

Bon plan : déclarer les origins par env, via variables.

# settings.py
import os

CORS_ALLOWED_ORIGINS = os.getenv("CORS_ALLOWED_ORIGINS","").split(",")
CORS_ALLOWED_ORIGINS = [o.strip() for o in CORS_ALLOWED_ORIGINS if o.strip()]

# .env
CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com

Pattern C : preview deployments

Ton frontend a des URLs temporaires, il faut une regex stricte et “safe”.

CORS_ALLOWED_ORIGIN_REGEXES = [
  r"^https://pr-\d+\.preview\.example\.com$",
]

Pattern D : downloads (CSV/PDF)

Si tu veux lire le nom de fichier côté JS : expose Content-Disposition.

CORS_EXPOSE_HEADERS = ["content-disposition"]

Pattern E : Observabilité

• Ajoute X-Request-ID (corr_id) partout
• Expose-le via CORS pour debug front
• Logue l’Origin sur erreurs CORS (en staging)

CORS_EXPOSE_HEADERS = ["x-request-id"]

Officiel (à privilégier)

• PyPI : django-cors-headers
• GitHub : repo officiel
• README : README.rst
• Changelog (sécurité, breaking changes) : CHANGELOG.rst

Références “compréhension”

• Guide Django CORS (2025) : StackHawk
• freeCodeCamp (2025) : How to Enable CORS in Django

Outils pratiques

• DevTools Network (Chrome/Firefox) : inspecter OPTIONS + headers
• curl : reproduire préflight exactement
• Tests Django/pytest : verrouiller la config

Échelle de difficulté (1 → 10)

Ce qui rend CORS “galère”

• Différences de scheme/port entre dev/staging/prod
• Préflight masqué derrière des redirects
• Headers supprimés par proxy/CDN
• Credentials + cookies + CSRF (triple combo)
• Regex trop permissives (sécurité)