{"id":13719957,"url":"https://github.com/nginx-shib/nginx-http-shibboleth","last_synced_at":"2025-09-10T19:03:20.964Z","repository":{"id":21971718,"uuid":"25296507","full_name":"nginx-shib/nginx-http-shibboleth","owner":"nginx-shib","description":"Shibboleth auth request module for nginx","archived":false,"fork":false,"pushed_at":"2023-05-26T13:19:14.000Z","size":157,"stargazers_count":209,"open_issues_count":2,"forks_count":27,"subscribers_count":24,"default_branch":"master","last_synced_at":"2024-11-14T09:39:02.834Z","etag":null,"topics":["authentication","c","hacktoberfest","nginx","saml2","shibboleth","sso","web"],"latest_commit_sha":null,"homepage":"https://github.com/nginx-shib/nginx-http-shibboleth/wiki","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nginx-shib.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-10-16T10:02:55.000Z","updated_at":"2024-07-16T16:42:13.000Z","dependencies_parsed_at":"2024-06-21T14:18:13.792Z","dependency_job_id":"5383d231-a4c7-4c34-bb4f-03464ae83c48","html_url":"https://github.com/nginx-shib/nginx-http-shibboleth","commit_stats":{"total_commits":151,"total_committers":5,"mean_commits":30.2,"dds":0.06622516556291391,"last_synced_commit":"ebd59e372ee8537e058e56fab6759d65629c8f98"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx-shib%2Fnginx-http-shibboleth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx-shib%2Fnginx-http-shibboleth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx-shib%2Fnginx-http-shibboleth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx-shib%2Fnginx-http-shibboleth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nginx-shib","download_url":"https://codeload.github.com/nginx-shib/nginx-http-shibboleth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252876276,"owners_count":21818155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","c","hacktoberfest","nginx","saml2","shibboleth","sso","web"],"created_at":"2024-08-03T01:00:58.188Z","updated_at":"2025-05-07T12:30:30.437Z","avatar_url":"https://github.com/nginx-shib.png","language":"C","funding_links":[],"categories":["C","Authentication"],"sub_categories":[],"readme":"Shibboleth auth request module for Nginx\n========================================\n\n.. image:: https://github.com/nginx-shib/nginx-http-shibboleth/actions/workflows/build.yml/badge.svg\n   :target: https://github.com/nginx-shib/nginx-http-shibboleth/actions/workflows/build.yml\n\nThis module allows Nginx to work with Shibboleth, by way of Shibboleth's\nFastCGI authorizer.  This module requires specific configuration in order to\nwork correctly, as well as Shibboleth's FastCGI authorizer application\navailable on the system.  It aims to be similar to parts of Apache's\n`mod_shib`_, though Shibboleth authorisation and authentication settings are\nconfigured via `shibboleth2.xml`_ rather than in the web server configuration.\n\nWith this module configured against a ``location`` block, incoming requests\nare authorized within Nginx based upon the result of a subrequest to\nShibboleth's FastCGI authorizer.  In this process, this module can be used to\ncopy user attributes from a successful authorizer response into Nginx's\noriginal request as headers or environment parameters for use by any backend\napplication.  If authorization is not successful, the authorizer response\nstatus and headers are returned to the client, denying access or redirecting\nthe user's browser accordingly (such as to a WAYF page, if so configured).\n\nThis module works at access phase and therefore may be combined with other\naccess modules (such as ``access``, ``auth_basic``) via the ``satisfy``\ndirective.  This module can be also compiled alongside\n``ngx_http_auth_request_module``, though use of both of these modules in the\nsame ``location`` block is untested and not advised.\n\nRead more about the `Behaviour`_ below and consult `Configuration`_ for\nimportant notes on avoiding spoofing if using headers for attributes.\n\nFor further information on why this is a dedicated module, see\nhttps://forum.nginx.org/read.php?2,238523,238523#msg-238523\n\nDirectives\n----------\n\nThe following directives are added into your Nginx configuration files. The\ncontexts mentioned below show where they may be added.\n\n\nshib_request \u003curi\u003e|off\n   | **Context:** ``http``, ``server``, ``location``\n   | **Default:** ``off``\n\n   Switches the Shibboleth auth request module on and sets URI which will be\n   asked for authorization.  The configured URI should refer to a Nginx\n   location block that points to your Shibboleth FastCGI authorizer.\n\n   The HTTP status and headers of the response resulting\n   from the sub-request to the configured URI will be returned to the user,\n   in accordance with the `FastCGI Authorizer specification`_.\n   The one (potentially significant) caveat is that due to the way\n   Nginx operates at present with regards to subrequests (what\n   an Authorizer effectively requires), the request body will *not* be\n   forwarded to the authorizer, and similarly, the response body from\n   the authorizer will *not* be returned to the client.\n\n   Configured URIs are not restricted to using a FastCGI backend\n   to generate a response, however.  This may be useful during\n   testing or otherwise, as you can use Nginx's built in ``return``\n   and ``rewrite`` directives to produce a suitable response.\n   Additionally, this module may be used with *any* FastCGI\n   authorizer, although operation may be affected by the above caveat.\n\n   .. warning::\n\n      The ``shib_request`` directive no longer requires the ``shib_authorizer``\n      flag.  This must be removed for Nginx to start. No other changes are\n      required.\n\nshib_request_set \u003cvariable\u003e \u003cvalue\u003e\n   | **Context:** ``http``, ``server``, ``location``\n   | **Default:** ``none``\n\n   Set the ``variable`` to the specified ``value`` after the auth request has\n   completed. The ``value`` may contain variables from the auth request's\n   response.  For instance, ``$upstream_http_*``, ``$upstream_status``, and\n   any other variables mentioned in the `nginx_http_upstream_module\n   \u003chttps://nginx.org/en/docs/http/ngx_http_upstream_module.html#variables\u003e`_\n   documentation.\n\n   This directive can be used to introduce Shibboleth attributes into the\n   environment of the backend application, such as `$_SERVER` for a FastCGI\n   PHP application and is the recommended method of doing so.  See the\n   `Configuration`_ documentation for an example.\n\nshib_request_use_headers on|off\n   | **Context:** ``http``, ``server``, ``location``\n   | **Default:** ``off``\n\n   .. note::\n\n      Added in v2.0.0.\n\n   Copy attributes from the Shibboleth authorizer response into the main\n   request as headers, making them available to upstream servers and\n   applications. Use this option only if your upstream/application does not\n   support server parameters via ``shib_request_set``.\n\n   With this setting enabled, Authorizer response headers beginning with\n   ``Variable-\\*`` are extracted, stripping the ``Variable-`` substring from\n   the header name, and copied into the main request before it is sent to the\n   backend. For example, an authorizer response header such as\n   ``Variable-Commonname: John Smith`` would result in ``Commonname: John\n   Smith`` being added to the main request, and thus sent to the backend.\n\n   **Beware of spoofing** - you must ensure that your backend application is\n   protected from injection of headers. Consult the `Configuration`_ example\n   on how to achieve this.\n\n\nInstallation\n------------\n\nThis module can either be compiled statically or dynamically, since the\nintroduction of `dynamic modules\n\u003chttps://www.nginx.com/resources/wiki/extending/converting/\u003e`_ in Nginx\n1.9.11.  The practical upshot of dynamic modules is that they can be loaded,\nas opposed to static modules which are permanently present and enabled.\n\nThe easiest way to obtain a packaged version of this module is to use the\n`pkg-oss \u003chttps://hg.nginx.org/pkg-oss/\u003e`_ tool from Nginx, which provides for\npackaging of dynamic modules for installation alongside the official releases\nof Nginx from the `main repositories \u003chttps://nginx.org/en/download.html\u003e`_\nand helps avoid the need to compile Nginx by hand.\n\nOtherwise, to compile Nginx with this module dynamically, pass the following\noption to ``./configure`` when building Nginx::\n\n    --add-dynamic-module=\u003cpath\u003e\n\nYou will need to explicitly load the module in your ``nginx.conf`` by\nincluding::\n\n    load_module /path/to/modules/ngx_http_shibboleth_module.so;\n\nand reload or restart Nginx.\n\nTo compile Nginx with this module statically, pass the following option to\n``./configure`` when building Nginx::\n\n    --add-module=\u003cpath\u003e\n\nWith a static build, no additional loading is required as the module is\nbuilt-in to Nginx.\n\n\nConfiguration\n-------------\n\nFor full details about configuring the Nginx/Shibboleth environment,\nsee the documentation at\nhttps://github.com/nginx-shib/nginx-http-shibboleth/blob/master/CONFIG.rst.\n\nAn example ``server`` block consists of the following:\n\n.. code-block:: nginx\n\n    #FastCGI authorizer for Auth Request module\n    location = /shibauthorizer {\n        internal;\n        include fastcgi_params;\n        fastcgi_pass unix:/opt/shibboleth/shibauthorizer.sock;\n    }\n\n    #FastCGI responder\n    location /Shibboleth.sso {\n        include fastcgi_params;\n        fastcgi_pass unix:/opt/shibboleth/shibresponder.sock;\n    }\n\n    # Using the ``shib_request_set`` directive, we can introduce attributes as\n    # environment variables for the backend application. In this example, we\n    # set ``fastcgi_param`` but this could be any type of Nginx backend that\n    # supports parameters (by using the appropriate *_param option)\n    #\n    # The ``shib_fastcgi_params`` is an optional set of default parameters,\n    # available in the ``includes/`` directory in this repository.\n    #\n    # Choose this type of configuration unless your backend application\n    # doesn't support server parameters or specifically requires headers.\n    location /secure-environment-vars {\n        shib_request /shibauthorizer;\n        include shib_fastcgi_params;\n        shib_request_set $shib_commonname $upstream_http_variable_commonname;\n        shib_request_set $shib_email $upstream_http_variable_email;\n        fastcgi_param COMMONNAME $shib_commonname;\n        fastcgi_param EMAIL $shib_email;\n        fastcgi_pass unix:/path/to/backend.socket;\n    }\n\n    # A secured location. All incoming requests query the Shibboleth FastCGI authorizer.\n    # Watch out for performance issues and spoofing!\n    #\n    # Choose this type of configuration for ``proxy_pass`` applications\n    # or backends that don't support server parameters.\n    location /secure {\n        shib_request /shibauthorizer;\n        shib_request_use_headers on;\n\n        # Attributes from Shibboleth are introduced as headers by the FastCGI\n        # authorizer so we must prevent spoofing. The\n        # ``shib_clear_headers`` is a set of default header directives,\n        # available in the `includes/` directory in this repository.\n        include shib_clear_headers;\n\n        # Add *all* attributes that your application uses, including all\n        #variations.\n        more_clear_input_headers 'displayName' 'mail' 'persistent-id';\n\n        # This backend application will receive Shibboleth variables as request\n        # headers (from Shibboleth's FastCGI authorizer)\n        proxy_pass http://localhost:8080;\n    }\n\nNote that we use the `headers-more-nginx-module\n\u003chttps://github.com/openresty/headers-more-nginx-module\u003e`_ to clear\npotentially dangerous input headers and avoid the potential for spoofing.  The\nlatter example with environment variables isn't susceptible to header\nspoofing, as long as the backend reads data from the environment parameters\n**only**.\n\nA `default configuration\n\u003chttps://github.com/nginx-shib/nginx-http-shibboleth/blob/master/includes/shib_clear_headers\u003e`_\nis available to clear the basic headers from the Shibboleth authorizer, but\nyou must ensure you write your own clear directives for all attributes your\napplication uses.  Bear in mind that some applications will try to read a\nShibboleth attribute from the environment and then fall back to headers, so\nreview your application's code even if you are not using\n``shib_request_use_headers``.\n\n\nWith use of ``shib_request_set``, a `default params\n\u003chttps://github.com/nginx-shib/nginx-http-shibboleth/blob/master/includes/shib_fastcgi_params\u003e`_\nfile is available which you can use as an nginx ``include`` to ensure all core\nShibboleth variables get passed from the FastCGI authorizer to the\napplication. Numerous default attributes are included so remove the ones that\naren't required by your application and add Federation or IDP attributes that\nyou need. This default params file can be re-used for upstreams that aren't\nFastCGI by simply changing the ``fastcgi_param`` directives to\n``uwsgi_param``, ``scgi_param`` or so forth.\n\nGotchas\n~~~~~~~\n\n* Subrequests, such as the Shibboleth auth request, aren't processed through header filters.\n  This means that built-in directives like ``add_header`` will **not** work if configured\n  as part of the a ``/shibauthorizer`` block.  If you need to manipulate subrequest headers,\n  use ``more_set_headers`` from the module ``headers-more``.\n\n  See https://forum.nginx.org/read.php?29,257271,257272#msg-257272.\n\nBehaviour\n---------\n\nThis module follows the `FastCGI Authorizer specification`_ where possible,\nbut has some notable deviations - with good reason.  The behaviour is thus:\n\n* An authorizer subrequest is comprised of all aspects of the original\n  request, excepting the request body as Nginx does not support buffering of\n  request bodies.  As the Shibboleth FastCGI authorizer does not consider the\n  request body, this is not an issue.\n\n* If an authorizer subrequest returns a ``200`` status, access is allowed.\n\n  If ``shib_request_use_headers`` is enabled, and response headers beginning\n  with ``Variable-\\*`` are extracted, stripping the ``Variable-`` substring\n  from the header name, and copied into the main request.  Other authorizer\n  response headers not prefixed with ``Variable-`` and the response body are\n  ignored.  The FastCGI spec calls for ``Variable-*`` name-value pairs to be\n  included in the FastCGI environment, but we make them headers so as they may\n  be used with *any* backend (such as ``proxy_pass``) and not just restrict\n  ourselves to FastCGI applications.  By passing the ``Variable-*`` data as\n  headers instead, we end up following the behaviour of ``ShibUseHeaders On``\n  in ``mod_shib`` for Apache, which passes these user attributes as headers.\n\n  In order to pass attributes as environment variables (the equivalent to\n  ``ShibUseEnvironment On`` in ``mod_shib``), attributes must be manually\n  extracted using ``shib_request_set`` directives for each attribute.  This\n  cannot (currently) be done *en masse* for all attributes as each backend may\n  accept parameters in a different way (``fastcgi_param``, ``uwsgi_param``\n  etc).  Pull requests are welcome to automate this behaviour.\n\n* If the authorizer subrequest returns *any* other status (including redirects\n  or errors), the authorizer response's status and headers are returned to the\n  client.\n\n  This means that on ``401 Unauthorized`` or ``403 Forbidden``, access will be\n  denied and headers (such as ``WWW-Authenticate``) from the authorizer will be\n  passed to client.  All other authorizer responses (such as ``3xx``\n  redirects) are passed back to the client, including status and headers,\n  allowing redirections such as those to WAYF pages and the Shibboleth\n  responder (``Shibboleth.sso``) to work correctly.\n\n  The FastCGI Authorizer spec calls for the response body to be returned to\n  the client, but as Nginx does not currently support buffering subrequest\n  responses (``NGX_HTTP_SUBREQUEST_IN_MEMORY``), the authorizer response body\n  is effectively ignored.  A workaround is to have Nginx serve an\n  ``error_page`` of its own, like so:\n\n  .. code-block:: nginx\n\n      location /secure {\n         shib_request /shibauthorizer;\n         error_page 403 /shibboleth-forbidden.html;\n         ...\n      }\n\n  This serves the given error page if the Shibboleth authorizer denies the\n  user access to this location.  Without ``error_page`` specified, Nginx will\n  serve its generic error pages.\n\n  Note that this does *not* apply to the Shibboleth responder (typically hosted at\n  ``Shibboleth.sso``) as it is a FastCGI responder and Nginx is fully compatible\n  with this as no subrequests are used.\n\n  For more details, see https://forum.nginx.org/read.php?2,238444,238453.\n\nWhilst this module is geared specifically for Shibboleth's FastCGI authorizer,\nit will likely work with other authorizers, bearing in mind the deviations\nfrom the spec above.\n\nTests\n-----\n\nTests are automatically run on GitHub Actions (using `this configuration\n\u003chttps://github.com/nginx-shib/nginx-http-shibboleth/blob/master/.github/workflows/build.yml\u003e`_)\nwhenever new commits are made to the repository or when new pull requests\nare opened. If something breaks, you'll be informed and the results will be\nreported on GitHub.\n\nTests are written using a combination of a simple Bash script for compilation\nof our module with different versions and configurations of Nginx and the\n`Test::Nginx \u003chttps://metacpan.org/pod/Test::Nginx::Socket\u003e`_ Perl test\nscaffolding for integration testing.  Consult the previous link for\ninformation on how to extend the tests, and also refer to the underlying\n`Test::Base \u003chttps://metacpan.org/pod/Test::Base#blocks-data-section-name\u003e`_\ndocumentation on aspects like the `blocks()` function.\n\nIntegration tests are run automatically by CI but can also be run manually\n(requires Perl \u0026 CPAN to be installed):\n\n.. code-block:: bash\n\n    cd nginx-http-shibboleth\n    cpanm --notest --local-lib=$HOME/perl5 Test::Nginx\n    # nginx must be present in PATH and built with debugging symbols\n    PERL5LIB=$HOME/perl5/lib/perl5 prove\n\nHelp \u0026 Support\n--------------\n\nSupport requests for Shibboleth configuration and Nginx or web server setup\nshould be directed to the Shibboleth community users mailing list.  See\nhttps://www.shibboleth.net/community/lists/ for details.\n\nDebugging\n---------\n\nBecause of the complex nature of the nginx/FastCGI/Shibboleth stack, debugging\nconfiguration issues can be difficult.  Here's some key points:\n\n#. Confirm that ``nginx-http-shibboleth`` is successfully built and installed\n   within nginx. You can check by running ``nginx -V`` and inspecting the\n   output for ``--add-module=[path]/nginx-http-shibboleth`` or\n   ``--add-dynamic-module=[path]/nginx-http-shibboleth``.\n#. If using dynamic modules for nginx, confirm you have used the\n   ``load_module`` directive to load this module.  Your use of ``shib_request``\n   and other directives will fail if you have forgotten to load the module.\n#. If using a version of nginx that is different to those we\n   `test with \u003chttps://github.com/nginx-shib/nginx-http-shibboleth/blob/master/.github/workflows/build.yml\u003e`_\n   or if you are using other third-party modules, you should run\n   the test suite above to confirm compatibility.  If any tests fail, then check\n   your configuration or consider updating your nginx version.\n#. Shibboleth configuration: check your ``shibboleth2.xml`` and associated\n   configuration to ensure your hosts, paths and attributes are being correctly\n   released.  An `example configuration \u003chttps://github.com/nginx-shib/nginx-http-shibboleth/blob/master/CONFIG.rst#configuring-shibboleths-shibboleth2xml-to-recognise-secured-paths\u003e`_\n   can help you identify key \"gotchas\" to configuring ``shibboleth2.xml`` to work\n   with the FastCGI authorizer.\n#. Application-level: within your code, always start with the simplest possible\n   debugging output (such as printing the request environment) and work\n   up from there.  If you want to create a basic, stand-alone app, take\n   a look at the `Bottle \u003chttps://github.com/nginx-shib/nginx-http-shibboleth/wiki/bottle\u003e`_\n   configuration on the wiki.\n#. Debugging module internals: if you've carefully checked all of the above, then\n   you can also debug the behaviour of this module itself.  You will need to have\n   compiled nginx with debugging support (via ``./auto/configure --with-debug ...``)\n   and when running nginx, it is easiest if you're able run in the foreground with\n   debug logging enabled.  Add the following to your ``nginx.conf``:\n\n   .. code-block:: nginx\n\n      daemon off;\n      error_log stderr debug;\n\n   and run nginx.  Upon starting nginx you should see lines containing `[debug]` and\n   as you make requests, console logging will continue.  If this doesn't happen,\n   then check your nginx configuration and compilation process.\n\n   When you eventually make a request that hits (or should invoke) the\n   ``shib_request`` location block, you will see lines like so in the output:\n\n   .. code-block:: nginx\n\n      [debug] 1234#0: shib request handler\n      [debug] 1234#0: shib request set variables\n      [debug] 1234#0: shib request authorizer handler\n      [debug] 1234#0: shib request authorizer allows access\n      [debug] 1234#0: shib request authorizer copied header: \"AUTH_TYPE: shibboleth\"\n      [debug] 1234#0: shib request authorizer copied header: \"REMOTE_USER: john.smith@example.com\"\n      ...\n\n   If you don't see these types of lines containing `shib request ...`,\n   or if you see *some* of the lines above but not where headers/variables are being\n   copied, then double-check your nginx configuration.  If you're still not getting\n   anywhere, then you can add your own debugging lines into the source (follow\n   this module's examples) to eventually determine what is going wrong and when.\n   If doing this, don't forget to recompile nginx and/or ``nginx-http-shibboleth``\n   whenever you make a change.\n\nIf you believe you've found a bug in the core module code, then please\n`create an issue \u003chttps://github.com/nginx-shib/nginx-http-shibboleth/issues\u003e`_.\n\nYou can also search existing issues as it is likely someone else has\nencountered a similar issue before.\n\nVersioning\n----------\n\nThis module uses `Semantic Versioning \u003chttps://semver.org/\u003e`_ and all releases\nare tagged on GitHub, which allows package downloads of individual tags.\n\nLicense\n-------\n\nThis project is licensed under the same license that nginx is, the\n`2-clause BSD-like license \u003chttps://github.com/nginx-shib/nginx-http-shibboleth/blob/master/LICENSE\u003e`_. \n\n.. _FastCGI Authorizer specification: https://web.archive.org/web/20160306081510/http://fastcgi.com/drupal/node/6?q=node/22#S6.3\n.. _mod_shib: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig\n.. _shibboleth2.xml: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPShibbolethXML\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx-shib%2Fnginx-http-shibboleth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnginx-shib%2Fnginx-http-shibboleth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx-shib%2Fnginx-http-shibboleth/lists"}