auth-totp: Zeitbasierte Einmalpasswort (TOTP) Authentifizierung für NGINX

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

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

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

load_module modules/ngx_http_auth_totp_module.so;

Dieses Dokument beschreibt nginx-module-auth-totp v1.2.0 veröffentlicht am 04. Mai 2026.

Zeitbasierte Einmalpasswort (TOTP) Authentifizierung für NGINX

Der Zeitbasierte Einmalpasswort (TOTP) Algorithmus bietet einen sicheren Mechanismus für kurzlebige Einmalpasswortwerte, die für verbesserte Sicherheit wünschenswert sind. Dieser Algorithmus kann in einer Vielzahl von Netzwerk-Anwendungen eingesetzt werden, die von Remote Virtual Private Network (VPN) Zugriff, WLAN-Netzwerkanmeldung bis hin zu transaktionsorientierten Webanwendungen reichen.

Das nginx-http-auth-totp Modul bietet TOTP-Authentifizierung für einen NGINX-Server.

Funktionen

HTTP-Basisauthentifizierung mit zeitbasiertem Einmalpasswort (TOTP)
Cookie-basiertes Tracking von authentifizierten Clients über das TOTP-Gültigkeitsfenster hinaus
Konfigurierbares Geheimnis, Zeitreferenz, Zeitintervall und Truncationslänge für die TOTP-Generierung
Konfigurierbare Zeitverschiebung für die TOTP-Validierung

Pakete

Für Benutzer, die vorgefertigte und optimierte Pakete bevorzugen, kann das nginx-http-auth-totp Modul aus dem GetPageSpeed Repository installiert werden:

dnf -y install https://extras.getpagespeed.com/release-latest.rpm 
dnf -y install nginx-module-auth-totp

Konfiguration

server {
    listen 80;

    location /protected {
        auth_totp_realm "Protected";
        auth_totp_secret "Secret";
        auth_totp_file /etc/nginx/totp.conf;
        auth_totp_length 8;
        auth_totp_reuse off;
        auth_totp_skew 1;
        auth_totp_step 1m;
        auth_totp_cookie "totp-session";
        auth_totp_expiry 1d;
    }
}

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

load_module modules/ngx_http_auth_totp_module.so;

Direktiven

auth_totp_cookie

syntax: auth_totp_cookie <name>
default: totp
context: http, server, location, limit_except

Gibt den Namen des HTTP-Cookies an, das für das Tracking authentifizierter Clients verwendet werden soll.

Da die Gültigkeit des für die Authentifizierung verwendeten Zeitbasierten Einmalpassworts (TOTP) abläuft (von Haus aus), wird nach erfolgreicher Authentifizierung ein HTTP-Cookie gesetzt, um die Client-Authentifizierung über das TOTP-Gültigkeitsfenster hinaus aufrechtzuerhalten. Diese Konfigurationsdirektive legt den Namen fest, der beim Setzen dieses Cookies verwendet werden soll, während der Ablaufzeitraum für dieses Cookie mit der Direktive auth_totp_expiry festgelegt werden kann.

auth_totp_expiry

syntax: auth_totp_expiry <interval>
default: 0s
context: http, server, location, limit_except

Gibt die Ablaufzeit für das HTTP-Cookie an, das für das Tracking authentifizierter Clients verwendet werden soll.

Wenn dieser Ablaufwert nicht angegeben wird (oder auf null gesetzt ist), wird das HTTP-Cookie, das für das Tracking authentifizierter Clients verwendet wird, als Sitzungscookie gesetzt, das gelöscht wird, wenn die aktuelle HTTP-Client-Sitzung endet. Es ist wichtig zu beachten, dass der Browser definiert, wann die "aktuelle Sitzung" endet, und einige Browser verwenden die Sitzungswiederherstellung beim Neustart, was dazu führen kann, dass Sitzungscookies unbegrenzt lange bestehen bleiben.

auth_totp_file

syntax: auth_totp_file <filename>
default: -
context: http, server, location, limit_except

Gibt die Datei an, die Benutzernamen und gemeinsame Geheimnisse für die zeitbasierte Einmalpasswort (TOTP) Authentifizierung enthält.

