Pourquoi les en-têtes HTTP avec des underscores sont-ils supprimés par Nginx ?

La suppression silencieuse : Comportement par défaut de Nginx

Nginx supprime par défaut les en-têtes contenant des tirets bas. Cela se produit sans avertissement ni message d'erreur. Lorsque Nginx reçoit une requête avec des en-têtes contenant des tirets bas, il supprime ces en-têtes avant d'envoyer la requête au serveur backend ou à l'application. Cette suppression peut causer des problèmes dans les applications web qui utilisent ces en-têtes personnalisés pour des fonctionnalités ou le transfert de données.

La nature cachée de ce processus rend difficile pour les développeurs et les administrateurs système de trouver la cause des problèmes liés aux données d'en-tête manquantes. Les utilisateurs peuvent passer du temps à déboguer leurs applications, sans savoir que Nginx supprime leurs en-têtes personnalisés. Ce comportement par défaut peut être problématique lors du travail avec des services tiers ou des API qui utilisent des en-têtes avec des tirets bas, car il peut perturber le flux d'informations entre les systèmes.

Contexte historique : Variables CGI et conversion des en-têtes

Le comportement de Nginx consistant à supprimer les en-têtes avec des tirets bas découle de l'héritage du Common Gateway Interface (CGI). CGI est une ancienne norme permettant aux serveurs web d'exécuter des programmes externes et de renvoyer leur sortie aux clients web. Il a influencé la manière dont les serveurs web gèrent les en-têtes HTTP.

Dans CGI, les en-têtes HTTP sont convertis en variables d'environnement utilisables par les scripts. Lors de cette conversion, les tirets et les tirets bas dans les noms d'en-têtes sont transformés en tirets bas. Par exemple, un en-tête comme "Custom-Header" devient "HTTP_CUSTOM_HEADER" en tant que variable d'environnement CGI. Ce processus peut créer une confusion lorsque les en-têtes contiennent déjà des tirets bas.

Pour éviter ces ambiguïtés, Nginx supprime par défaut les en-têtes avec des tirets bas. Cette décision évite les problèmes où différents en-têtes pourraient être mappés au même nom de variable CGI. Par exemple, "Custom_Header" et "Custom-Header" deviendraient tous deux "HTTP_CUSTOM_HEADER" en CGI, rendant peu clair quel en-tête original la variable représente.

Bien que cette approche résolve le problème d'ambiguïté, elle peut causer un comportement inattendu dans les applications web modernes qui n'utilisent pas CGI et s'appuient sur des en-têtes personnalisés avec des tirets bas. Comprendre ce contexte historique aide à expliquer pourquoi Nginx gère ainsi les en-têtes contenant des tirets bas, même si ce n'est pas toujours le comportement souhaité dans les pratiques actuelles de développement web.

Clarification de la RFC HTTP

La RFC HTTP (Request for Comments) autorise l'utilisation de tirets bas dans les noms d'en-têtes. Cela est souvent mal compris par les développeurs et les administrateurs système. La spécification HTTP permet de nombreux caractères dans les noms d'en-têtes, y compris les tirets bas.

La confusion vient souvent d'une mauvaise interprétation des règles de caractères ASCII dans la RFC. La spécification HTTP/1.1 (RFC 2616) fait référence à la RFC 822 pour les formats des champs d'en-tête. La RFC 822 stipule que les noms de champs doivent utiliser des caractères ASCII imprimables, ce qui inclut les caractères avec des valeurs décimales entre 33 et 126, à l'exception des deux-points. Le caractère tiret bas (valeur décimale 95) est dans cette plage autorisée.

Certains développeurs pensent que les tirets bas ne sont pas autorisés car certains serveurs web, comme Apache ou Nginx, les traitent comme invalides par défaut. Cependant, il s'agit d'un choix spécifique au serveur, pas d'une exigence de la norme HTTP.

Bien que les tirets bas soient autorisés dans les noms d'en-têtes HTTP selon la RFC, leur utilisation peut causer des problèmes avec certains serveurs ou proxys qui ne sont pas configurés pour les gérer. Pour cette raison, il est souvent préférable d'utiliser des tirets plutôt que des tirets bas dans les noms d'en-têtes personnalisés pour éviter des problèmes potentiels.

Activation des en-têtes avec tirets bas : La solution de configuration

Pour résoudre le problème de la suppression par Nginx des en-têtes contenant des tirets bas, vous pouvez utiliser la directive 'underscores_in_headers on;' dans votre configuration Nginx. Cette directive indique à Nginx d'accepter et de transmettre les en-têtes contenant des tirets bas.

Pour mettre en œuvre cette solution, ajoutez la ligne suivante à votre configuration Nginx :

underscores_in_headers on;

Vous pouvez placer cette directive à différents endroits dans votre fichier de configuration Nginx, selon l'étendue de son application :

1. Bloc server : Si vous voulez activer les en-têtes avec tirets bas pour un serveur spécifique, ajoutez la directive à l'intérieur du bloc server. Par exemple :

server {
    listen 80;
    server_name example.com;
    underscores_in_headers on;
    # Autres configurations du serveur...
}

2. Bloc http : Pour activer les en-têtes avec tirets bas pour tous les serveurs, placez la directive dans le bloc http de votre configuration Nginx :

http {
    underscores_in_headers on;
    # Autres configurations http...
}

3. Bloc location : Si vous avez seulement besoin d'autoriser les en-têtes avec tirets bas pour des emplacements spécifiques, ajoutez la directive au bloc location concerné :

location /api {
    underscores_in_headers on;
    # Autres configurations de location...
}

Après avoir ajouté la directive, redémarrez Nginx pour appliquer les changements. Cela permettra à Nginx de traiter et de transmettre les en-têtes contenant des tirets bas, résolvant ainsi le problème des en-têtes personnalisés manquants dans vos applications.

N'oubliez pas de tester votre configuration après avoir effectué ces modifications pour vous assurer que tout fonctionne comme prévu.

curl -I -H "X_Custom_Header: TestValue" http://votre-domaine.com