auth-totp: Authentification par mot de passe à usage unique basé sur le temps (TOTP) pour NGINX

Installation

Vous pouvez installer ce module dans toute distribution basée sur RHEL, y compris, mais sans s'y limiter :

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

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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_auth_totp_module.so;

Ce document décrit nginx-module-auth-totp v1.1.0 publié le 18 décembre 2024.

Authentification par mot de passe à usage unique basé sur le temps (TOTP) pour NGINX

L'algorithme de mot de passe à usage unique basé sur le temps (TOTP) fournit un mécanisme sécurisé pour des valeurs de mot de passe à usage unique à durée limitée, qui sont souhaitables pour une sécurité renforcée. Cet algorithme peut être utilisé dans un large éventail d'applications réseau allant de l'accès à un réseau privé virtuel (VPN) à distance, à la connexion à un réseau Wi-Fi, jusqu'aux applications Web orientées transaction.

Le module nginx-http-auth-totp fournit une authentification TOTP pour un serveur NGINX.

Fonctionnalités

Authentification HTTP de base utilisant un mot de passe à usage unique basé sur le temps (TOTP)
Suivi basé sur des cookies des clients authentifiés au-delà de la fenêtre de validité TOTP
Secret configurable, référence temporelle, pas de temps et longueur de troncature pour la génération TOTP
Décalage temporel configurable pour la validation TOTP

Paquets

Pour les utilisateurs qui préfèrent des paquets préconstruits et optimisés, le module nginx-http-auth-totp peut être installé depuis le dépôt GetPageSpeed :

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

Configuration

server {
    listen 80;

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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_auth_totp_module.so;

Directives

auth_totp_cookie

syntaxe : auth_totp_cookie <name>
par défaut : totp
contexte : http, server, location, limit_except

Spécifie le nom du cookie HTTP à utiliser pour le suivi des clients authentifiés.

Alors que la validité du mot de passe à usage unique basé sur le temps (TOTP) utilisé pour l'authentification expire (par conception), un cookie HTTP est défini après une authentification réussie afin de persister l'authentification du client au-delà de la fenêtre de validité TOTP. Cette directive de configuration spécifie le nom à utiliser lors de la définition de ce cookie, tandis que la période d'expiration de ce cookie peut être définie à l'aide de la directive auth_totp_expiry.

auth_totp_expiry

syntaxe : auth_totp_expiry <interval>
par défaut : 0s
contexte : http, server, location, limit_except

Spécifie le temps d'expiration pour le cookie HTTP à utiliser pour le suivi des clients authentifiés.

Si cette valeur d'expiration n'est pas spécifiée (ou définie sur zéro), le cookie HTTP utilisé pour le suivi des clients authentifiés sera défini comme un cookie de session qui sera supprimé lorsque la session HTTP actuelle du client se termine. Il est important de noter que le navigateur définit quand la "session actuelle" se termine, et certains navigateurs utilisent la restauration de session lors du redémarrage, ce qui peut entraîner une durée indéfinie pour les cookies de session.

auth_totp_file

syntaxe : auth_totp_file <filename>
par défaut : -
contexte : http, server, location, limit_except

Spécifie le fichier contenant les noms d'utilisateur et les secrets partagés pour l'authentification par mot de passe à usage unique basé sur le temps (TOTP).

Ce fichier de configuration a le format :

# commentaire
user1:secret1
user2:secret2
user3:secret3

auth_totp_length

syntaxe : auth_totp_length <number>
par défaut : 6
contexte : http, server, location, limit_except

Spécifie la longueur de troncature du code de mot de passe à usage unique basé sur le temps (TOTP). Cette longueur de troncature peut être comprise entre 1 et 8 chiffres inclusivement.

Si le TOTP fourni a une longueur différente de cette valeur, la demande d'authentification échouera.

auth_totp_realm

syntaxe : auth_totp_realm <string>|off
par défaut : off
contexte : http, server, location, limit_except

Active la validation du nom d'utilisateur et du mot de passe à usage unique basé sur le temps (TOTP) en utilisant le protocole "HTTP Basic Authentication". Le paramètre spécifié est utilisé comme le realm pour cette authentification. Cette valeur de paramètre peut contenir des variables. La valeur spéciale de off annule l'application de toute directive auth_totp_realm héritée d'un niveau de configuration supérieur.

auth_totp_reuse

syntaxe : auth_totp_reuse <on>|<off>
par défaut : off
contexte : http, server, location, limit_except

Active la réutilisation d'un mot de passe à usage unique basé sur le temps (TOTP) dans une fenêtre de validité. Bien que cela soit un comportement non standard selon RFC 6238, cela fournit un moyen pratique d'assurer une fenêtre de validité minimale pour les codes TOTP générés, même si le TOTP a déjà été présenté au système de validation.

auth_totp_skew

syntaxe : auth_totp_skew <number>
par défaut : 1
contexte : http, server, location, limit_except

Spécifie le nombre de pas de temps entre les systèmes TOTP émetteur et validateur.

En raison de la latence réseau, l'écart entre le moment où un OTP a été généré et le moment où l'OTP est reçu par le système de validation peut être important. En effet, il est possible que le moment de réception au système de validation et celui où l'OTP a été généré par le système émetteur ne tombent pas dans la même fenêtre de pas de temps. En conséquence, le système de validation doit généralement établir une politique pour une fenêtre de transmission OTP acceptable pour la validation. Dans cette optique, le système de validation doit comparer les OTP non seulement avec l'horodatage de réception, mais aussi avec les horodatages passés qui se situent dans le délai de transmission.

Il est important de noter que des fenêtres de délai d'acceptation plus larges représentent une plus grande fenêtre pour les attaques et un équilibre doit être trouvé entre la sécurité et l'utilisabilité des OTP.

auth_totp_start

syntaxe : auth_totp_start <time>
par défaut : 0
contexte : http, server, location, limit_except

Spécifie le temps UNIX à partir duquel commencer à compter les pas de temps dans le cadre des opérations de l'algorithme de mot de passe à usage unique basé sur le temps (TOTP).

La valeur par défaut est 0, l'époque UNIX à 1970/01/01.

auth_totp_step

syntaxe : auth_totp_step <interval>
par défaut : 30s
contexte : http, server, location, limit_except

Spécifie le pas de temps dans le cadre des opérations de l'algorithme de mot de passe à usage unique basé sur le temps (TOTP).

Références

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-auth-totp.