spnego-http-auth: módulo NGINX para autenticação HTTP SPNEGO

Requer o plano Pro (ou superior) da assinatura GetPageSpeed NGINX Extras.

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-spnego-http-auth

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-spnego-http-auth

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

load_module modules/ngx_http_auth_spnego_module.so;

Este documento descreve o nginx-module-spnego-http-auth v1.2.0 lançado em 14 de fevereiro de 2026.

Este módulo implementa suporte a SPNEGO para nginx(http://nginx.org). Atualmente, ele suporta apenas autenticação Kerberos via GSSAPI.

Pré-requisitos

A autenticação foi testada com (pelo menos) os seguintes:

Nginx 1.2 até 1.15
Internet Explorer 8 e acima
Firefox 10 e acima
Chrome 20 e acima
Curl 7.x (GSS-Negotiate), 7.x (SPNEGO/fbopenssl)

A biblioteca kerberos subjacente usada para esses testes foi o MIT KRB5 v1.12.

Referência de configuração

Você pode configurar a autenticação GSS por localização e/ou de forma global:

Essas opções são obrigatórias. * auth_gss: on/off, para facilitar a desativação enquanto mantém outras opções no arquivo de configuração * auth_gss_keytab: caminho absoluto para o arquivo keytab contendo as credenciais do serviço

Essas opções DEVEM ser especificadas SOMENTE se você tiver um keytab contendo principais privilegiados. Em quase todos os casos, você não deve colocar essas no arquivo de configuração, pois gss_accept_sec_context fará a coisa certa. * auth_gss_realm: nome do reino Kerberos. Se isso for especificado, o reino é passado apenas para a variável nginx $remote_user se for diferente deste padrão. Para substituir esse comportamento, defina auth_gss_format_full como on em sua configuração. * auth_gss_service_name: nome do principal do serviço a ser usado ao adquirir credenciais.

Se você deseja autorizar apenas um conjunto específico de principais, pode usar a diretiva auth_gss_authorized_principal. A sintaxe de configuração suporta múltiplas entradas, uma por linha.

auth_gss_authorized_principal <primary1>@<realm>
auth_gss_authorized_principal <primary2>@<realm>

Os principais também podem ser autorizados usando um padrão regex via a diretiva auth_gss_authorized_principal_regex. Essa diretiva pode ser usada juntamente com a diretiva auth_gss_authorized_principal.

auth_gss_authorized_principal <primary1>@<realm>
auth_gss_authorized_principal_regex ^(<primary2>)/(<instance>)@<realm>$

O cabeçalho do usuário remoto no nginx só pode ser definido fazendo autenticação básica. Assim, este módulo define um cabeçalho de autenticação básica falso que chegará ao seu aplicativo backend para definir esse cabeçalho/variável nginx. A maneira mais fácil de desativar esse comportamento é adicionar a seguinte configuração à sua configuração de localização.

proxy_set_header Authorization "";

Uma versão futura do módulo pode tornar esse comportamento uma opção, mas isso deve ser uma solução suficiente por enquanto.

Se você deseja habilitar regras de nome local GSS para reescrever nomes de usuário, pode especificar a opção auth_gss_map_to_local.

Delegação de Credenciais

As credenciais do usuário podem ser delegadas ao nginx usando a diretiva auth_gss_delegate_credentials. Essa diretiva habilitará a delegação irrestrita se o usuário optar por delegar suas credenciais. A delegação restrita (S4U2proxy) também pode ser habilitada usando a diretiva auth_gss_constrained_delegation juntamente com a diretiva auth_gss_delegate_credentials. Para especificar o nome do arquivo ccache para armazenar o ticket de serviço usado para delegação restrita, defina a diretiva auth_gss_service_ccache. Caso contrário, o nome padrão do ccache será usado.

auth_gss_service_ccache /tmp/krb5cc_0;
auth_gss_delegate_credentials on;
auth_gss_constrained_delegation on;

As credenciais delegadas serão armazenadas no diretório tmp do sistema. Após a conclusão da solicitação, o arquivo de credenciais será destruído. O nome do arquivo de credenciais será especificado na variável nginx $krb5_cc_name. O uso da variável pode incluir passá-la para um programa fcgi usando a diretiva fastcgi_param.

fastcgi_param KRB5CCNAME $krb5_cc_name;

A delegação restrita atualmente é suportada apenas usando o esquema de autenticação negotiate e foi testada apenas com MIT Kerberos (Use por sua conta e risco se estiver usando Heimdal Kerberos).

Recuo para autenticação básica

O módulo recua para autenticação básica por padrão se nenhuma negociação for tentada pelo cliente. Se você estiver usando SPNEGO sem SSL, é recomendável desativar o recuo para autenticação básica, pois a senha seria enviada em texto claro. Isso é feito definindo auth_gss_allow_basic_fallback no arquivo de configuração.

auth_gss_allow_basic_fallback off

Essas opções afetam a operação da autenticação básica: * auth_gss_realm: nome do reino Kerberos. Se isso for especificado, o reino é passado apenas para a variável nginx $remote_user se for diferente deste padrão. Para substituir esse comportamento, defina auth_gss_format_full como 1 em sua configuração. * auth_gss_force_realm: Autenticar forçadamente usando o reino configurado em auth_gss_realm ou o reino padrão do sistema se auth_gss_realm não estiver definido. Isso reescreverá $remote_user se o cliente forneceu um reino diferente. Se auth_gss_format_full não estiver definido, $remote_user não incluirá um reino mesmo que um tenha sido especificado pelo cliente.

Solução de Problemas

Verifique os logs. Se você ver uma menção ao NTLM, seu cliente está tentando conectar usando NTLMSSP, que não é suportado e é inseguro.

Verifique se você tem um principal HTTP no seu keytab

Utilitários MIT Kerberos

$ KRB5_KTNAME=FILE:<caminho para seu keytab> klist -k

ou

$ ktutil
ktutil: read_kt <caminho para seu keytab>
ktutil: list

Utilitários Heimdal Kerberos

$ ktutil -k <caminho para seu keytab> list

Obtenha um principal HTTP

Se você descobrir que não tem o principal de serviço HTTP, está executando em um ambiente Active Directory, e está vinculado ao domínio de forma que as ferramentas Samba funcionem corretamente

$ env KRB5_KTNAME=FILE:<caminho para seu keytab> net ads -P keytab add HTTP

Se você estiver executando em um ambiente kerberos diferente, provavelmente pode executar

$ env KRB5_KTNAME=FILE:<caminho para seu keytab> krb5_keytab HTTP

Aumente o tamanho máximo permitido do cabeçalho

Em um ambiente Active Directory, o token SPNEGO no cabeçalho Authorization inclui informações PAC (Privilege Access Certificate), que incluem todos os grupos de segurança dos quais o usuário faz parte. Isso pode fazer com que o cabeçalho cresça além do limite padrão de 8kB e causar a seguinte mensagem de erro:

400 Bad Request
Request Header Or Cookie Too Large

Por razões de desempenho, a melhor solução é reduzir o número de grupos dos quais o usuário faz parte. Quando isso não é prático, você também pode optar por aumentar o tamanho do cabeçalho permitido definindo explicitamente o número e o tamanho dos buffers de cabeçalho do Nginx:

large_client_header_buffers 8 32k;

Depuração

O módulo imprime todo tipo de informação de depuração se o nginx for compilado com a opção --with-debug, e a diretiva error_log tiver um nível debug.

NTLM

Observe que o módulo não suporta NTLMSSP no Negotiate. NTLM, tanto v1 quanto v2, é um protocolo explorável e deve ser evitado sempre que possível.

Windows

Para ambientes KDC/AD do Windows, consulte a documentação aqui.

Ajuda

Se você não conseguir resolver as coisas, sinta-se à vontade para abrir uma issue no Github e farei o meu melhor para ajudá-lo.