nginx http shibboleth download - nginx http shibboleth código fonte download

nginx http shibboleth

Dados do site

v2.0.2

Baixar

Módulo de solicitação de autenticação Shibboleth para Nginx

Este módulo permite que o Nginx funcione com Shibboleth, por meio do autor do autor do fastcgi de Shibboleth. Este módulo requer configuração específica para funcionar corretamente, bem como o aplicativo Autorizador FastCGI da Shibboleth disponível no sistema. O objetivo é ser semelhante às partes do mod_shib do Apache, embora as configurações de autorização e autenticação Shibboleth sejam configuradas via shibboleth2.xml e não na configuração do servidor da web.

Com este módulo configurado em um bloco location , as solicitações recebidas são autorizadas dentro do NGINX com base no resultado de uma sub -calma para o autorizador fastcgi de Shibboleth. Nesse processo, este módulo pode ser usado para copiar os atributos do usuário de uma resposta do autorizador bem -sucedida à solicitação original do NGINX como cabeçalhos ou parâmetros de ambiente para uso por qualquer aplicativo de back -end. Se a autorização não for bem -sucedida, o status de resposta do autor e os cabeçalhos serão devolvidos ao cliente, negando o acesso ou redirecionando o navegador do usuário de acordo (como uma página do Wayf, se estiver configurado).

Este módulo funciona na fase de acesso e, portanto, pode ser combinado com outros módulos de acesso (como access , auth_basic ) através da diretiva satisfy . Este módulo também pode ser compilado ao lado de ngx_http_auth_request_module , embora o uso de ambos os dois módulos no mesmo bloco location não seja testado e não seja aconselhado.

Leia mais sobre o comportamento abaixo e consulte a configuração para obter notas importantes para evitar a falsificação se estiver usando cabeçalhos para atributos.

Para obter mais informações sobre por que este é um módulo dedicado, consulte https://forum.nginx.org/read.php?2,238523,238523#msg-238523

Diretivas

As seguintes diretivas são adicionadas aos seus arquivos de configuração NGINX. Os contextos mencionados abaixo mostram onde eles podem ser adicionados.

shib_request <uri> | OFF

Contexto: http , server , location

Padrão: off

Alterna o módulo de solicitação de autenticação Shibboleth e define o URI, que será solicitado a autorização. O URI configurado deve se referir a um bloco de localização nginx que aponta para o seu autorizador shibboleth fastcgi.

O status HTTP e os cabeçalhos da resposta resultantes da sub-requisição do URI configurado serão devolvidos ao usuário, de acordo com a especificação do autorizador fastcgi. A advertência (potencialmente significativa) é que, devido à maneira como o Nginx opera atualmente com relação aos sub -cestas (o que um autoridade exige efetivamente), o órgão de solicitação não será encaminhado ao autor e da mesma forma que o órgão de resposta do autor não será devolvido ao cliente.

Os URIs configurados não estão restritos ao uso de um back -end do FastCGI para gerar uma resposta, no entanto. Isso pode ser útil durante o teste ou de outra forma, pois você pode usar o Nginx's integrados em return e rewrite as diretrizes para produzir uma resposta adequada. Além disso, este módulo pode ser usado com qualquer autorizador FastCGI, embora a operação possa ser afetada pela ressalva acima.

Aviso

A diretiva shib_request não requer mais o sinalizador shib_authorizer . Isso deve ser removido para o início do nginx. Nenhuma outra alteração é necessária.

shib_request_set <variável> <Value>

Contexto: http , server , location

Padrão: none

Defina a variable para o value especificado após a conclusão da solicitação de autenticação. O value pode conter variáveis da resposta da solicitação de autenticação. Por exemplo, $upstream_http_* , $upstream_status e quaisquer outras variáveis mencionadas na documentação nginx_http_upstream_module.

Esta diretiva pode ser usada para introduzir atributos Shibboleth no ambiente do aplicativo de back -end, como $ _Server para um aplicativo FastCGI PHP e é o método recomendado de fazê -lo. Consulte a documentação de configuração para um exemplo.

shib_request_use_headers ON | OFF

Contexto: http , server , location

Padrão: off

Observação

Adicionado em v2.0.0.

Copie os atributos da resposta do autorizador Shibboleth para a solicitação principal como cabeçalhos, disponibilizando -os para servidores e aplicativos a montante. Use esta opção apenas se o seu upstream/aplicativo não suportar parâmetros do servidor via shib_request_set .

