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.4.0, veröffentlicht am 17. September 2025.

Dies ist ein NGINX-Modul, um ein gültiges JWT zu überprüfen und an einen Upstream-Server weiterzuleiten oder auf eine Anmeldeseite umzuleiten. 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 in 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 auf `auth_jwt_loginurl` umzuleiten, wenn die Authentifizierung fehlschlägt.
`auth_jwt_loginurl`	Die URL, auf die umgeleitet 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 über z.B.: `$jwt_claim_sub` zugänglich.
`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 über z.B.: `$http_jwt_sub` zugänglich.
`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 über z.B.: `$sent_http_jwt_sub` zugänglich.
`auth_jwt_use_keyfile`	Auf "on" setzen, um den Schlüssel aus einer Datei anstelle der `auth_jwt_key`-Direktive zu lesen.
`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 symmetrischem Schlüssel. 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, anstelle eines PEM-Zertifikats. Zum Beispiel:

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, gehen Sie wie folgt vor:

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

Ein typischer Anwendungsfall wäre, den Schlüssel und die Anmeldeseite 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 Querystring-Parameter return_url, dessen Wert die aktuelle / versuchte URL ist.

Wenn Sie lieber 401 Unauthorized zurückgeben möchten, anstatt umzuleiten, können Sie auth_jwt_redirect ausschalten:

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;  # Holen Sie das JWT aus dem "auth-token" Header
auth_jwt_location COOKIE=auth-token;  # Holen Sie das JWT aus dem "auth-token" Cookie

`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 ausgegeben, wenn Sie versuchen, einen Nicht-String-Anspruch zu extrahieren.

Verwendung von Ansprüchen

Zum Beispiel könnten Sie einen NGINX-Standort konfigurieren, der auf das Profil des aktuellen Benutzers umleitet. Angenommen, sub=abc-123, würde die folgende Konfiguration auf /profile/abc-123 umleiten.

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, mit den einzigen Unterschieden: - 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;

Klonen von `libjwt`

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

Klonen von `libjansson`

Klonen Sie dieses Repository wie folgt (ersetzen Sie <target_dir>): git clone [email protected]:akheron/jansson.git <target_dir>
Wechseln Sie in das Verzeichnis und wechseln Sie zum neuesten Tag: git checkout $(git tag | sort -Vr | head -n 1)
Aktualisieren Sie die includePath-Einträge, die oben gezeigt 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 gesetzt sind.

Für Linux-Systeme mit systemd (optional)

export LOG_DRIVER=journald

Für andere Systeme oder wenn Sie dateibasierte Protokolle bevorzugen (Standard)

export LOG_DRIVER=json-file

Testbilder neu erstellen

./scripts rebuild_test

Tests ausführen

./scripts test

Protokolle ü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 Protokolle 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 Protokolle verfolgen:

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

## Terminal 2 - wählen Sie je nach 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 zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-teslagov-jwt.