Aller au contenu

jwt: Module JWT NGINX

Installation

Vous pouvez installer ce module dans n'importe quelle 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
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 ce qui suit 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.4 publié le 3 février 2026.

Module d'authentification jwt Nginx

License

Ceci est un module NGINX pour vérifier un JWT valide, ce module vise à être aussi léger que possible et à rester simple :

Démarrage rapide :

Image Docker :

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

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

Paquets préconstruits (Ubuntu / Debian)

Des paquets préconstruits pour ce module sont disponibles gratuitement depuis le dépôt GetPageSpeed :

# Ajoutez le dépôt (exemple Ubuntu - remplacez 'ubuntu' et 'jammy' par 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é en 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érentes localisations
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # Votre clé en 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;
Par défaut : auth_jwt off;
Contexte : http, serveur, localisation

Active la validation du JWT.

La valeur auth_jwt $variable peut être utilisée pour définir une manière personnalisée d'obtenir le JWT, par exemple pour l'obtenir à partir d'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];
Par défaut : ——
Contexte : http, serveur, localisation

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;
Par défaut : auth_jwt_alg any;
Contexte : http, serveur, localisation

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

auth_jwt_require

Syntaxe :    auth_jwt_require $value ... [error=401 | 403];
Par défaut : ——
Contexte : http, serveur, localisation

Spécifie des vérifications supplémentaires pour la validation du JWT. L'authentification réussira uniquement 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 uniquement s'il n'y a pas de directives auth_jwt_require définies au niveau actuel.

Si l'une des vérifications échoue, le code d'erreur 401 est renvoyé. Le paramètre d'erreur optionnel 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 de l'en-tête spécifié
  • $jwtclaimname renvoie la valeur de la 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 par le 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 # Va construire une image de test et exécuter la suite de tests

Exemples de configurations :

Dans cette section, nous allons voir quelques exemples de la façon d'utiliser ce module.

Rediriger 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é en 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.