Com essa configuração ativada, os cabeçalhos de resposta do autorizador começando com Variable-* são extraídos, retirando a substring Variable- do nome do cabeçalho e copiados para a solicitação principal antes de ser enviada para o back-end. Por exemplo, um cabeçalho de resposta do autorizador, como Variable-Commonname: John Smith resultaria em Commonname: John Smith sendo adicionado à solicitação principal e, portanto, enviado ao back-end.

Cuidado com a falsificação - você deve garantir que seu aplicativo de back -end seja protegido contra injeção de cabeçalhos. Consulte o exemplo de configuração sobre como conseguir isso.

Instalação

Este módulo pode ser compilado estaticamente ou dinamicamente, uma vez que a introdução de módulos dinâmicos no Nginx 1.9.11. O resultado prático dos módulos dinâmicos é que eles podem ser carregados, em oposição aos módulos estáticos que estão permanentemente presentes e ativados.

A maneira mais fácil de obter uma versão embalada deste módulo é usar a ferramenta PKG-OSS do Nginx, que fornece embalagem de módulos dinâmicos para instalação ao lado dos lançamentos oficiais do NGINX dos principais repositórios e ajuda a evitar a necessidade de compilar o Nginx manualmente.

Caso contrário, para compilar o nginx com este módulo dinamicamente, passe a opção a seguir para ./configure ao criar o nginx:

 --Add-dinâmico-módulo = <TACH>

Você precisará carregar explicitamente o módulo em seu nginx.conf , incluindo:

 load_module /path/to/modules/ngx_http_shibboleth_module.so;

e recarregar ou reiniciar o nginx.

Para compilar o nginx com este módulo estaticamente, passe a opção a seguir para ./configure ao criar o nginx:

 --Add-Module = <tath>

Com uma construção estática, nenhuma carga adicional é necessária, pois o módulo está embutido no NGINX.

Configuração

Para obter detalhes completos sobre a configuração do ambiente Nginx/Shibboleth, consulte a documentação em https://github.com/nginxhhib/nginxh-httphhibboleth/blob/master/config.rst.

Um exemplo de bloco server consiste no seguinte:

 #FastCGI authorizer for Auth Request module
location = /shibauthorizer {
    internal ;
    include fastcgi_params;
    fastcgi_pass unix:/opt/shibboleth/shibauthorizer.sock;
}

#FastCGI responder
location /Shibboleth.sso {
    include fastcgi_params;
    fastcgi_pass unix:/opt/shibboleth/shibresponder.sock;
}

# Using the ``shib_request_set`` directive, we can introduce attributes as
# environment variables for the backend application. In this example, we
# set ``fastcgi_param`` but this could be any type of Nginx backend that
# supports parameters (by using the appropriate *_param option)
#
# The ``shib_fastcgi_params`` is an optional set of default parameters,
# available in the ``includes/`` directory in this repository.
#
# Choose this type of configuration unless your backend application
# doesn't support server parameters or specifically requires headers.
location /secure-environment-vars {
    shib_request /shibauthorizer;
    include shib_fastcgi_params;
    shib_request_set $shib_commonname $upstream_http_variable_commonname ;
    shib_request_set $shib_email $upstream_http_variable_email ;
    fastcgi_param COMMONNAME $shib_commonname ;
    fastcgi_param EMAIL $shib_email ;
    fastcgi_pass unix:/path/to/backend.socket;
}

# A secured location. All incoming requests query the Shibboleth FastCGI authorizer.
# Watch out for performance issues and spoofing!
#
# Choose this type of configuration for ``proxy_pass`` applications
# or backends that don't support server parameters.
location /secure {
    shib_request /shibauthorizer;
    shib_request_use_headers on;

    # Attributes from Shibboleth are introduced as headers by the FastCGI
    # authorizer so we must prevent spoofing. The
    # ``shib_clear_headers`` is a set of default header directives,
    # available in the `includes/` directory in this repository.
    include shib_clear_headers;

    # Add *all* attributes that your application uses, including all
    #variations.
    more_clear_input_headers 'displayName' 'mail' 'persistent-id' ;

    # This backend application will receive Shibboleth variables as request
    # headers (from Shibboleth's FastCGI authorizer)
    proxy_pass http://localhost:8080;
}

Observe que usamos os cabeçalhos-More-Nginx-Module para limpar os cabeçalhos de entrada potencialmente perigosos e evitar o potencial de falsificação. O último exemplo com variáveis de ambiente não é suscetível à falsificação do cabeçalho, desde que o back -end lê dados apenas dos parâmetros do ambiente.

Uma configuração padrão está disponível para limpar os cabeçalhos básicos do autorizador Shibboleth, mas você deve garantir que você escreva suas próprias diretivas claras para todos os atributos que seu aplicativo usa. Lembre -se de que alguns aplicativos tentarão ler um atributo shibboleth do ambiente e depois voltará aos cabeçalhos; portanto, revise o código do seu aplicativo, mesmo que você não esteja usando shib_request_use_headers .

