teslagov-jwt: Sécurisez vos emplacements NGINX avec JWT

Installation

Vous pouvez installer ce module dans 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-teslagov-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-teslagov-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-teslagov-jwt v2.4.0 publié le 17 septembre 2025.

Il s'agit d'un module NGINX pour vérifier un JWT valide et proxy vers un serveur en amont ou rediriger vers une page de connexion. Il prend en charge des fonctionnalités supplémentaires telles que l'extraction des revendications du JWT et leur placement dans les en-têtes de requête/réponse.

Changements majeurs avec v2

La branche v2, qui a maintenant été fusionnée dans master, comprend des changements majeurs. Veuillez consulter la publication initiale de v2 pour plus de détails.

Directives

Ce module nécessite plusieurs nouvelles directives nginx.conf, qui peuvent être spécifiées aux niveaux http, server ou location. Voir le fichier de configuration NGINX exemple pour plus d'informations.

Directive	Description
`auth_jwt_key`	La clé à utiliser pour décoder/vérifier le JWT, au format binhex -- voir ci-dessous.
`auth_jwt_redirect`	Défini sur "on" pour rediriger vers `auth_jwt_loginurl` si l'authentification échoue.
`auth_jwt_loginurl`	L'URL vers laquelle rediriger si `auth_jwt_redirect` est activé et que l'authentification échoue.
`auth_jwt_enabled`	Défini sur "on" pour activer la vérification du JWT.
`auth_jwt_algorithm`	L'algorithme à utiliser. Un des suivants : HS256, HS384, HS512, RS256, RS384, RS512
`auth_jwt_location`	Indique où le JWT est situé dans la requête -- voir ci-dessous.
`auth_jwt_validate_sub`	Défini sur "on" pour valider la revendication `sub` (par exemple, l'identifiant de l'utilisateur) dans le JWT.
`auth_jwt_extract_var_claims`	Défini sur une liste de revendications séparées par des espaces à extraire du JWT et à rendre disponibles en tant que variables NGINX. Celles-ci seront accessibles via par exemple : `$jwt_claim_sub`
`auth_jwt_extract_request_claims`	Défini sur une liste de revendications séparées par des espaces à extraire du JWT et à définir en tant qu'en-têtes de requête. Celles-ci seront accessibles via par exemple : `$http_jwt_sub`
`auth_jwt_extract_response_claims`	Défini sur une liste de revendications séparées par des espaces à extraire du JWT et à définir en tant qu'en-têtes de réponse. Celles-ci seront accessibles via par exemple : `$sent_http_jwt_sub`
`auth_jwt_use_keyfile`	Défini sur "on" pour lire la clé à partir d'un fichier plutôt qu'à partir de la directive `auth_jwt_key`.
`auth_jwt_keyfile_path`	Défini sur le chemin à partir duquel la clé doit être lue lorsque `auth_jwt_use_keyfile` est activé.

Algorithmes

L'algorithme par défaut est HS256, pour la validation de clé symétrique. Lors de l'utilisation de l'un des algorithmes HS*, la valeur pour auth_jwt_key doit être spécifiée au format binhex. Il est recommandé d'utiliser au moins 256 bits de données (32 paires de caractères hexadécimaux ou 64 caractères au total). Notez que l'utilisation de plus de 512 bits n'augmentera pas la sécurité. Pour des directives sur les clés, veuillez consulter NIST Special Publication 800-107 Recommendation for Applications Using Approved Hash Algorithms, Section 5.3.2 La clé HMAC.

Pour générer une clé de 256 bits (32 paires de caractères hexadécimaux ; 64 caractères au total) :

openssl rand -hex 32

Algorithmes supplémentaires pris en charge

La configuration prend également en charge la validation de clé publique RSA via (par exemple) auth_jwt_algorithm RS256. Lors de l'utilisation des algorithmes RS*, le champ auth_jwt_key doit être défini sur votre clé publique OU auth_jwt_use_keyfile doit être défini sur on et auth_jwt_keyfile_path doit pointer vers la clé publique sur le disque. NGINX ne démarrera pas si auth_jwt_use_keyfile est défini sur on et qu'un fichier de clé n'est pas fourni.

Lors de l'utilisation d'un algorithme RS* avec une clé en ligne, assurez-vous de définir auth_jwt_key sur la clé publique, plutôt que sur un certificat PEM. Par exemple :

auth_jwt_key "-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0aPPpS7ufs0bGbW9+OFQ
RvJwb58fhi2BuHMd7Ys6m8D1jHW/AhDYrYVZtUnA60lxwSJ/ZKreYOQMlNyZfdqA
rhYyyUkedDn8e0WsDvH+ocY0cMcxCCN5jItCwhIbIkTO6WEGrDgWTY57UfWDqbMZ
4lMn42f77OKFoxsOA6CVvpsvrprBPIRPa25H2bJHODHEtDr/H519Y681/eCyeQE/
1ibKL2cMN49O7nRAAaUNoFcO89Uc+GKofcad1TTwtTIwmSMbCLVkzGeExBCrBTQo
wO6AxLijfWV/JnVxNMUiobiKGc/PP6T5PI70Uv67Y4FzzWTuhqmREb3/BlcbPwtM
oQIDAQAB
-----END PUBLIC KEY-----";

Lors de l'utilisation d'un algorithme RS* avec un fichier de clé publique, procédez comme suit :

auth_jwt_use_keyfile on;
auth_jwt_keyfile_path "/path/to/pub_key.pem";

