Configure CORS policies for Nginx Ingress - Container Service for Kubernetes

Fonctionnement

Le mécanisme CORS gère deux types de requêtes : les requêtes simples et les requêtes préliminaires (preflight).

Une requête simple est envoyée directement au serveur :

Le navigateur ajoute l'en-tête Origin à la requête, par exemple Origin: https://example.com.
Le contrôleur Nginx Ingress compare la méthode HTTP et la valeur de Origin avec la configuration CORS. Si elles correspondent, il ajoute Access-Control-Allow-Origin à la réponse.
Le navigateur vérifie si Access-Control-Allow-Origin correspond à l'origine de la requête. Une correspondance indique un succès ; un en-tête absent ou non correspondant entraîne un échec.

Une requête préliminaire (preflight) envoie une vérification OPTIONS avant la requête principale :

Le navigateur envoie une requête OPTIONS accompagnée des en-têtes Access-Control-Request-Method et Access-Control-Request-Headers décrivant la requête réelle.
Si la méthode ou les en-têtes ne sont pas autorisés, la requête préliminaire échoue et la requête principale n'est jamais envoyée. Si elle réussit, la requête principale se déroule comme une requête simple.

Une requête déclenche une étape préliminaire dans les cas suivants :

La méthode utilisée n'est ni GET, ni HEAD, ni POST.
La méthode est POST et Content-Type n'est ni text/plain, ni application/x-www-form-urlencoded, ni multipart/form-data.
La requête inclut un en-tête personnalisé.

Important

Lorsque cors-allow-credentials est défini sur "true", ne configurez pas cors-allow-origin sur "*". La spécification W3C interdit cette combinaison : lorsqu'une requête transporte des informations d'identification (comme des cookies), le serveur doit explicitement nommer l'origine de confiance. L'utilisation de "*" permettrait à n'importe quel site web d'envoyer des requêtes authentifiées au nom d'un utilisateur, ce qui constitue un risque de sécurité.

Configurer CORS

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un cluster ACK avec le contrôleur Nginx Ingress déployé
Une ressource Ingress acheminant le trafic vers votre service backend
Les autorisations nécessaires pour modifier les ressources Ingress dans le cluster

Ajouter des annotations CORS

Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.
Sur la page Clusters, cliquez sur le cluster cible. Dans le volet de navigation de gauche, sélectionnez Network > Ingresses.
Sur la page Ingresses, repérez l'Ingress cible et cliquez sur Edit YAML dans la colonne Actions.
Ajoutez les annotations CORS à metadata.annotations en fonction de votre scénario.

Scénario A : Requêtes avec informations d'identification ou cookies (recommandé)

