Saltar a contenido

auth-totp: Autenticación de contraseña de un solo uso basada en tiempo (TOTP) para NGINX

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y Amazon Linux 2023
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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_totp_module.so;

Este documento describe nginx-module-auth-totp v1.1.0 lanzado el 18 de diciembre de 2024.

Autenticación de contraseña de un solo uso basada en tiempo (TOTP) para NGINX

El algoritmo de Contraseña de Un Solo Uso Basada en Tiempo (TOTP) proporciona un mecanismo seguro para valores de contraseñas de un solo uso de corta duración, que son deseables para una mayor seguridad. Este algoritmo se puede utilizar en una amplia gama de aplicaciones de red que van desde el acceso remoto a redes privadas virtuales (VPN), inicio de sesión en redes Wi-Fi hasta aplicaciones web orientadas a transacciones.

El módulo nginx-http-auth-totp proporciona autenticación TOTP para un servidor NGINX.

Características

  • Autenticación básica HTTP utilizando contraseña de un solo uso basada en tiempo (TOTP)
  • Seguimiento basado en cookies de clientes autenticados más allá de la ventana de validez de TOTP
  • Secreto configurable, referencia de tiempo, paso de tiempo y longitud de truncamiento para la generación de TOTP
  • Desfase de tiempo configurable para la validación de TOTP

Paquetes

Para los usuarios que prefieren paquetes precompilados y optimizados, el módulo nginx-http-auth-totp se puede instalar desde el repositorio GetPageSpeed:

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

Configuración

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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_totp_module.so;

Directivas

  • sintaxis: auth_totp_cookie <nombre>
  • predeterminado: totp
  • contexto: http, server, location, limit_except

Especifica el nombre de la cookie HTTP que se utilizará para rastrear a los clientes autenticados.

A medida que la validez de la Contraseña de Un Solo Uso Basada en Tiempo (TOTP) utilizada para la autenticación expira (por diseño), se establece una cookie HTTP tras una autenticación exitosa para persistir la autenticación del cliente más allá de la ventana de validez de TOTP. Esta directiva de configuración especifica el nombre que se utilizará al establecer esta cookie, mientras que el período de caducidad de esta cookie puede establecerse utilizando la directiva auth_totp_expiry.

auth_totp_expiry

  • sintaxis: auth_totp_expiry <intervalo>
  • predeterminado: 0s
  • contexto: http, server, location, limit_except

Especifica el tiempo de caducidad para la cookie HTTP que se utilizará para rastrear a los clientes autenticados.

Si este valor de caducidad no se especifica (o se establece en cero), la cookie HTTP utilizada para rastrear a los clientes autenticados se establecerá como una cookie de sesión que se eliminará cuando finalice la sesión HTTP actual. Es importante tener en cuenta que el navegador define cuándo termina la "sesión actual", y algunos navegadores utilizan la restauración de sesión al reiniciar, lo que puede hacer que las cookies de sesión duren indefinidamente.

auth_totp_file

  • sintaxis: auth_totp_file <nombre_archivo>
  • predeterminado: -
  • contexto: http, server, location, limit_except

Especifica el archivo que contiene nombres de usuario y secretos compartidos para la autenticación de Contraseña de Un Solo Uso Basada en Tiempo (TOTP).

Este archivo de configuración tiene el siguiente formato:

# comentario
usuario1:secreto1
usuario2:secreto2
usuario3:secreto3

auth_totp_length

  • sintaxis: auth_totp_length <número>
  • predeterminado: 6
  • contexto: http, server, location, limit_except

Especifica la longitud de truncamiento del código de Contraseña de Un Solo Uso Basada en Tiempo (TOTP). Esta longitud de truncamiento puede estar entre 1 y 8 dígitos inclusive.

Si el TOTP suministrado tiene una longitud diferente a este valor, la solicitud de autenticación fallará.

auth_totp_realm

  • sintaxis: auth_totp_realm <cadena>|off
  • predeterminado: off
  • contexto: http, server, location, limit_except

Habilita la validación del nombre de usuario y la Contraseña de Un Solo Uso Basada en Tiempo (TOTP) utilizando el protocolo "Autenticación Básica HTTP". El parámetro especificado se utiliza como el realm para esta autenticación. Este valor de parámetro puede contener variables. El valor especial de off cancela la aplicación de cualquier directiva auth_totp_realm heredada de un nivel de configuración superior.

auth_totp_reuse

  • sintaxis: auth_totp_reuse <on>|<off>
  • predeterminado: off
  • contexto: http, server, location, limit_except

Habilita la reutilización de una Contraseña de Un Solo Uso Basada en Tiempo (TOTP) dentro de una ventana de validez. Si bien este comportamiento no es estándar según RFC 6238, proporciona una manera conveniente de asegurar una ventana mínima de validez para los códigos TOTP generados, incluso si el TOTP ya ha sido presentado al sistema de validación.

auth_totp_skew

  • sintaxis: auth_totp_skew <número>
  • predeterminado: 1
  • contexto: http, server, location, limit_except

Especifica el número de pasos de tiempo por los cuales la base de tiempo entre los sistemas TOTP emisores y validadores.

Debido a la latencia de la red, la brecha entre el momento en que se generó un OTP y el momento en que se recibe en el sistema de validación puede ser grande. De hecho, es posible que el tiempo de recepción en el sistema de validación y el momento en que se generó el OTP por el sistema emisor no caigan dentro de la misma ventana de paso de tiempo. En consecuencia, el sistema de validación debe establecer típicamente una política para una ventana de transmisión de OTP aceptable para la validación. En línea con esto, el sistema de validación debe comparar los OTP no solo con la marca de tiempo de recepción, sino también con las marcas de tiempo pasadas que están dentro del retraso de transmisión.

Es importante tener en cuenta que ventanas de retraso aceptables más grandes representan una ventana más amplia para ataques y se debe encontrar un equilibrio entre la seguridad y la usabilidad de los OTP.

auth_totp_start

  • sintaxis: auth_totp_start <tiempo>
  • predeterminado: 0
  • contexto: http, server, location, limit_except

Especifica el tiempo UNIX desde el cual comenzar a contar los pasos de tiempo como parte de las operaciones del algoritmo de Contraseña de Un Solo Uso Basada en Tiempo (TOTP).

El valor predeterminado es 0, la época UNIX en 1970/01/01.

auth_totp_step

  • sintaxis: auth_totp_step <intervalo>
  • predeterminado: 30s
  • contexto: http, server, location, limit_except

Especifica el paso de tiempo como parte de las operaciones del algoritmo de Contraseña de Un Solo Uso Basada en Tiempo (TOTP).

Referencias

GitHub

Puedes encontrar consejos adicionales de configuración y documentación para este módulo en el repositorio de GitHub para nginx-module-auth-totp.