teslagov-jwt: Sichern Sie Ihre NGINX-Standorte mit JWT

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-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

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

load_module modules/ngx_http_auth_jwt_module.so;

Dieses Dokument beschreibt nginx-module-teslagov-jwt v2.5.0 veröffentlicht am 11. Juni 2026.

Dies ist ein NGINX-Modul zur Überprüfung eines gültigen JWT und zum Proxy zu einem Upstream-Server oder zur Weiterleitung zu einer Anmeldeseite. Es unterstützt zusätzliche Funktionen wie das Extrahieren von Ansprüchen aus dem JWT und das Platzieren dieser in den Anfrage-/Antwort-Headern.

Breaking Changes mit v2

Der v2-Zweig, der jetzt mit master zusammengeführt wurde, enthält breaking changes. Bitte sehen Sie sich die ursprüngliche v2-Version für Details an.

Direktiven

Dieses Modul erfordert mehrere neue nginx.conf-Direktiven, die auf den Ebenen http, server oder location angegeben werden können. Siehe die Beispiel-NGINX-Konfigurationsdatei für weitere Informationen.

Direktive	Beschreibung
`auth_jwt_key`	Der Schlüssel, der zum Dekodieren/Überprüfen des JWT verwendet wird, im Binhex-Format -- siehe unten.
`auth_jwt_redirect`	Auf "on" setzen, um zu `auth_jwt_loginurl` weiterzuleiten, wenn die Authentifizierung fehlschlägt.
`auth_jwt_loginurl`	Die URL, zu der weitergeleitet werden soll, wenn `auth_jwt_redirect` aktiviert ist und die Authentifizierung fehlschlägt.
`auth_jwt_enabled`	Auf "on" setzen, um die JWT-Überprüfung zu aktivieren.
`auth_jwt_algorithm`	Der zu verwendende Algorithmus. Einer von: HS256, HS384, HS512, RS256, RS384, RS512
`auth_jwt_location`	Gibt an, wo sich das JWT in der Anfrage befindet -- siehe unten.
`auth_jwt_validate_sub`	Auf "on" setzen, um den `sub`-Anspruch (z.B. Benutzer-ID) im JWT zu validieren.
`auth_jwt_extract_var_claims`	Auf eine durch Leerzeichen getrennte Liste von Ansprüchen setzen, die aus dem JWT extrahiert und als NGINX-Variablen verfügbar gemacht werden sollen. Diese sind zugänglich über z.B.: `$jwt_claim_sub`
`auth_jwt_extract_request_claims`	Auf eine durch Leerzeichen getrennte Liste von Ansprüchen setzen, die aus dem JWT extrahiert und als Anfrage-Header gesetzt werden sollen. Diese sind zugänglich über z.B.: `$http_jwt_sub`
`auth_jwt_extract_response_claims`	Auf eine durch Leerzeichen getrennte Liste von Ansprüchen setzen, die aus dem JWT extrahiert und als Antwort-Header gesetzt werden sollen. Diese sind zugänglich über z.B.: `$sent_http_jwt_sub`
`auth_jwt_use_keyfile`	Auf "on" setzen, um den Schlüssel aus einer Datei zu lesen, anstatt aus der `auth_jwt_key`-Direktive.
`auth_jwt_keyfile_path`	Auf den Pfad setzen, von dem der Schlüssel gelesen werden soll, wenn `auth_jwt_use_keyfile` aktiviert ist.

Algorithmen

Der Standardalgorithmus ist HS256 für die Validierung mit symmetrischen Schlüsseln. Bei Verwendung eines der HS*-Algorithmen sollte der Wert für auth_jwt_key im Binhex-Format angegeben werden. Es wird empfohlen, mindestens 256 Bit Daten (32 Paare von Hex-Zeichen oder insgesamt 64 Zeichen) zu verwenden. Beachten Sie, dass die Verwendung von mehr als 512 Bit die Sicherheit nicht erhöht. Für Richtlinien zu Schlüsseln siehe NIST Special Publication 800-107 Recommendation for Applications Using Approved Hash Algorithms, Abschnitt 5.3.2 Der HMAC-Schlüssel.

