Os clientes frequentemente nos perguntam como podem usar o NGINX Plus e o NGINX para proteger recursos ou aplicativos protegidos autenticando os usuários que os solicitam. Hoje estamos anunciando uma implementação de referência desse sistema de autenticação e disponibilizando-a no repositório da NGINX, Inc. no GitHub . Neste post descrevemos como a implementação funciona, como instalá-la e como usá-la como modelo para seu próprio sistema de autenticação.
A solução aproveita o módulo ngx_http_auth_request_module no NGINX Plus e NGINX, que encaminha solicitações de autenticação para um serviço externo. Na implementação de referência, esse serviço é um daemon que chamamos de ldap‑auth . Ele é escrito em Python e se comunica com um servidor de autenticação Lightweight Directory Access Protocol (LDAP) – OpenLDAP por padrão, mas testamos o daemon ldap-auth em relação às configurações padrão do Microsoft® Windows® Server Active Directory também (versões de 2003 e 2012).
O daemon ldap-auth serve como um modelo para seu próprio aplicativo “conector”, que você pode escrever em outras linguagens, implantar com diferentes sistemas de autenticação ou ambos. A equipe de Serviços Profissionais da NGINX está disponível para ajudar com essas adaptações.
Notas:
Para executar a autenticação, o módulo http_auth_request faz uma sub-solicitação HTTP ao daemon ldap-auth, que atua como intermediário e interpreta a sub-solicitação para o servidor LDAP – ele usa HTTP para comunicação com o NGINX Plus e a API apropriada para comunicação com o servidor LDAP.
Presumimos que, se você estiver interessado na implementação de referência, você já tem um aplicativo ou outros recursos que deseja proteger exigindo autenticação. Para facilitar o teste da implementação de referência, no entanto, estamos fornecendo um daemon de backend de exemplo, também escrito em Python, que escuta na porta 9000. Ele pode substituir um aplicativo HTTP real durante o teste, solicitando credenciais do usuário e criando um cookie com base nelas.
Aqui está uma descrição passo a passo do processo de autenticação na implementação de referência. Os detalhes são determinados pelas configurações no arquivo de configuração nginx-ldap-auth.conf ; consulte Configurando a implementação de referência abaixo. O fluxograma abaixo das etapas resume o processo.
Um cliente envia uma solicitação HTTP para um recurso protegido hospedado em um servidor para o qual o NGINX Plus está atuando como proxy reverso.
O NGINX Plus (especificamente, o módulo http_auth_request) encaminha a solicitação para o daemon ldap‑auth, que responde com código HTTP401
porque nenhuma credencial foi fornecida.
O NGINX Plus encaminha a solicitação para http://backend/login , que corresponde ao daemon de backend. Ele grava o URI da solicitação original no cabeçalho X-Target
da solicitação encaminhada.
O daemon de backend envia ao cliente um formulário de login (o formulário é definido no código Python para o daemon). Conforme configurado pela diretiva error_page
, o NGINX define o código HTTP no formulário de login para200
.
O usuário preenche os campos Nome de usuário e Senha no formulário e clica no botão Login. De acordo com o código no formulário, o cliente gera uma solicitação HTTP POST
direcionada para /login , que o NGINX Plus encaminha para o daemon de backend.
O daemon de backend constrói uma string no formato nome de usuário : senha
, aplica a codificação Base64, gera um cookie chamado nginxauth com seu valor definido como a string codificada e envia o cookie ao cliente. Ele define o sinalizador httponly
para impedir o uso de JavaScript para ler ou manipular o cookie (protegendo contra a vulnerabilidade de script entre sites [XSS] ).
O cliente retransmite sua solicitação original (da Etapa 1), desta vez incluindo o cookie no campo Cookie
do cabeçalho HTTP. O NGINX Plus encaminha a solicitação para o daemon ldap‑auth (como na Etapa 2).
O daemon ldap-auth decodifica o cookie e envia o nome de usuário e a senha para o servidor LDAP em uma solicitação de autenticação.
A próxima ação depende se o servidor LDAP autentica o usuário com sucesso:
Se a autenticação for bem-sucedida, o daemon ldap-auth enviará o código HTTP200
para NGINX Plus. O NGINX Plus solicita o recurso do daemon de backend. Na implementação de referência, o daemon de backend retorna o seguinte texto:
Olá, mundo! URL solicitada: URL
O arquivo nginx-ldap-auth.conf inclui diretivas para armazenar em cache os resultados da tentativa de autenticação; para desabilitar o cache, consulte Cache abaixo.
Se a autenticação falhar, o daemon ldap-auth envia o código HTTP401
para NGINX Plus. O NGINX Plus encaminha a solicitação para o daemon de backend novamente (como na Etapa 3) e o processo se repete.
O arquivo de configuração do NGINX Plus distribuído com a implementação de referência, nginx-ldap-auth.conf , configura todos os componentes, exceto o servidor LDAP (ou seja, o NGINX Plus, o cliente, o daemon ldap-auth e o daemon de backend) para serem executados no mesmo host, o que é adequado para fins de teste. O servidor LDAP também pode ser executado nesse host durante o teste.
Em uma implantação real, o aplicativo de backend e o servidor de autenticação normalmente são executados em um host separado, com o NGINX Plus em um terceiro host. O daemon ldap-auth não consome muitos recursos na maioria das situações, portanto ele pode ser executado no host NGINX Plus ou em outro host de sua escolha.
Crie um clone do repositório GitHub .
Se o NGINX Plus ainda não estiver em execução, instale-o de acordo com as instruções do seu sistema operacional.
Se um servidor LDAP ainda não estiver em execução, instale e configure um. Por padrão, o daemon ldap-auth se comunica com o OpenLDAP, mas o Microsoft Windows Active Directory 2003 e 2012 também são suportados.
Se estiver usando o servidor LDAP apenas para testar a implementação de referência, você pode usar a imagem Docker do servidor OpenLDAP disponível no GitHub ou pode configurar um servidor usando instruções como Como instalar e configurar o OpenLDAP e o phpLDAPadmin no Ubuntu 16.04 .
Anote os valores definidos para o DN base, o DN de vinculação e a senha de vinculação. Você os colocará no arquivo de configuração do NGINX em Configurando a implementação de referência .
No host onde o daemon ldap‑auth será executado, instale o seguinte software adicional. Recomendamos usar as versões distribuídas com o sistema operacional, em vez de baixar o software de um repositório de código aberto.
Copie os seguintes arquivos do seu repositório clone para os hosts indicados:
Modifique o arquivo de configuração do NGINX Plus conforme descrito em Configurando a implementação de referência abaixo. Depois de fazer as alterações, execute o comando nginx
-t
para verificar se o arquivo é sintaticamente válido.
root# nginx -t nginx: a sintaxe do arquivo de configuração /etc/nginx/nginx.conf está ok nginx: o teste do arquivo de configuração /etc/nginx/nginx.conf foi bem-sucedido
Inicie o NGINX Plus. Se o NGINX Plus já estiver em execução, execute o seguinte comando para recarregar o arquivo de configuração:
root# nginx -s recarregar
Execute os seguintes comandos nos hosts apropriados para iniciar o daemon ldap‑auth e o daemon de backend.
raiz# nginx-ldap-auth-daemon-ctl.sh iniciar raiz# python backend-sample-app.py
Use um navegador da web para acessar http:// nginx-server-address :8081 . Verifique se o navegador apresenta o formulário de autenticação. Depois de preencher o formulário e enviá-lo, verifique se o servidor retorna a resposta esperada para credenciais válidas. Conforme observado acima, o daemon de backend retorna o seguinte texto:
Olá, mundo! URL solicitada: URL
Faça as seguintes alterações no arquivo nginx-ldap-auth.conf . Alguns são obrigatórios e outros opcionais, conforme indicado.
Conforme implementado em nginx-ldap-auth-daemon.py , o daemon ldap-auth se comunica com um servidor OpenLDAP, passando parâmetros para especificar qual conta de usuário autenticar. Para eliminar a necessidade de modificar o código Python, o arquivo nginx-ldap-auth.conf contém diretivas proxy_set_header
que definem valores no cabeçalho HTTP que são então usados para definir os parâmetros. A tabela a seguir mapeia os parâmetros e cabeçalhos.
Parâmetro LDAP | Cabeçalho HTTP |
---|---|
baseado |
X-LDAP-BaseDN |
vincular |
X-LDAP-BindDN |
senha de ligação |
X-LDAP-BindPass |
nome do cookie |
X-Nome do Cookie |
reino |
X-LDAP-Reino |
modelo |
Modelo X-LDAP |
URL |
X-LDAP-URL |
(Obrigatório) Nas diretivas a seguir, substitua os valores em negrito pelos valores corretos para a implantação do seu servidor LDAP. Observe em particular que o arquivo nginx-ldap-auth.conf usa a porta bem conhecida para LDAPS, 636. Se você alterar a porta para 389 (a porta conhecida para LDAP) ou outra porta LDAP, lembre-se também de alterar o nome do protocolo de ldaps
para ldap
.
# URL e porta para conexão ao servidor LDAP proxy_set_header X-Ldap-URL " ldaps :// example.com :636 "; # DN base proxy_set_header X-Ldap-BaseDN " cn=Usuários,dc=teste,dc=local "; # DN de vinculação proxy_set_header X-Ldap-BindDN " cn=root,dc=teste,dc=local "; # DN de vinculação proxy_set_header X-Ldap-BindDN " cn=root,dc=teste,dc=local "; # DN de vinculação proxy_set_header X-Ldap-BindPass " segredo ";
(Obrigatório se estiver usando o Active Directory em vez do OpenLDAP) Descomente a seguinte diretiva conforme mostrado:
proxy_set_header X-Ldap-Template "(SAMAccountName=%(nomedeusuário)s)";
(Opcional) A implementação de referência usa autenticação baseada em cookie. Se você estiver usando autenticação básica HTTP, comente as seguintes diretivas conforme mostrado:
# proxy_set_header X-CookieName "nginxauth"; # proxy_set_header Cookie nginxauth=$cookie_nginxauth;
(Opcional) Se você quiser alterar o valor do parâmetro de modelo
que o daemon ldap‑auth passa para o servidor OpenLDAP por padrão, descomente a seguinte diretiva conforme mostrado e altere o valor:
proxy_set_header X-Ldap-Template " (cn=%(nome de usuário)s) ";
(Opcional) Se você quiser alterar o nome do reino do valor padrão ( Restrito ), descomente e altere a seguinte diretiva:
proxy_set_header X-Ldap-Realm " Restrito ";
Se o daemon de backend não estiver em execução no mesmo host que o NGINX Plus, altere o endereço IP dele no bloco de configuração upstream
:
backend upstream { servidor127.0.0.1 :9000; }
Se o daemon ldap‑auth não estiver em execução no mesmo host que o NGINX Plus, altere o endereço IP nesta diretiva proxy_pass
:
localização = /auth-proxy { proxy_pass http://127.0.0.1 :8888; # ... }
Se o cliente não estiver sendo executado no mesmo host que o NGINX Plus, altere o endereço IP nesta diretiva de escuta
(ou remova o endereço completamente para aceitar tráfego de qualquer cliente). Você também pode alterar a porta na qual o NGINX escuta a partir da 8081, se desejar:
servidor { ouvir127.0.0.1 :8081 ; # ... }
O arquivo nginx-ldap-auth.conf permite o armazenamento em cache de dados e credenciais. Opcionalmente, você pode alterar as seguintes configurações:
A diretiva proxy_cache_path
no bloco de configuração http
cria um diretório de disco local chamado cache e aloca 10 MB em memória compartilhada para uma zona chamada auth_cache , onde os metadados são armazenados.
caminho_do_cache_proxy cache/ keys_zone= cache_de_autenticação : 10m ;
Se você alterar o nome da zona de memória compartilhada, também deverá alterá-lo na diretiva proxy_cache
(no bloco de localização
que direciona o tráfego para o daemon ldap-auth).
localização = /auth-proxy { proxy_cache auth_cache ; # ... }
A diretiva proxy_cache_valid
(no mesmo bloco de localização
que proxy_cache
) especifica que as respostas em cache marcadas com código HTTP200
ou403
são válidos por 10 minutos.
localização = /auth-proxy { proxy_cache_valid 200 403 10m ; # ... }
Para desabilitar o cache, comente estas três diretivas mais a diretiva proxy_cache_key
.
Conforme mencionado acima, você pode usar o daemon ldap-auth como um modelo para seu próprio aplicativo que aceita solicitações do módulo http_auth_request. Se estiver escrevendo um aplicativo em Python para se comunicar com um tipo diferente (não LDAP) de servidor de autenticação, escreva uma nova classe de manipulador de autenticação para substituir LDAPAuthHandler
no script nginx-ldap-auth-daemon.py .
O daemon de backend usa codificação Base64 no nome de usuário e senha no cookie. Base64 é uma forma muito fraca de embaralhamento, tornando as credenciais vulneráveis à extração e ao uso indevido. Para que a autenticação atenda a algum propósito real, você precisa usar uma criptografia mais sofisticada em seu aplicativo de backend.
"Esta postagem do blog pode fazer referência a produtos que não estão mais disponíveis e/ou não têm mais suporte. Para obter as informações mais atualizadas sobre os produtos e soluções F5 NGINX disponíveis, explore nossa família de produtos NGINX . O NGINX agora faz parte do F5. Todos os links anteriores do NGINX.com redirecionarão para conteúdo semelhante do NGINX no F5.com."