auth-totp: Autenticação de senha única baseada em tempo (TOTP) para NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

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

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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_totp_module.so;

Este documento descreve o nginx-module-auth-totp v1.2.0 lançado em 04 de maio de 2026.

Autenticação de senha única baseada em tempo (TOTP) para NGINX

O algoritmo de Senha Única Baseada em Tempo (TOTP) fornece um mecanismo seguro para valores de senha única de curta duração, que são desejáveis para uma segurança aprimorada. Este algoritmo pode ser usado em uma ampla gama de aplicações de rede, desde acesso remoto a Redes Privadas Virtuais (VPN), login em redes Wi-Fi até aplicações web orientadas a transações.

O módulo nginx-http-auth-totp fornece autenticação TOTP para um servidor NGINX.

Recursos

Autenticação básica HTTP usando senha única baseada em tempo (TOTP)
Rastreamento baseado em cookies de clientes autenticados além da janela de validade do TOTP
Segredo configurável, referência de tempo, passo de tempo e comprimento de truncamento para geração de TOTP
Desvio de tempo configurável para validação de TOTP

Pacotes

Para usuários que preferem pacotes pré-compilados e otimizados, o módulo nginx-http-auth-totp pode ser instalado a partir do repositório GetPageSpeed:

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

Configuração

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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_totp_module.so;

Diretivas

auth_totp_cookie

sintaxe: auth_totp_cookie <name>
padrão: totp
contexto: http, server, location, limit_except

Especifica o nome do cookie HTTP a ser usado para rastrear clientes autenticados.

À medida que a validade da Senha Única Baseada em Tempo (TOTP) usada para autenticação expira (por design), um cookie HTTP é definido após a autenticação bem-sucedida a fim de persistir a autenticação do cliente além da janela de validade do TOTP. Esta diretiva de configuração especifica o nome a ser usado ao definir este cookie, enquanto o período de expiração para este cookie pode ser definido usando a diretiva auth_totp_expiry.

auth_totp_expiry

sintaxe: auth_totp_expiry <interval>
padrão: 0s
contexto: http, server, location, limit_except

Especifica o tempo de expiração para o cookie HTTP a ser usado para rastrear clientes autenticados.

Se este valor de expiração não for especificado (ou definido como zero), o cookie HTTP usado para rastrear clientes autenticados será definido como um cookie de sessão que será excluído quando a sessão HTTP atual do cliente terminar. É importante notar que o navegador define quando a "sessão atual" termina, e alguns navegadores usam a restauração de sessão ao reiniciar, o que pode fazer com que os cookies de sessão durem indefinidamente.

auth_totp_file

sintaxe: auth_totp_file <filename>
padrão: -
contexto: http, server, location, limit_except

Especifica o arquivo que contém nomes de usuários e segredos compartilhados para autenticação de Senha Única Baseada em Tempo (TOTP).

Este arquivo de configuração tem o formato:

# comentário
user1:secret1
user2:secret2
user3:secret3

auth_totp_length

sintaxe: auth_totp_length <number>
padrão: 6
contexto: http, server, location, limit_except

Especifica o comprimento de truncamento do código da Senha Única Baseada em Tempo (TOTP). Este comprimento de truncamento pode ser entre 1 e 8 dígitos, inclusive.

Se o TOTP fornecido tiver um comprimento diferente deste valor, a solicitação de autenticação falhará.

auth_totp_realm

sintaxe: auth_totp_realm <string>|off
padrão: off
contexto: http, server, location, limit_except

Habilita a validação do nome de usuário e da Senha Única Baseada em Tempo (TOTP) usando o protocolo "HTTP Basic Authentication". O parâmetro especificado é usado como o realm para esta autenticação. Este valor de parâmetro pode conter variáveis. O valor especial de off cancela a aplicação de qualquer diretiva auth_totp_realm herdada de um nível de configuração superior.

auth_totp_reuse

sintaxe: auth_totp_reuse <on>|<off>
padrão: off
contexto: http, server, location, limit_except

Habilita a reutilização de uma Senha Única Baseada em Tempo (TOTP) dentro de uma janela de validade. Embora isso seja um comportamento não padrão de acordo com RFC 6238, fornece uma maneira conveniente de garantir uma janela mínima de validade para os códigos TOTP gerados, mesmo que o TOTP já tenha sido apresentado ao sistema de validação.

auth_totp_secret

sintaxe: auth_totp_secret <string>
padrão: -
contexto: http, server, location, limit_except

Um segredo do lado do servidor usado ao gerar cookies de sessão e, em seguida, ao validar cookies de sessão. Se um atacante conhecer este segredo, ele poderá forjar cookies de sessão que concedem acesso, portanto, é vital que seja difícil de adivinhar.

auth_totp_skew

sintaxe: auth_totp_skew <number>
padrão: 1
contexto: http, server, location, limit_except

Especifica o número de passos de tempo pelos quais a base de tempo entre os sistemas TOTP de emissão e validação.

Devido à latência da rede, a diferença entre o momento em que um OTP foi gerado e o momento em que o OTP é recebido no sistema de validação pode ser grande. De fato, é possível que o horário de recebimento no sistema de validação e o momento em que o OTP foi gerado pelo sistema emissor não estejam dentro da mesma janela de passo de tempo. Assim, o sistema de validação deve tipicamente estabelecer uma política para uma janela de transmissão de OTP aceitável para validação. Nesse sentido, o sistema de validação deve comparar OTPs não apenas com o timestamp de recebimento, mas também com os timestamps passados que estão dentro do atraso de transmissão.

É importante notar que janelas de atraso aceitáveis maiores representam uma janela maior para ataques e um equilíbrio deve ser alcançado entre a segurança e a usabilidade dos OTPs.

auth_totp_start

sintaxe: auth_totp_start <time>
padrão: 0
contexto: http, server, location, limit_except

Especifica o tempo UNIX a partir do qual começar a contar os passos de tempo como parte das operações do algoritmo de Senha Única Baseada em Tempo (TOTP).

O valor padrão é 0, o epoch UNIX em 1970/01/01.

auth_totp_step

sintaxe: auth_totp_step <interval>
padrão: 30s
contexto: http, server, location, limit_except

Especifica o passo de tempo como parte das operações do algoritmo de Senha Única Baseada em Tempo (TOTP).

Referências

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-auth-totp.