Um einen 256-Bit-Schlüssel (32 Paare von Hex-Zeichen; insgesamt 64 Zeichen) zu generieren:

openssl rand -hex 32

Zusätzliche unterstützte Algorithmen

Die Konfiguration unterstützt auch die Validierung von RSA-Öffentlichen Schlüsseln über (z.B.) auth_jwt_algorithm RS256. Bei Verwendung der RS*-Algorithmen muss das Feld auth_jwt_key auf Ihren öffentlichen Schlüssel ODER auth_jwt_use_keyfile auf on gesetzt werden, und auth_jwt_keyfile_path sollte auf den öffentlichen Schlüssel auf der Festplatte verweisen. NGINX startet nicht, wenn auth_jwt_use_keyfile auf on gesetzt ist und keine Schlüsseldatei bereitgestellt wird.

Bei Verwendung eines RS*-Algorithmus mit einem Inline-Schlüssel stellen Sie sicher, dass auth_jwt_key auf den öffentlichen Schlüssel gesetzt ist, anstatt auf ein PEM-Zertifikat. Z.B.:

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-----";

Bei Verwendung eines RS*-Algorithmus mit einer öffentlichen Schlüsseldatei, verfahren Sie wie folgt:

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

Ein typischer Anwendungsfall wäre, den Schlüssel und die Anmeldungs-URL auf der http-Ebene anzugeben und dann die JWT-Authentifizierung nur für die Standorte zu aktivieren, die Sie sichern möchten (oder umgekehrt). Unautorisierte Anfragen führen zu einer 302 Moved Temporarily-Antwort mit dem Location-Header, der auf die in der auth_jwt_loginurl-Direktive angegebene URL gesetzt ist, und einem Abfrageparameter return_url, dessen Wert die aktuelle / versuchte URL ist.

Wenn Sie lieber 401 Unauthorized anstelle einer Weiterleitung zurückgeben möchten, können Sie auth_jwt_redirect deaktivieren:

auth_jwt_redirect off;

JWT-Standorte

Standardmäßig wird der Authorization-Header verwendet, um ein JWT zur Validierung bereitzustellen. Sie können jedoch die auth_jwt_location-Direktive verwenden, um den Namen des Headers oder Cookies anzugeben, der das JWT bereitstellt:

auth_jwt_location HEADER=auth-token;  # das JWT aus dem "auth-token"-Header abrufen
auth_jwt_location COOKIE=auth-token;  # das JWT aus dem "auth-token"-Cookie abrufen

`sub`-Validierung

Optional kann das Modul validieren, dass ein sub-Anspruch (z.B. die Benutzer-ID) im JWT vorhanden ist. Sie können diese Funktion wie folgt aktivieren:

auth_jwt_validate_sub on;

Ansprüche aus dem JWT extrahieren

Sie können Ansprüche angeben, die aus dem JWT extrahiert und in den Anfrage- und/oder Antwort-Headern platziert werden sollen. Dies ist besonders praktisch, da die Ansprüche dann auch als NGINX-Variablen verfügbar sind.

Wenn Sie einen Anspruch nur als NGINX-Variable zugänglich machen möchten, sollten Sie auth_jwt_extract_var_claims verwenden, damit der Anspruch nicht als Antwort-Header an den Client gesendet wird. Wenn Sie jedoch möchten, dass der Anspruch an den Client in der Antwort gesendet wird, können Sie stattdessen auth_jwt_extract_response_claims verwenden.

Bitte beachten Sie, dass number, boolean, array und object-Ansprüche derzeit nicht unterstützt werden -- nur string-Ansprüche werden unterstützt. Ein Fehler wird ausgelöst, wenn Sie versuchen, einen Nicht-String-Anspruch zu extrahieren.

Verwendung von Ansprüchen