Diese Konfigurationsdatei hat das Format:

# Kommentar
user1:secret1
user2:secret2
user3:secret3

auth_totp_length

syntax: auth_totp_length <number>
default: 6
context: http, server, location, limit_except

Gibt die Truncationslänge des Zeitbasierten Einmalpassworts (TOTP) an. Diese Truncationslänge kann zwischen 1 und 8 Ziffern liegen.

Wenn das bereitgestellte TOTP eine andere Länge als dieser Wert hat, schlägt die Authentifizierungsanfrage fehl.

auth_totp_realm

syntax: auth_totp_realm <string>|off
default: off
context: http, server, location, limit_except

Aktiviert die Validierung des Benutzernamens und des Zeitbasierten Einmalpassworts (TOTP) unter Verwendung des "HTTP Basic Authentication"-Protokolls. Der angegebene Parameter wird als realm für diese Authentifizierung verwendet. Dieser Parameterwert kann Variablen enthalten. Der spezielle Wert off hebt die Anwendung einer von einem höheren Konfigurationslevel geerbten auth_totp_realm Direktive auf.

auth_totp_reuse

syntax: auth_totp_reuse <on>|<off>
default: off
context: http, server, location, limit_except

Aktiviert die Wiederverwendung eines Zeitbasierten Einmalpassworts (TOTP) innerhalb eines Gültigkeitsfensters. Während dies gemäß RFC 6238 ein nicht standardmäßiges Verhalten darstellt, bietet es eine bequeme Möglichkeit, ein minimales Gültigkeitsfenster für generierte TOTP-Codes sicherzustellen, selbst wenn das TOTP bereits dem validierenden System präsentiert wurde.

auth_totp_secret

syntax: auth_totp_secret <string>
default: -
context: http, server, location, limit_except

Ein serverseitiges Geheimnis, das beim Generieren von Sitzungscookies und dann bei der Validierung von Sitzungscookies verwendet wird. Wenn ein Angreifer dieses Geheimnis kennt, kann er Sitzungscookies fälschen, die Zugriff gewähren, daher ist es wichtig, dass es schwer zu erraten ist.

auth_totp_skew

syntax: auth_totp_skew <number>
default: 1
context: http, server, location, limit_except

Gibt die Anzahl der Zeitschritte an, um die die Zeitbasis zwischen den ausstellenden und validierenden TOTP-Systemen verschoben ist.

Aufgrund von Netzwerkverzögerungen kann die Lücke zwischen dem Zeitpunkt, an dem ein OTP generiert wurde, und dem Zeitpunkt, an dem das OTP im validierenden System empfangen wird, groß sein. Tatsächlich ist es möglich, dass der Empfangszeitpunkt im validierenden System und der Zeitpunkt, zu dem das OTP vom ausstellenden System generiert wurde, nicht im selben Zeitstufenfenster liegen. Dementsprechend sollte das validierende System typischerweise eine Richtlinie für ein akzeptables OTP-Übertragungsfenster für die Validierung festlegen. In Übereinstimmung damit sollte das validierende System OTPs nicht nur mit dem Empfangszeitstempel vergleichen, sondern auch mit den vergangenen Zeitstempeln, die innerhalb der Übertragungsverzögerung liegen.

Es ist wichtig zu beachten, dass größere akzeptable Verzögerungsfenster ein größeres Fenster für Angriffe darstellen und ein Gleichgewicht zwischen der Sicherheit und der Benutzerfreundlichkeit von OTPs gefunden werden muss.

auth_totp_start

syntax: auth_totp_start <time>
default: 0
context: http, server, location, limit_except

Gibt die UNIX-Zeit an, ab der die Zeitstufen im Rahmen der Operationen des Zeitbasierten Einmalpassworts (TOTP) gezählt werden sollen.

Der Standardwert ist 0, die UNIX-Epoche am 1970/01/01.

auth_totp_step

syntax: auth_totp_step <interval>
default: 30s
context: http, server, location, limit_except

Gibt das Zeitintervall im Rahmen der Operationen des Zeitbasierten Einmalpassworts (TOTP) an.

Referenzen

GitHub

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