Zum Inhalt

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
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 an den 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.4 veröffentlicht am 03. Februar 2026.

Nginx jwt auth Modul

License

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

Schnellstart:

Docker-Image:

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

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

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

# 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 hexadezimale Zeichenfolge
        auth_jwt     off;

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

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

        # JWT-Schlüssel werden vom vorherigen Konfigurationslevel geerbt
        # aber Sie können unterschiedliche Schlüssel für verschiedene Standorte haben
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # Ihr Schlüssel als utf8-Zeichenfolge
            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 anstelle des Standard-Authentication-Headers abzurufen: 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 encoding-Option kann hex | utf8 | base64 | file sein (Standard ist utf8).
Die file-Option 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 erwartet, um ihn im JWT zu erhalten.

auth_jwt_require

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

Gibt zusätzliche Überprüfungen für die JWT-Validierung an. Die Authentifizierung wird nur erfolgreich sein, wenn alle Werte nicht leer sind und nicht gleich "0".

Diese Direktiven werden vom vorherigen Konfigurationslevel geerbt, wenn und nur wenn auf der aktuellen Ebene keine auth_jwt_require-Direktiven definiert sind.

Wenn eine der Überprüfungen fehlschlägt, wird der Fehlercode 401 zurückgegeben. Der optionale Fehlerparameter ermöglicht es, den Fehlercode auf 403 neu zu definieren.

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, sodass wir \"value\" (und nicht value) überprüfen müssen.

Eingebettete Variablen:

Das ngx_http_auth_jwt_module-Modul unterstützt eingebettete Variablen:

  • $jwtheadername gibt den angegebenen Headerwert zurück
  • $jwtclaimname gibt den angegebenen Anspruchswert zurück
  • $jwt_headers gibt Header zurück
  • $jwt_payload gibt Payload zurück

Beachten Sie, dass alle zurückgegebenen Werte JSON-kodiert sind, sodass Zeichenfolgen von dem "-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 Ihrer Konfiguration einzuschließen
# 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:

#### Standardnutzung:

```bash
make test # Wird ein Test-Image erstellen und die Test-Suite ausführen

Beispielkonfigurationen:

In diesem Abschnitt werden einige Beispiele gezeigt, wie Sie dieses Modul verwenden können.

Umleitung zur Anmeldeseite, wenn JWT ungültig ist:

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 hexadezimale Zeichenfolge
        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";
        }
    }
}

Ein Versuch von curl -i http://localhost/secure/path?param=value wird eine 302-Umleitung zu /login?redirect=/secure/path?param=value zurückgeben, wenn das JWT ungültig ist.

GitHub

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