Zum Beispiel könnten Sie einen NGINX-Standort konfigurieren, der zu dem Profil des aktuellen Benutzers weiterleitet. Angenommen, sub=abc-123, würde die folgende Konfiguration zu /profile/abc-123 weiterleiten.

location /profile/me {
    auth_jwt_extract_var_claims sub;

    return 301 /profile/$jwt_claim_sub;
}

Verwendung von Antwortansprüchen

Antwortansprüche werden auf die gleiche Weise verwendet, wobei die einzigen Unterschiede sind: - die Variablen werden über das Muster $sent_http_jwt_* zugegriffen, z.B. $sent_http_jwt_sub, und - die Header werden an den Client gesendet.

Mehrere Ansprüche extrahieren

Sie können mehrere Ansprüche extrahieren, indem Sie alle Ansprüche als Argumente zu einer einzelnen Direktive angeben oder mehrere Direktiven bereitstellen. Die folgenden beiden Beispiele sind gleichwertig.

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;

Vorgefertigte Pakete (Ubuntu / Debian)

Vorgefertigte Pakete für dieses Modul sind kostenlos im GetPageSpeed-Repository verfügbar:

# Fügen Sie das Repository hinzu (Ubuntu-Beispiel - ersetzen Sie 'ubuntu' und 'jammy' durch 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

#### Klonen von `libjwt`

1. Klonen Sie dieses Repository wie folgt (ersetzen Sie `<target_dir>`): `git clone [email protected]:benmcollins/libjwt.git <target_dir>`
2. Wechseln Sie in das Verzeichnis und wechseln Sie zum neuesten Tag: `git checkout $(git tag | sort -Vr | head -n 1)`
3. Aktualisieren Sie die `includePath`-Einträge, die oben angezeigt werden, um mit dem von Ihnen gewählten Speicherort übereinzustimmen.

#### Klonen von `libjansson`

1. Klonen Sie dieses Repository wie folgt (ersetzen Sie `<target_dir>`): `git clone [email protected]:akheron/jansson.git <target_dir>`
2. Wechseln Sie in das Verzeichnis und wechseln Sie zum neuesten Tag: `git checkout $(git tag | sort -Vr | head -n 1)`
3. Aktualisieren Sie die `includePath`-Einträge, die oben angezeigt werden, um mit dem von Ihnen gewählten Speicherort übereinzustimmen.

#### Überprüfen der Kompilierung

Sobald Sie Ihre Änderungen an `.vscode/c_cpp_properties.json` gespeichert haben, sollten Sie sehen, dass Warnungen und Fehler im Problems-Panel verschwinden, zumindest vorübergehend. Hoffentlich kommen sie nicht zurück, aber wenn doch, stellen Sie sicher, dass Ihre Include-Pfade korrekt eingestellt sind.

# Für Linux-Systeme mit systemd (optional)
export LOG_DRIVER=journald

# Für andere Systeme oder wenn Sie dateibasierten Logs (Standard) bevorzugen
export LOG_DRIVER=json-file

# Testbilder neu erstellen
./scripts rebuild_test

# Tests ausführen
./scripts test

# Logs überprüfen -- passen Sie den Containernamen nach Bedarf an
# Für journald (Linux-Systeme):
journalctl -eu docker CONTAINER_NAME=nginx-auth-jwt-test-nginx

# Für json-file-Treiber (alle Systeme):
docker logs nginx-auth-jwt-test-nginx

Jetzt können Sie Logs von vorherigen Testläufen sehen. Der beste Weg, dies zu nutzen, besteht darin, zwei Terminals zu öffnen, eines, in dem Sie die Tests ausführen, und eines, in dem Sie die Logs verfolgen:

# Terminal 1
./scripts test

# Terminal 2 - wählen Sie basierend auf Ihrer LOG_DRIVER-Einstellung:

# Für journald:
journalctl -fu docker CONTAINER_NAME=jwt-nginx-test

# Für json-file (Standard):
docker logs -f nginx-auth-jwt-test-nginx

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-teslagov-jwt.