Pular para conteúdo

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
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.1.0 lançado em 18 de dezembro de 2024.

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 segurança aprimorada. Este algoritmo pode ser usado em uma ampla gama de aplicativos 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 cookie 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_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;
    }
}

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

load_module modules/ngx_http_auth_totp_module.so;

Diretivas

  • 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 para 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 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 de Senha Única Baseada em Tempo (TOTP). Este comprimento de truncamento pode estar 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 este seja um comportamento não padrão de acordo com RFC 6238, ele 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_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 caia na 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. Em linha com isso, o sistema de validação deve comparar OTPs não apenas com o timestamp de recebimento, mas também com timestamps passados que estejam 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 GitHub do nginx-module-auth-totp.