Un cas d'utilisation typique consisterait à spécifier la clé et l'URL de connexion au niveau http, puis à activer l'authentification JWT uniquement pour les emplacements que vous souhaitez sécuriser (ou vice-versa). Les requêtes non autorisées entraîneront une réponse 302 Moved Temporarily avec l'en-tête Location défini sur l'URL spécifiée dans la directive auth_jwt_loginurl, et un paramètre de chaîne de requête return_url dont la valeur est l'URL actuelle / tentée.

Si vous préférez renvoyer 401 Unauthorized plutôt que de rediriger, vous pouvez désactiver auth_jwt_redirect :

auth_jwt_redirect off;

Emplacements JWT

Par défaut, l'en-tête Authorization est utilisé pour fournir un JWT pour validation. Cependant, vous pouvez utiliser la directive auth_jwt_location pour spécifier le nom de l'en-tête ou du cookie qui fournit le JWT :

auth_jwt_location HEADER=auth-token;  # obtenir le JWT depuis l'en-tête "auth-token"
auth_jwt_location COOKIE=auth-token;  # obtenir le JWT depuis le cookie "auth-token"

Validation `sub`

En option, le module peut valider qu'une revendication sub (par exemple, l'identifiant de l'utilisateur) existe dans le JWT. Vous pouvez activer cette fonctionnalité comme suit :

auth_jwt_validate_sub on;

Extraction des revendications du JWT

Vous pouvez spécifier des revendications à extraire du JWT et à placer dans les en-têtes de requête et/ou de réponse. Cela est particulièrement utile car les revendications seront alors également disponibles en tant que variables NGINX.

Si vous souhaitez uniquement accéder à une revendication en tant que variable NGINX, vous devez utiliser auth_jwt_extract_var_claims afin que la revendication ne soit pas envoyée au client en tant qu'en-tête de réponse. Cependant, si vous souhaitez que la revendication soit envoyée au client dans la réponse, vous pouvez utiliser auth_jwt_extract_response_claims à la place.

Veuillez noter que les revendications number, boolean, array et object ne sont pas prises en charge pour le moment -- seules les revendications string sont prises en charge. Une erreur sera générée si vous tentez d'extraire une revendication non-string.

Utilisation des revendications

Par exemple, vous pourriez configurer un emplacement NGINX qui redirige vers le profil de l'utilisateur actuel. Supposons que sub=abc-123, la configuration ci-dessous redirigerait vers /profile/abc-123.

location /profile/me {
    auth_jwt_extract_var_claims sub;

    return 301 /profile/$jwt_claim_sub;
}

Utilisation des revendications de réponse

Les revendications de réponse sont utilisées de la même manière, avec les seules différences suivantes : - les variables sont accessibles via le motif $sent_http_jwt_*, par exemple $sent_http_jwt_sub, et - les en-têtes sont envoyés au client.

Extraction de plusieurs revendications

Vous pouvez extraire plusieurs revendications en spécifiant toutes les revendications comme arguments à une seule directive, ou en fournissant plusieurs directives. Les deux exemples suivants sont équivalents.

auth_jwt_extract_request_claims sub firstName lastName;

auth_jwt_extract_request_claims sub;
auth_jwt_extract_request_claims firstName;
auth_jwt_extract_request_claims lastName;

Clonage de `libjwt`

Clonez ce dépôt comme suit (remplacez <target_dir>): git clone [email protected]:benmcollins/libjwt.git <target_dir>
Entrez dans le répertoire et passez à la dernière balise : git checkout $(git tag | sort -Vr | head -n 1)
Mettez à jour les entrées includePath montrées ci-dessus pour correspondre à l'emplacement que vous avez choisi.

Clonage de `libjansson`

Clonez ce dépôt comme suit (remplacez <target_dir>): git clone [email protected]:akheron/jansson.git <target_dir>
Entrez dans le répertoire et passez à la dernière balise : git checkout $(git tag | sort -Vr | head -n 1)
Mettez à jour les entrées includePath montrées ci-dessus pour correspondre à l'emplacement que vous avez choisi.

Vérification de la compilation

Une fois que vous avez enregistré vos modifications dans .vscode/c_cpp_properties.json, vous devriez voir que les avertissements et les erreurs dans le panneau Problèmes disparaissent, du moins temporairement. Espérons qu'ils ne reviennent pas, mais s'ils le font, assurez-vous que vos chemins d'inclusion sont correctement définis.

Pour les systèmes Linux avec systemd (optionnel)

export LOG_DRIVER=journald

Pour les autres systèmes ou si vous préférez des journaux basés sur des fichiers (par défaut)

export LOG_DRIVER=json-file

reconstruire les images de test

./scripts rebuild_test

exécuter les tests

./scripts test

vérifier les journaux -- ajustez le nom du conteneur si nécessaire

Pour journald (systèmes Linux) :

journalctl -eu docker CONTAINER_NAME=nginx-auth-jwt-test-nginx

Pour le pilote json-file (tous les systèmes) :

docker logs nginx-auth-jwt-test-nginx

Vous pourrez maintenant voir les journaux des exécutions de test précédentes. Le meilleur moyen d'en profiter est d'ouvrir deux terminaux, l'un où vous exécutez les tests, et l'autre où vous suivez les journaux :

```shell
## terminal 1
./scripts test

## terminal 2 - choisissez en fonction de votre paramètre LOG_DRIVER :

## Pour journald :
journalctl -fu docker CONTAINER_NAME=jwt-nginx-test

## Pour json-file (par défaut) :
docker logs -f nginx-auth-jwt-test-nginx

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-teslagov-jwt.