jwt : Module JWT pour NGINX

Installation

Vous pouvez installer ce module sur toute distribution basée sur RHEL, y compris, mais sans s'y limiter :

RedHat Enterprise Linux 7, 8, 9 et 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 et Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 et Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-jwt

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-jwt

Activez le module en ajoutant la ligne suivante en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_auth_jwt_module.so;

Ce document décrit nginx-module-jwt v3.4.6 publié le 01 août 2026.

Module d'authentification JWT pour Nginx

Il s'agit d'un module NGINX permettant de vérifier la validité d'un JWT. Ce module se veut aussi léger que possible et simple :

Image Docker basée sur le Dockerfile nginx officiel (alpine).
Image légère (~400KB de plus que l'image officielle).

Démarrage rapide :

Image Docker :

L'image est générée avec Github Actions (voir nginx-jwt-module:latest)

docker pull ghcr.io/max-lt/nginx-jwt-module:latest

Une variante plus légère basée sur nginx:alpine-slim (sans les modules dynamiques nginx supplémentaires tels que njs, image-filter, xslt ou geoip) est également disponible :

docker pull ghcr.io/max-lt/nginx-jwt-module:latest-slim

Paquets pré-compilés (Ubuntu / Debian)

Des paquets pré-compilés pour ce module sont disponibles gratuitement dans le dépôt GetPageSpeed :

# Ajouter le dépôt (exemple Ubuntu - remplacez 'ubuntu' et 'jammy' selon votre distribution)
echo "deb [signed-by=/etc/apt/keyrings/getpagespeed.gpg] https://extras.getpagespeed.com/ubuntu jammy main" \
  | sudo tee /etc/apt/sources.list.d/getpagespeed-extras.list

# nginx.conf
load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;

http {
    server {
        auth_jwt_key "0123456789abcdef" hex; # Votre clé sous forme de chaîne hexadécimale
        auth_jwt     off;

        # La méthode d'authentification par défaut est l'en-tête "Authentication"
        location /secured-by-auth-header/ {
            auth_jwt on;
        }

        # Mais vous pouvez utiliser un cookie à la place
        location /secured-by-cookie/ {
            auth_jwt $cookie_MyCookieName;
        }

        # Les clés JWT sont héritées du niveau de configuration précédent
        # mais vous pouvez avoir des clés différentes pour différents emplacements
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # Votre clé sous forme de chaîne utf8
            auth_jwt on;
        }

        location /secured-by-rsa-key/ {
            auth_jwt_key /etc/keys/rsa-public.pem file; # Votre clé depuis un fichier PEM
            auth_jwt on;
        }

        location /not-secure/ {}
    }
}

Remarque : n'oubliez pas de charger le module dans le contexte principal :

load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;

Directives :

auth_jwt

Syntaxe : auth_jwt $variable | on | off;
Défaut : auth_jwt off;
Contexte : http, server, location

Active la validation du JWT.

La valeur auth_jwt $variable peut être utilisée pour définir une méthode personnalisée d'obtention du JWT, par exemple pour le récupérer depuis un cookie au lieu de l'en-tête Authentication par défaut : auth_jwt $cookie_MyCookieName;

auth_jwt_key

Syntaxe : auth_jwt_key value [encoding];
Défaut : ——
Contexte : http, server, location

Spécifie la clé pour valider la signature JWT (doit être hexadécimale).
L'option encoding peut être hex | utf8 | base64 | file (la valeur par défaut est utf8).
L'option file nécessite que la value soit un chemin de fichier valide (pointant vers une clé encodée en PEM).

auth_jwt_alg

Syntaxe : auth_jwt_alg any | HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | ES256 | ES384 | ES512;
Défaut : auth_jwt_alg any;
Contexte : http, server, location

Spécifie l'algorithme que le serveur s'attend à recevoir dans le JWT.

Les jetons signés avec un algorithme HMAC (HS256, HS384, HS512) sont toujours rejetés lorsque la clé est une clé PEM, quelle que soit la valeur de cette directive : une clé publique n'est pas un secret, donc n'importe qui pourrait sinon l'utiliser pour signer un jeton que le serveur accepterait. Il est néanmoins recommandé de fixer l'algorithme attendu.

auth_jwt_require

Syntaxe : auth_jwt_require $value ... [error=401 | 403];
Défaut : ——
Contexte : http, server, location

Spécifie des vérifications supplémentaires pour la validation JWT. L'authentification ne réussira que si toutes les valeurs ne sont pas vides et ne sont pas égales à « 0 ».

Ces directives sont héritées du niveau de configuration précédent si et seulement si aucune directive auth_jwt_require n'est définie au niveau actuel.

Si l'une des vérifications échoue, le code d'erreur 401 est renvoyé. Le paramètre optionnel error permet de redéfinir le code d'erreur à 403.

Exemple :

# server.conf

map $jwt_claim_role $jwt_has_admin_role {
    \"admin\"  1;
}

map $jwt_claim_scope $jwt_has_restricted_scope {
    \"restricted\"  1;
}

server {
  # ...

  location /auth-require {
    auth_jwt_require $jwt_has_admin_role error=403;
    # ...
  }

  location /auth-compound-require {
    auth_jwt_require $jwt_has_admin_role $jwt_has_restricted_scope error=403;
    # ...
  }
}

Notez que comme $jwt_claim_ renvoie une valeur encodée en JSON, nous devons vérifier \"value\" (et non value)

Variables intégrées :

Le module ngx_http_auth_jwt_module prend en charge les variables intégrées :

$jwtheadername renvoie la valeur d'en-tête spécifiée
$jwtclaimname renvoie la valeur de revendication spécifiée
$jwt_headers renvoie les en-têtes
$jwt_payload renvoie la charge utile

Notez que comme toutes les valeurs renvoyées sont encodées en JSON, les chaînes seront entourées du caractère "

Étendre votre image Docker :

Créez simplement votre image à partir de celle générée par Github

FROM ghcr.io/max-lt/nginx-jwt-module:latest

# Copiez votre configuration nginx
# N'oubliez pas d'inclure ce module dans votre configuration
# load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;
COPY my-nginx-conf /etc/nginx

EXPOSE 8000

STOPSIGNAL SIGTERM

CMD ["nginx", "-g", "daemon off;"]

Ou utilisez directement celle fournie

docker run -p 80:80 \
  -v ./nginx.conf:/etc/nginx/nginx.conf \
  ghcr.io/max-lt/nginx-jwt-module

ou

docker build -f Dockerfile -t jwt-nginx .

### Test :

#### Utilisation par défaut :

```bash
make test # Construira une image de test et exécutera la suite de tests

Exemples de configurations :

Dans cette section, nous verrons quelques exemples d'utilisation de ce module.

Redirection vers la page de connexion si le JWT est invalide :

load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;

# ...

http {
    server {
        listen 80;
        server_name _;

        auth_jwt_key "0123456789abcdef" hex; # Votre clé sous forme de chaîne hexadécimale
        auth_jwt     off;

        location @login_err_redirect {
            return 302 $scheme://$host:$server_port/login?redirect=$request_uri;
        }

        location /secure/ {
            auth_jwt on;
            error_page 401 = @login_err_redirect;
        }

        location / {
            return 200 "OK";
        }
    }
}

Essayer curl -i http://localhost/secure/path?param=value renverra une redirection 302 vers /login?redirect=/secure/path?param=value si le JWT est invalide.

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-jwt.