Utilisez cette configuration lorsque votre frontend (https://example.com ou https://app.example.com) envoie des informations d'identification, telles que des cookies ou un en-tête Authorization, vers une API backend (https://api.example.com).

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress-secure
  annotations:
    # Enable CORS.
    nginx.ingress.kubernetes.io/enable-cors: "true"
    # Allow requests with credentials, such as cookies and Authorization headers.
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    # Specify exact origins. Do not use "*" when credentials are enabled.
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com, https://app.example.com"
    # Specify the allowed HTTP methods.
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, DELETE, OPTIONS"
    # Specify the allowed request headers, including any custom headers your application requires.
    nginx.ingress.kubernetes.io/cors-allow-headers: "Content-Type, Authorization"
    # Specify which custom response headers are exposed to browser JavaScript.
    nginx.ingress.kubernetes.io/cors-expose-headers: "X-Request-ID, Content-Length, Content-Range"
    # Set the preflight cache duration in seconds. 86400 = 24 hours.
    nginx.ingress.kubernetes.io/cors-max-age: "86400"
...

Scénario B : Requêtes sans informations d'identification

Cette option convient aux API publiques en lecture seule ne nécessitant aucune authentification.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress-public
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
    # Must be "false" when cors-allow-origin is "*".
    nginx.ingress.kubernetes.io/cors-allow-credentials: "false"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, HEAD"
...

Vérifier la configuration CORS

Utilisez curl pour simuler une requête préliminaire de navigateur :

curl -i -X OPTIONS 'https://api.example.com/your/path' \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: Content-Type, Authorization'

Une requête préliminaire réussie renvoie un code d'état 2xx, généralement 204 No Content ou 200 OK :

HTTP/2 204
date: Fri, 12 Sep 2025 03:51:12 GMT
access-control-allow-origin: https://example.com, https://app.example.com
access-control-allow-credentials: true
access-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS
access-control-allow-headers: Content-Type, Authorization

Vérifiez que chaque valeur access-control-allow-* correspond à l'annotation nginx.ingress.kubernetes.io/cors-* correspondante dans votre Ingress.

Référence des annotations CORS

Annotation	Description	En-tête HTTP	Exemple
`nginx.ingress.kubernetes.io/enable-cors`	Active ou désactive CORS.	S/O	`nginx.ingress.kubernetes.io/enable-cors: "true"`
`nginx.ingress.kubernetes.io/cors-allow-origin`	Origines autorisées. Séparez plusieurs origines par des virgules.	`Access-Control-Allow-Origin`	`nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"`
`nginx.ingress.kubernetes.io/cors-allow-methods`	Méthodes HTTP autorisées.	`Access-Control-Allow-Methods`	`nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH, OPTIONS"`
`nginx.ingress.kubernetes.io/cors-allow-headers`	En-têtes de requête personnalisés autorisés.	`Access-Control-Allow-Headers`	`nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range"`
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Indique s'il faut autoriser les requêtes avec informations d'identification, telles que les cookies ou l'authentification HTTP. Doit être défini sur `"false"` lorsque `cors-allow-origin` est défini sur `"*"`.	`Access-Control-Allow-Credentials`	`nginx.ingress.kubernetes.io/cors-allow-credentials: "true"`
`nginx.ingress.kubernetes.io/cors-expose-headers`	En-têtes de réponse exposés au JavaScript du navigateur. Par défaut, seuls les en-têtes standard (`Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified`, `Pragma`) sont accessibles. Exposez des en-têtes personnalisés tels que `X-Request-ID`. Nécessite le contrôleur Nginx Ingress v0.44 ou version ultérieure.	`Access-Control-Expose-Headers`	`nginx.ingress.kubernetes.io/cors-expose-headers: "Content-Length,Content-Range"`
`nginx.ingress.kubernetes.io/cors-max-age`	Durée maximale (en secondes) pendant laquelle un navigateur peut mettre en cache la réponse préliminaire. Des valeurs plus élevées réduisent le nombre de requêtes préliminaires ; des valeurs plus faibles améliorent la sécurité.	`Access-Control-Max-Age`	`nginx.ingress.kubernetes.io/cors-max-age: "86400"`

FAQ

Comment résoudre les erreurs inter-origines ?

Examinez les requêtes réseau dans les outils de développement de votre navigateur ou dans les journaux du contrôleur Nginx Ingress. Vérifiez que l'origine, la méthode et les en-têtes de la requête correspondent aux annotations CORS de votre Ingress.

Messages d'erreur courants et leurs causes :

Method POST is not allowed by Access-Control-Allow-Methods in preflight response — la méthode n'est pas répertoriée dans cors-allow-methods.
Access to fetch at 'https://api.example.com/data' from origin 'https://app.example.com' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: xxxx. — échec de la requête préliminaire ; comparez les en-têtes de réponse access-control-allow-* avec vos valeurs d'annotation.

Comment configurer différentes politiques CORS pour différents chemins sur le même domaine ?

Les annotations CORS s'appliquent au niveau de l'Ingress ; la configuration au niveau du chemin n'est pas prise en charge. Créez des ressources Ingress distinctes pour les groupes de chemins nécessitant des politiques différentes, par exemple api-public-ingress.yaml pour les chemins publics et api-private-ingress.yaml pour les chemins authentifiés.

Comment exposer des en-têtes de réponse personnalisés au JavaScript du navigateur ?

Dans les réponses inter-origines, les navigateurs ne peuvent accéder qu'à ces en-têtes standard : Cache-Control, Content-Language, Content-Type, Expires, Last-Modified et Pragma. Les en-têtes personnalisés, tels que X-Request-ID, restent invisibles pour JavaScript sauf s'ils sont explicitement exposés.

Ajoutez cors-expose-headers à vos annotations pour les exposer. Consultez la section Scénario A : Requêtes avec informations d'identification ou cookies.

Références

Enable CORS — référence officielle des annotations ingress-nginx
Dépannage des problèmes Nginx Ingress