jwt: NGINX JWT-Modul

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 und 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

Aktivieren Sie das Modul, indem Sie Folgendes am Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_auth_jwt_module.so;

Dieses Dokument beschreibt nginx-module-jwt v3.4.6, veröffentlicht am 01. August 2026.

Nginx JWT-Authentifizierungsmodul

Dies ist ein NGINX-Modul zur Überprüfung eines gültigen JWT. Dieses Modul soll so leichtgewichtig wie möglich sein und einfach bleiben:

Docker-Image basierend auf dem offiziellen nginx Dockerfile (alpine).
Leichtes Image (~400KB mehr als das offizielle).

Schnellstart:

Docker-Image:

Das Image wird mit Github Actions erstellt (siehe nginx-jwt-module:latest)

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

Eine leichtere Variante basierend auf nginx:alpine-slim (ohne die zusätzlichen nginx-Dynamikmodule wie njs, image-filter, xslt oder geoip) ist ebenfalls verfügbar:

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

Vorgefertigte Pakete (Ubuntu / Debian)

Vorgefertigte Pakete für dieses Modul sind kostenlos aus dem GetPageSpeed-Repository erhältlich:

# Repository hinzufügen (Ubuntu-Beispiel - ersetzen Sie 'ubuntu' und 'jammy' für Ihre 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; # Ihr Schlüssel als Hex-String
        auth_jwt     off;

        # Standard-Authentifizierungsmethode ist der "Authentication"-Header
        location /secured-by-auth-header/ {
            auth_jwt on;
        }

        # Sie können stattdessen aber auch ein Cookie verwenden
        location /secured-by-cookie/ {
            auth_jwt $cookie_MyCookieName;
        }

        # JWT-Schlüssel werden von der vorherigen Konfigurationsebene geerbt,
        # aber Sie können für verschiedene Locations unterschiedliche Schlüssel haben
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # Ihr Schlüssel als UTF-8-String
            auth_jwt on;
        }

        location /secured-by-rsa-key/ {
            auth_jwt_key /etc/keys/rsa-public.pem file; # Ihr Schlüssel aus einer PEM-Datei
            auth_jwt on;
        }

        location /not-secure/ {}
    }
}

Hinweis: Vergessen Sie nicht, das Modul im Hauptkontext zu laden:

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

Direktiven:

auth_jwt

Syntax:  auth_jwt $variable | on | off;
Standard: auth_jwt off;
Kontext: http, server, location

Aktiviert die Validierung von JWT.

Der Wert auth_jwt $variable kann verwendet werden, um eine benutzerdefinierte Methode zum Abrufen des JWT festzulegen, z. B. um es aus einem Cookie statt aus dem standardmäßigen Authentication-Header zu erhalten: auth_jwt $cookie_MyCookieName;

auth_jwt_key

Syntax:  auth_jwt_key value [encoding];
Standard: ——
Kontext: http, server, location

Gibt den Schlüssel zur Validierung der JWT-Signatur an (muss hexadezimal sein).
Die Option encoding kann hex | utf8 | base64 | file sein (Standard ist utf8).
Die Option file erfordert, dass der value ein gültiger Dateipfad ist (der auf einen PEM-kodierten Schlüssel verweist).

auth_jwt_alg

Syntax:  auth_jwt_alg any | HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | ES256 | ES384 | ES512;
Standard: auth_jwt_alg any;
Kontext: http, server, location

Gibt an, welchen Algorithmus der Server im JWT erwartet.

Token, die mit einem HMAC-Algorithmus (HS256, HS384, HS512) signiert sind, werden immer abgelehnt, wenn der Schlüssel ein PEM-Schlüssel ist, unabhängig davon, was diese Direktive festlegt: Ein öffentlicher Schlüssel ist kein Geheimnis, sodass jeder ihn sonst verwenden könnte, um ein Token zu signieren, das der Server akzeptieren würde. Das Festlegen des erwarteten Algorithmus wird dennoch empfohlen.

auth_jwt_require

Syntax:  auth_jwt_require $value ... [error=401 | 403];
Standard: ——
Kontext: http, server, location

Gibt zusätzliche Prüfungen für die JWT-Validierung an. Die Authentifizierung ist nur dann erfolgreich, wenn alle Werte nicht leer und nicht gleich „0“ sind.

Diese Direktiven werden von der vorherigen Konfigurationsebene nur dann geerbt, wenn auf der aktuellen Ebene keine auth_jwt_require-Direktiven definiert sind.

Wenn eine der Prüfungen fehlschlägt, wird der Fehlercode 401 zurückgegeben. Die optionale Fehlerparameter ermöglicht die Neudefinition des Fehlercodes auf 403.

Beispiel:

# 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;
    # ...
  }
}

Beachten Sie, dass $jwt_claim_ einen JSON-kodierten Wert zurückgibt, daher müssen wir \"value\" (und nicht value) prüfen.

Eingebettete Variablen:

Das ngx_http_auth_jwt_module-Modul unterstützt eingebettete Variablen:

$jwtheadername gibt den angegebenen Header-Wert zurück
$jwtclaimname gibt den angegebenen Claim-Wert zurück
$jwt_headers gibt die Header zurück
$jwt_payload gibt die Payload zurück

Beachten Sie, dass alle zurückgegebenen Werte JSON-kodiert sind, sodass Zeichenfolgen von "-Zeichen umgeben sind.

Erweitern Sie Ihr Docker-Image:

Erstellen Sie einfach Ihr Image aus dem von Github generierten

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

# Kopieren Sie Ihre nginx-Konfiguration
# Vergessen Sie nicht, dieses Modul in Ihre Konfiguration aufzunehmen
# 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;"]

Oder verwenden Sie das bereitgestellte direkt

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

oder

docker build -f Dockerfile -t jwt-nginx .

### Test:

#### Standardverwendung:

```bash
make test # Erstellt ein Test-Image und führt die Testsuite aus

Beispielkonfigurationen:

In diesem Abschnitt sehen wir einige Beispiele für die Verwendung dieses Moduls.

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

# ...

http {
    server {
        listen 80;
        server_name _;

        auth_jwt_key "0123456789abcdef" hex; # Ihr Schlüssel als Hex-String
        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";
        }
    }
}

Der Versuch curl -i http://localhost/secure/path?param=value gibt eine 302-Weiterleitung zu /login?redirect=/secure/path?param=value zurück, wenn das JWT ungültig ist.

GitHub

Weitere Konfigurationstipps und Dokumentationen für dieses Modul finden Sie im GitHub-Repository für nginx-module-jwt.