nginx http shibboleth
v2.0.2
Este módulo permite que NGINX funcione con Shibboleth, a través del autorizador FastCGI de Shibboleth. Este módulo requiere una configuración específica para funcionar correctamente, así como la aplicación Autorizador FastCGI de Shibboleth disponible en el sistema. Su objetivo es ser similar a las partes del mod_shib de Apache, aunque la configuración de autorización y autenticación de Shibboleth se configuran a través de shibboleth2.xml en lugar de en la configuración del servidor web.
Con este módulo configurado en un bloque location , las solicitudes entrantes están autorizadas dentro de NGINX en función del resultado de una subrequest para el autorizador FastCGI de Shibboleth. En este proceso, este módulo se puede utilizar para copiar atributos del usuario de una respuesta de autorizador exitosa a la solicitud original de Nginx como encabezados o parámetros de entorno para su uso de cualquier aplicación de backend. Si la autorización no es exitosa, el estado de respuesta del autorizador y los encabezados se devuelven al cliente, negando el acceso o redirigir el navegador del usuario en consecuencia (como a una página de Wayf, si es así configurada).
Este módulo funciona en la fase de acceso y, por lo tanto, se puede combinar con otros módulos de acceso (como access , auth_basic ) a través de la Directiva satisfy . Este módulo también se puede compilar junto con ngx_http_auth_request_module , aunque el uso de ambos módulos en el mismo bloque location no se ha probado y no se recomienda.
Lea más sobre el comportamiento a continuación y consulte la configuración para obtener notas importantes sobre cómo evitar la suplantación de suplementación si usa encabezados para atributos.
Para obtener más información sobre por qué este es un módulo dedicado, consulte https://forum.nginx.org/read.php?2,238523,238523#MSG-238523
Las siguientes directivas se agregan a sus archivos de configuración NGINX. Los contextos mencionados a continuación muestran dónde se pueden agregar.
http , server , locationoffCambia el módulo de solicitud de Auth Shibboleth y establece URI que se le pedirá autorización. El URI configurado debe referirse a un bloque de ubicación NGINX que apunta a su autorizador de Shibboleth Fastcgi.
El estado HTTP y los encabezados de la respuesta resultante de la subrequest al URI configurado se devolverán al usuario, de acuerdo con la especificación del autorizador FastCGI. La única advertencia (potencialmente significativa) es que, debido a la forma en que Nginx opera actualmente con respecto a las subrequests (lo que un autorizador requiere efectivamente), el cuerpo de solicitud no se enviará al autorizador y, de manera similar, el cuerpo de respuesta del autorizador no se devolverá al cliente.
Sin embargo, los URI configurados no están restringidos al uso de un backend fastCGI para generar una respuesta. Esto puede ser útil durante las pruebas o de otra manera, ya que puede usar las directivas construidas de Nginx a return y rewrite para producir una respuesta adecuada. Además, este módulo puede usarse con cualquier autorizador FastCGI, aunque la operación puede verse afectada por la advertencia anterior.
Advertencia
La Directiva shib_request ya no requiere la bandera shib_authorizer . Esto debe eliminarse para que Nginx comience. No se requieren otros cambios.
http , server , locationnone Establezca la variable en el value especificado después de que se haya completado la solicitud de Auth. El value puede contener variables de la respuesta de la solicitud de autenticación. Por ejemplo, $upstream_http_* , $upstream_status y cualquier otra variable mencionada en la documentación nginx_htp_upstream_module.
Esta directiva se puede utilizar para introducir atributos de Shibboleth en el entorno de la aplicación de backend, como $ _server para una aplicación FastCGI PHP y es el método recomendado para hacerlo. Consulte la documentación de configuración para obtener un ejemplo.
http , server , locationoffNota
Agregado en v2.0.0.
Copie los atributos de la respuesta del autor de Shibboleth en la solicitud principal como encabezados, haciéndolos disponibles para servidores y aplicaciones aguas arriba. Use esta opción solo si su aplicación Upstream/no admite los parámetros del servidor a través de shib_request_set .
Con esta configuración habilitada, los encabezados de respuesta del autor, que comienzan con Variable-* se extraen, eliminan la subcadena Variable- del nombre del encabezado y se copian en la solicitud principal antes de que se envíe al backend. Por ejemplo, un encabezado de respuesta autorizador, como Variable-Commonname: John Smith daría lugar al Commonname: John Smith se agrega a la solicitud principal y, por lo tanto, se envía al backend.
Tenga cuidado con la suplantación : debe asegurarse de que su aplicación de backend esté protegida de la inyección de encabezados. Consulte el ejemplo de configuración sobre cómo lograr esto.
Este módulo se puede compilar de manera estadí o dinámica, ya que la introducción de módulos dinámicos en Nginx 1.9.11. El resultado práctico de los módulos dinámicos es que se pueden cargar, a diferencia de los módulos estáticos que están permanentemente presentes y habilitados.
La forma más fácil de obtener una versión empaquetada de este módulo es utilizar la herramienta PKG-oss de NGINX, que proporciona el empaque de módulos dinámicos para la instalación junto con las versiones oficiales de Nginx de los repositorios principales y ayuda a evitar la necesidad de compilar NGINX a mano.
De lo contrario, para compilar nginx con este módulo dinámicamente, pase la siguiente opción a ./configure al construir nginx:
--Add-Dynamic-Module = <Phath>
Deberá cargar explícitamente el módulo en su nginx.conf incluyendo:
load_module /path/to/modules/ngx_http_shibboleth_module.so;
y recargar o reiniciar Nginx.
Para compilar nginx con este módulo estáticamente, pase la siguiente opción a ./configure al construir nginx:
--Add-Module = <Phath>
Con una compilación estática, no se requiere carga adicional ya que el módulo está incorporado a Nginx.
Para obtener detalles completos sobre la configuración del entorno Nginx/Shibboleth, consulte la documentación en https://github.com/nginx-shib/nginx-http-shibboleth/blob/master/config.rst.
Un bloque de ejemplo server consta de lo siguiente:
#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;
}Tenga en cuenta que usamos los encabezados-Módulo-Módulo-Nginx para eliminar los encabezados de entrada potencialmente peligrosos y evitar el potencial de falsificación. El último ejemplo con variables de entorno no es susceptible a la falsificación de encabezados, siempre que el backend solo lea datos de los parámetros del entorno.
Una configuración predeterminada está disponible para borrar los encabezados básicos del autorizador de Shibboleth, pero debe asegurarse de escribir sus propias directivas claras para todos los atributos que usa su aplicación. Tenga en cuenta que algunas aplicaciones intentarán leer un atributo Shibboleth del entorno y luego recurrir a los encabezados, así que revise el código de su aplicación incluso si no está utilizando shib_request_use_headers .
Con el uso de shib_request_set , hay un archivo de parámetros predeterminado disponible que puede usar como un NGINX include para garantizar que todas las variables de Shibboleth núcleos pasen del autorizador FastCGI a la aplicación. Se incluyen numerosos atributos predeterminados, así que elimine los que su aplicación no requiere y agregue los atributos de federación o IDP que necesita. Este archivo de parámetros predeterminado se puede reutilizar para los transmisiones ascendentes que no son FASTCGI simplemente cambiando las directivas fastcgi_param a uwsgi_param , scgi_param OR.
Las subrequests, como la solicitud de autenticación Shibboleth, no se procesan a través de filtros de encabezado. Esto significa que las directivas incorporadas como add_header no funcionarán si se configuran como parte del bloque A /shibauthorizer . Si necesita manipular los encabezados de subrequest, use more_set_headers de los headers-more .
Ver https://forum.nginx.org/read.php?29,257271,257272#MSG-257272.
Este módulo sigue la especificación de autorizador FastCGI cuando sea posible, pero tiene algunas desviaciones notables, con una buena razón. El comportamiento es así:
Un subrequest autorizador se compone de todos los aspectos de la solicitud original, excepto el cuerpo de solicitud ya que NGINX no admite el almacenamiento en búfer de los cuerpos de solicitud. Como el autorizador de Shibboleth Fastcgi no considera el cuerpo de solicitud, este no es un problema.
Si un subrequest del autor devuelve un estado 200 , se permite el acceso.
Si shib_request_use_headers está habilitado, y los encabezados de respuesta que comienzan con Variable-* se extraen, eliminando la subcadena Variable- del nombre del encabezado y se copia en la solicitud principal. Otros encabezados de respuesta autorizador no están prefijados con Variable- y el cuerpo de respuesta se ignoran. La especificación FASTCGI requiere que los pares de valor de nombre Variable-* se incluyan en el entorno FastCGI, pero los hacemos encabezados, ya que pueden usarse con cualquier backend (como proxy_pass ) y no solo restringirnos a las aplicaciones FASTCGI. Al pasar los datos Variable-* como encabezados, terminamos siguiendo el comportamiento de ShibUseHeaders On en mod_shib para Apache, que pasa estos atributos de usuario como encabezados.
Para aprobar atributos como variables de entorno (el equivalente a ShibUseEnvironment On mod_shib ), los atributos deben extraerse manualmente utilizando directivas shib_request_set para cada atributo. Esto no se puede hacer (actualmente) en masa para todos los atributos, ya que cada backend puede aceptar parámetros de una manera diferente ( fastcgi_param , uwsgi_param , etc.). Las solicitudes de extracción son bienvenidas para automatizar este comportamiento.
Si el subrequest del autor devuelve cualquier otro estado (incluidas las redirecciones o errores), el estado y los encabezados de la respuesta del autorizador se devuelven al cliente.
Esto significa que en 401 Unauthorized o 403 Forbidden , el acceso será denegado y los encabezados (como WWW-Authenticate ) del autorizador se pasarán al cliente. Todas las demás respuestas autorizador (como las redirecciones 3xx ) se transmiten al cliente, incluidos el estado y los encabezados, lo que permite redirecciones como las que las páginas de Wayf y el respondedor de shibboleth ( Shibboleth.sso ) funcionan correctamente.
La especificación del autorizador de FastCGI requiere que el cuerpo de respuesta se devuelva al cliente, pero como Nginx actualmente no admite las respuestas de subrequest de amortiguación ( NGX_HTTP_SUBREQUEST_IN_MEMORY ), el cuerpo de respuesta del autorizador se ignora efectivamente. Una solución es hacer que Nginx sirva un error_page propio, como así:
location /secure {
shib_request /shibauthorizer;
error_page 403 /shibboleth-forbidden.html;
...
} Esto sirve a la página de error dada si el autorizador de Shibboleth niega el acceso del usuario a esta ubicación. Sin error_page especificado, NGINX cumplirá sus páginas de error genéricos.
Tenga en cuenta que esto no se aplica al respondedor de shibboleth (generalmente alojado en Shibboleth.sso ), ya que es un respondedor FastCGI y Nginx es completamente compatible con esto, ya que no se usan subrequests.
Para más detalles, consulte https://forum.nginx.org/read.php?2,2384444,238453.
Si bien este módulo está dirigido específicamente para el autorizador FastCGI de Shibboleth, es probable que funcione con otros autorizadores, teniendo en cuenta las desviaciones de las especificaciones anteriores.
Las pruebas se ejecutan automáticamente en acciones de GitHub (usando esta configuración) cada vez que se realizan nuevas confirmaciones en el repositorio o cuando se abren nuevas solicitudes de extracción. Si algo se rompe, se le informará y los resultados se informarán en GitHub.
Las pruebas se escriben utilizando una combinación de un script bash simple para la compilación de nuestro módulo con diferentes versiones y configuraciones de Nginx y el andamio de prueba de prueba :: Nginx Perl para pruebas de integración. Consulte el enlace anterior para obtener información sobre cómo extender las pruebas, y también consulte la documentación de la prueba subyacente :: Base en aspectos como la función BLOCKS ().
Las pruebas de integración se ejecutan automáticamente por CI, pero también se pueden ejecutar manualmente (requiere que se instale Perl & CPAN):
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 proveLas solicitudes de soporte para la configuración de Shibboleth y la configuración de Nginx o del servidor web deben dirigirse a la lista de correo de los usuarios de la comunidad de Shibboleth. Consulte https://www.shibboleth.net/community/lists/ para más detalles.
Debido a la naturaleza compleja de la pila NGINX/FASTCGI/Shibboleth, los problemas de configuración de depuración pueden ser difíciles. Aquí hay algunos puntos clave:
Confirme que nginx-http-shibboleth se construye e instala con éxito dentro de Nginx. Puede verificar ejecutando nginx -V e inspeccionar la salida para --add-module=[path]/nginx-http-shibboleth o --add-dynamic-module=[path]/nginx-http-shibboleth .
Si usa módulos dinámicos para NGINX, confirme que ha utilizado la directiva load_module para cargar este módulo. Su uso de shib_request y otras directivas fallarán si ha olvidado cargar el módulo.
Si usa una versión de Nginx que es diferente a las que probamos o si está utilizando otros módulos de terceros, debe ejecutar el conjunto de pruebas anterior para confirmar la compatibilidad. Si alguna prueba falla, verifique su configuración o considere actualizar su versión Nginx.
Configuración de Shibboleth: verifique su shibboleth2.xml y la configuración asociada para garantizar que sus hosts, rutas y atributos se liberen correctamente. Una configuración de ejemplo puede ayudarlo a identificar la clave "gotchas" para configurar shibboleth2.xml para funcionar con el autorizador FastCGI.
Level de aplicación: dentro de su código, siempre comience con la salida de depuración más simple posible (como imprimir el entorno de solicitud) y trabaje desde allí. Si desea crear una aplicación básica y independiente, eche un vistazo a la configuración de la botella en el wiki.
El módulo de depuración de módulos internales: si ha revisado cuidadosamente todo lo anterior, también puede depurar el comportamiento de este módulo en sí. Deberá haber compilado a Nginx con soporte de depuración (a través de ./auto/configure --with-debug ... ) y al ejecutar Nginx, es más fácil si puede ejecutar en primer plano con registro de depuración habilitado. Agregue lo siguiente a su nginx.conf :
daemon off ;
error_log stderr debug ;y ejecutar nginx. Al iniciar Nginx, debe ver líneas que contienen [depuración] y, a medida que realice solicitudes, continuará el registro de consolas. Si esto no sucede, verifique su proceso de configuración y compilación de Nginx.
Cuando eventualmente realiza una solicitud que golpea (o debe invocar) el bloque de ubicación shib_request , verá líneas como en la salida:
[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]"
... Si no ve este tipo de líneas que contienen la solicitud SHIB ..., o si ve algunas de las líneas anteriores, pero no donde se copian encabezados/variables, luego verifique su configuración de Nginx. Si todavía no está llegando a ninguna parte, puede agregar sus propias líneas de depuración a la fuente (siga los ejemplos de este módulo) para determinar eventualmente qué está pasando mal y cuándo. Si hace esto, no olvide recompilar Nginx y/o nginx-http-shibboleth siempre que realice un cambio.
Si cree que ha encontrado un error en el código del módulo central, cree un problema.
También puede buscar problemas existentes, ya que es probable que alguien más haya encontrado un problema similar antes.
Este módulo utiliza versiones semánticas y todas las versiones están etiquetadas en GitHub, que permite descargas de paquetes de etiquetas individuales.
Este proyecto tiene licencia bajo la misma licencia que es Nginx, la licencia similar a BSD de 2 cláusulas.