Com o uso de shib_request_set , um arquivo PARAMS padrão está disponível que você pode usar como um NGINX include para garantir que todas as variáveis de shibboleth do núcleo sejam passadas do autorizador FastCGI para o aplicativo. Numerosos atributos padrão são incluídos, portanto, remova os que não são necessários pelo seu aplicativo e adicionam atributos da federação ou do IDP que você precisa. Esse arquivo params padrão pode ser reutilizado para a montante que não são fastcgi simplesmente alterando as diretivas fastcgi_param para uwsgi_param , scgi_param ou mais.

Botchas

Sub -festas, como a solicitação de autenticação Shibboleth, não são processadas por meio de filtros de cabeçalho. Isso significa que diretivas internas como add_header não funcionarão se configuradas como parte do bloco A /shibauthorizer . Se você precisar manipular os cabeçalhos de sub-requisição, use more_set_headers dos headers-more do módulo.
Consulte https://forum.nginx.org/read.php?29,257271,257272#msg-257272.

Comportamento

Este módulo segue a especificação do Autorizador Fastcgi sempre que possível, mas tem alguns desvios notáveis - por um bom motivo. O comportamento é assim:

Uma sub -referência do autorizador é composta por todos os aspectos da solicitação original, exceto o órgão de solicitação, pois o NGINX não suporta buffer dos órgãos de solicitação. Como o autor do shibboleth fastcgi não considera o órgão de solicitação, isso não é um problema.
Se um sub -calma autorizador retornar um status 200 , o acesso será permitido.
Se shib_request_use_headers estiver ativado, e os cabeçalhos de resposta começando com Variable-* forem extraídos, retirando a substring Variable- do nome do cabeçalho e copiaram para a solicitação principal. Outros cabeçalhos de resposta do autorizador não prefixados com Variable- e o corpo de resposta são ignorados. O FastCGI SPEC exige que os pares Variable-* nomes-valor sejam incluídos no ambiente FastCGI, mas os tornamos cabeçalhos para que possam ser usados com qualquer back-end (como proxy_pass ) e não apenas nos restringem a aplicativos FastCGI. Ao passar os dados Variable-* como cabeçalhos, acabamos seguindo o comportamento do ShibUseHeaders On no mod_shib para o Apache, que passa esses atributos do usuário como cabeçalhos.
Para passar os atributos como variáveis de ambiente (o equivalente ao ShibUseEnvironment On em mod_shib ), os atributos devem ser extraídos manualmente usando as diretivas shib_request_set para cada atributo. Isso não pode (atualmente) ser feito em massa para todos os atributos, pois cada back -end pode aceitar parâmetros de uma maneira diferente ( fastcgi_param , uwsgi_param etc). Solicitações de tração são bem -vindas para automatizar esse comportamento.
Se o Subrequest Authorizer retornar qualquer outro status (incluindo redirecionamentos ou erros), o status e os cabeçalhos do autorizador serão devolvidos ao cliente.
Isso significa que, no 401 Unauthorized ou 403 Forbidden , o acesso será negado e os cabeçalhos (como WWW-Authenticate ) do autoridade serão passados para o cliente. Todas as outras respostas do autorizador (como redirecionamentos 3xx ) são transmitidas de volta ao cliente, incluindo status e cabeçalhos, permitindo redirecionamentos como os do Wayf Pages e o Shibboleth Responder ( Shibboleth.sso ) funcionar corretamente.
O FastCGI Authorizer Spec exige que o órgão de resposta seja devolvido ao cliente, mas como o NGINX atualmente não suporta respostas de sub -calma buffer ( NGX_HTTP_SUBREQUEST_IN_MEMORY ), o corpo de resposta do autorizador é efetivamente ignorado. Uma solução alternativa é fazer com que o Nginx sirva uma error_page , assim:
```
 location /secure {
   shib_request /shibauthorizer;
   error_page 403 /shibboleth-forbidden.html;
   ...
}
```
Isso serve à página de erro fornecida se o autorizador Shibboleth negar ao usuário acesso a este local. Sem error_page especificado, o Nginx servirá suas páginas de erro genéricas.
Observe que isso não se aplica ao respondedor Shibboleth (normalmente hospedado em Shibboleth.sso ), pois é um respondente fastcgi e o nginx é totalmente compatível com isso, pois não são usados sub -referências.
Para mais detalhes, consulte https://forum.nginx.org/read.php?2,238444,238453.

Embora este módulo seja voltado especificamente para o autor do fastcgi de Shibboleth, provavelmente funcionará com outros autorizadores, tendo em mente os desvios da especificação acima.

Testes

Os testes são executados automaticamente em ações do GitHub (usando essa configuração) sempre que novas confirmações são feitas no repositório ou quando novas solicitações de tração são abertas. Se algo quebrar, você será informado e os resultados serão relatados no GitHub.

Os testes são gravados usando uma combinação de um script simples de bash para compilação do nosso módulo com diferentes versões e configurações do Nginx e o teste :: NGINX PERL Teste andaime para testes de integração. Consulte o link anterior para obter informações sobre como estender os testes e também consulte o teste subjacente :: documentação base sobre aspectos como a função Blocks ().

Os testes de integração são executados automaticamente pelo CI, mas também podem ser executados manualmente (exige que o Perl & cpan seja instalado):

 cd nginx-http-shibboleth
cpanm --notest --local-lib= $HOME /perl5 Test::Nginx
# nginx must be present in PATH and built with debugging symbols
PERL5LIB= $HOME /perl5/lib/perl5 prove

Ajuda e suporte

As solicitações de suporte para a configuração do Shibboleth e a configuração do NGINX ou do servidor da Web devem ser direcionadas para a lista de discussão dos usuários da comunidade Shibboleth. Consulte https://www.shibboleth.net/community/lists/ para obter detalhes.

Depuração

Devido à natureza complexa da pilha nginx/fastcgi/shibboleth, problemas de configuração de depuração podem ser difíceis. Aqui estão alguns pontos -chave:

Confirme que nginx-http-shibboleth é construído e instalado com sucesso no Nginx. Você pode verificar executando nginx -V e inspecionando a saída para --add-module=[path]/nginx-http-shibboleth ou --add-dynamic-module=[path]/nginx-http-shibboleth .
Se estiver usando módulos dinâmicos para NGINX, confirme que você usou a diretiva load_module para carregar este módulo. Seu uso de shib_request e outras diretrizes falhará se você tiver esquecido de carregar o módulo.
Se estiver usando uma versão do Nginx diferente daqueles com quem testamos ou se você estiver usando outros módulos de terceiros, execute o conjunto de testes acima para confirmar a compatibilidade. Se algum teste falhar, verifique sua configuração ou considere atualizar sua versão nginx.
Configuração do Shibboleth: verifique seu shibboleth2.xml e configuração associada para garantir que seus hosts, caminhos e atributos estejam sendo liberados corretamente. Um exemplo de configuração pode ajudá -lo a identificar os principais "gotchas" para configurar shibboleth2.xml para trabalhar com o autorizador fastcgi.
Nível do aplicativo: dentro do seu código, sempre comece com a saída de depuração mais simples possível (como imprimir o ambiente de solicitação) e trabalhe a partir daí. Se você deseja criar um aplicativo básico e independente, dê uma olhada na configuração da garrafa no wiki.
Módulo de depuração Interna: se você verificou cuidadosamente tudo o que foi acima, também poderá depurar o comportamento deste módulo em si. Você precisará ter compilado o nginx com suporte de depuração (via ./auto/configure --with-debug ... ) e ao executar o nginx, é mais fácil se você é capaz de executar em primeiro plano com o log de depuração ativado. Adicione o seguinte ao seu nginx.conf :
```
 daemon off ;
error_log stderr debug ;
```
e execute nginx. Ao iniciar o NGINX, você deve ver linhas contendo [Debug] e, ao fazer solicitações, o registro do console continuará. Se isso não acontecer, verifique seu processo de configuração e compilação NGINX.
Quando você eventualmente faz uma solicitação que atinge (ou deve invocar) o bloco de localização shib_request , você verá linhas como assim na saída:
```
[debug] 1234 #0: shib request handler
[debug] 1234 #0: shib request set variables
[debug] 1234 #0: shib request authorizer handler
[debug] 1234 #0: shib request authorizer allows access
[debug] 1234 #0: shib request authorizer copied header: "AUTH_TYPE: shibboleth"
[debug] 1234 #0: shib request authorizer copied header: "REMOTE_USER: [email protected]"
...
```
Se você não vir esses tipos de linhas que contêm a solicitação de shib ... ou se você vir algumas das linhas acima, mas não onde os cabeçalhos/variáveis estão sendo copiados, verifique novamente sua configuração nginx. Se você ainda não está chegando a lugar algum, poderá adicionar suas próprias linhas de depuração à fonte (siga os exemplos deste módulo) para determinar o que está dando errado e quando. Se fizer isso, não se esqueça de recompilar o nginx e/ou nginx-http-shibboleth sempre que fizer uma alteração.