Skip to content
Snippets Groups Projects
Commit 69fc4ebb authored by David\ Beitey's avatar David\ Beitey
Browse files

Complete configuration documentation

parent f1bc7806
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 188 additions and 190 deletions
CONFIG.rst
+ 188
− 190
View file @ 69fc4ebb
...@@ -14,6 +14,8 @@ Steps ...@@ -14,6 +14,8 @@ Steps
#. Configure Nginx to talk to both FastCGI authorizer and responder. #. Configure Nginx to talk to both FastCGI authorizer and responder.
#. Configure your Nginx application ``location`` block with ``shib_request #. Configure your Nginx application ``location`` block with ``shib_request
on``. on``.
#. Configure Shibboleth's ``shibboleth2.xml`` so the authorizer and responder are
aware of which paths to protect.
#. Ensure your application code accepts the relevant incoming headers for #. Ensure your application code accepts the relevant incoming headers for
authN/authZ. authN/authZ.
...@@ -104,122 +106,130 @@ Note that you'll almost certainly have other options being passed to ...@@ -104,122 +106,130 @@ Note that you'll almost certainly have other options being passed to
existing packages for your distribution, and patch the above ``configure`` existing packages for your distribution, and patch the above ``configure``
argument into the build processes. argument into the build processes.
Also, you will likely need the Nginx module `nginx_headers_more
<http://wiki.nginx.org/HttpHeadersMoreModule>`_ in order to prevent header
spoofing from the client, unless you already have a separate solution in
place.
If you wish to confirm the build was successful, install a version of Nginx
with debugging support, configure full trace logging, and the example
configuration below. You should notice ``shib request ...`` lines in the
output showing where ``nginx-http-shibboleth`` is up to during a request.
Configure Nginx Configure Nginx
--------------- ---------------
Nginx now needs to be configured with ``location`` blocks that point to both
#. Configure one or more servers within your Nginx configuration like so. the FastCGI authorizer and responder. Specify your FastCGI socket locations,
You'll need the socket information for your FastCGI Shibboleth SP where required. Note that the ``more_clear_input_headers`` directive is
applications. required to prevent header spoofing from the client, since the Shibboleth
variables are passed around as headers.
The ``proxy_pass http://localhost:8080`` can be replaced
with whatever application or configuration should be receiving the .. code:: nginx
Shibboleth attributes as headers. In my case, port 8080 is running Plone,
a Python-based CMS, but you might anything (PHP, FastCGI, etc) here. server {
Essentially, this is what would normally be the backend configured against listen 443 ssl;
``AuthType shibboleth`` in Apache. server_name example.org;
...
.. code:: nginx
#FastCGI authorizer for Auth Request module
server { location = /shibauthorizer {
listen 443 ssl; internal;
... include fastcgi_params;
fastcgi_pass unix:/opt/shibboleth/shibauthorizer.sock;
#FastCGI authorizer for Auth Request module }
location = /shibauthorizer {
internal; #FastCGI responder
include fastcgi_params; location /Shibboleth.sso {
fastcgi_pass unix:/opt/shibboleth/shibauthorizer.sock; include fastcgi_params;
} fastcgi_pass unix:/opt/shibboleth/shibresponder.sock;
}
#FastCGI responder for SSO
location /Shibboleth.sso { #Resources for the Shibboleth error pages. This can be customised.
include fastcgi_params; location /shibboleth-sp {
fastcgi_pass unix:/opt/shibboleth/shibresponder.sock; alias /usr/share/shibboleth/;
} }
#Resources for the Shibboleth error pages. This can be customised. #A secured location. Here all incoming requests query the
location /shibboleth-sp { #FastCGI authorizer. Watch out for performance issues and spoofing.
alias /usr/share/shibboleth/; location /secure {
} more_clear_input_headers 'Variable-*' 'Shib-*' 'Remote-User' 'REMOTE_USER' 'Auth-Type' 'AUTH_TYPE';
#A secured location. Here all incoming requests query the #Add your attributes here. They get introduced as headers
#FastCGI authorizer. Watch out for performance issues and spoofing. #by the FastCGI authorizer so we must prevent spoofing.
location /secure { more_clear_input_headers 'displayName' 'mail' 'persistent-id';
more_clear_input_headers 'Variable-*' 'Shib-*' 'Remote-User' 'REMOTE_USER' 'Auth-Type' 'AUTH_TYPE'; shib_request /shibauthorizer;
proxy_pass http://localhost:8080;
#Add your attributes here. They get introduced as headers }
#by the FastCGI authorizer so we must prevent spoofing.
more_clear_input_headers 'displayName' 'mail' 'persistent-id'; #A secured location, but only a specific sub-path causes Shibboleth
auth_request /shibauthorizer authorizer=on; #authentication.
proxy_pass http://localhost:8080; location /secure2 {
} proxy_pass http://localhost:8080;
#A secured location, but only a specific sub-path causes Shibboleth location = /secure2/shibboleth {
#authentication. more_clear_input_headers 'Variable-*' 'Shib-*' 'Remote-User' 'REMOTE_USER' 'Auth-Type' 'AUTH_TYPE';
location /secure2 { #Add your attributes here. They get introduced as headers
proxy_pass http://localhost:8080; #by the FastCGI authorizer so we must prevent spoofing.
more_clear_input_headers 'displayName' 'mail' 'persistent-id';
location = /secure2/shibboleth { shib_request /shibauthorizer;
more_clear_input_headers 'Variable-*' 'Shib-*' 'Remote-User' 'REMOTE_USER' 'Auth-Type' 'AUTH_TYPE'; proxy_pass http://localhost:8080;
#Add your attributes here. They get introduced as headers }
#by the FastCGI authorizer so we must prevent spoofing. }
more_clear_input_headers 'displayName' 'mail' 'persistent-id'; }
auth_request /shibauthorizer authorizer=on;
proxy_pass http://localhost:8080; Notes
} ~~~~~
}
} * ``proxy_pass`` can be replaced with any application or configuration that
should receive the Shibboleth attributes as headers. Essentially, this is
An explanation about the above is provided in the comments. I should note what would normally be the backend configured against ``AuthType
that: shibboleth`` in Apache.
* The first 3 locations are pure boilerplate for any host that requires * The first 3 locations are pure boilerplate for any host that requires
Shibboleth authentication, so you can (and should!) put these into an Shibboleth authentication, so you may wish to template these for reuse
``include``-able configuration file and reuse them. between hosts.
* The ``/shibboleth-sp`` location is purely there to help your default * The ``/shibboleth-sp`` location provides web resources for default
install. If you customise your error pages, feel free to change or delete Shibboleth error messages. If you customise error pages, or don't care for
this location. images or styles on error pages, delete this location.
* Take note of the ``more_clear_input_headers`` calls. As the Shibboleth * Take note of the ``more_clear_input_headers`` calls. As the Shibboleth
authorizer will inject headers into the request before passing the authorizer will inject headers into the request before passing the
request onto the final upstream endpoint, you **must** request onto the final upstream endpoint, you **must**
use these directives to protect from spoofing. You should expand the use these directives to protect from spoofing. You should expand the
second call to this directive when you have more incoming attributes second call to this directive when you have more incoming attributes
from the Shibboleth authorizer. Or else beware... from the Shibboleth authorizer. Or else beware...
* The ``/secure`` location will ask the FastCGI authorizer for attributes * The ``/secure`` location will ask the FastCGI authorizer for attributes for
for **every** request that comes in. This may or may not be what you **every** request that comes in. This may or may not be desirable. Keep in
want. Keep in mind this means that each request will have Shibboleth mind this means that each request will have Shibboleth attributes add before
attributes dropped into the request for sending onto backend services, being sent onto a backend, and this will happen every time.
and this will happen every time. Did I mention for **every request**?
* You may wish to consider only securing a path that creates an application
* The ``/secure2`` location only asks the FastCGI authorizer for auth session (such as the ``/secure2`` location block), and letting your
on a (very) specific sub-path. Only upon the user hitting this specific application handle the rest. Only upon the user hitting this specific URL
URL will the authentication process be triggered. This is a smarter will the authentication process be triggered. This is a authentication
authentication technique to avoid extra overhead -- set the upstream technique to avoid extra overhead -- set the upstream for the specific
for the specific sub-path to be somewhere an application session is sub-path to be somewhere an application session is created, and have that
created, and have that application session capture the Shibboleth application session capture the Shibboleth attributes.
attributes.
Notice how the rest of the application doesn't refer to the authorizer.
Notice how the rest of the application doesn't refer to the authorizer. This means the application can be used anonymously, too. Alternatively,
This means the application can be used anonymously, too. Alternatively, you can configure the ``requireSession`` option to be fa
you can configure the ``requireSession`` option to be fa
* Adding the ``shib_request`` line into a location isn't all you need to
* Adding the ``auth_request`` line into a location isn't all you need to do to get the FastCGI authorizer to recognise your path as Shibboleth
do to get the FastCGI authorizer to recognise your path as Shibboleth protected. You need also need to ensure that ``shibd`` is configured to
protected. You need to follow the instructions below and take care. accept your paths as well, following the next set of instructions.
#. Save the configuration and follow the next section. You're almost done.
Configuring Shibboleth's shibboleth2.xml to recognise secured paths
-------------------------------------------------------------------
Configuring Shibboleth to recognise secured paths
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Within Apache, you can tell Shibboleth which paths to secure by
using configuration like:
Typically, within Apache, you can tell Shibboleth which paths to secure by
using something like:
.. code:: apache .. code:: apache
...@@ -228,80 +238,55 @@ using something like: ...@@ -228,80 +238,55 @@ using something like:
ShibRequestSetting requireSession false ShibRequestSetting requireSession false
</Location> </Location>
However, the FastCGI authorizer for Shibboleth operates without such directives Shibboleth is made aware of this configuration automatically.
and thus path protection needs to be configured like it would be for IIS,
using the ``<RequestMapper>`` configuration. The same options are accepted However, the FastCGI authorizer for Shibboleth operates without such
within this section of the ``shibboleth2.xml`` configuration file, it's just directives and thus path protection needs to be configured like it would be
that you need to know where to put them. So let's do that. for IIS, using the ``<RequestMapper>`` configuration. The same options from
Apache are accepted within the ``RequestMapper`` section of the
``shibboleth2.xml`` configuration file, like this truncated example shows.
#. Configure your ``shibboleth2.xml`` file like so. Find the ``RequestMapper`` This example corresponds to the sample Nginx configuration given above.
element and replace it with something like the following:
.. code:: xml
.. code:: xml
<RequestMapper type="XML">
<RequestMapper type="XML"> <RequestMap>
<RequestMap> <Host name="example.org"
<Host name="eresearch.jcu.edu.au" authType="shibboleth"
authType="shibboleth" requireSession="true"
requireSession="true" redirectToSSL="443">
redirectToSSL="443"> <Path name="/secure" />
<Path name="/secure" /> <Path name="/secure2/shibboleth" />
<Path name="/secure2/shibboleth" /> ...
... </Host>
</Host> ...
... </RequestMap>
</RequestMap> </RequestMapper>
</RequestMapper>
Notes
Some notes: ~~~~~
* The Shibboleth FastCGI authorizer needs to see ``authType`` **and** * The Shibboleth FastCGI authorizer must have both ``authType`` **and**
``requireSession`` configured for the resultant path. If they are not ``requireSession`` configured for the resultant path. If they are not
present, then the authorizer will ignore the path it is passed and present, then the authorizer will ignore the path it is passed and the user
the user will not be prompted for authentication (and you **will** will not be prompted for authentication (and no logging will take place).
tear your hair out because no logging takes place!).
* ``<Path>`` names are **case sensitive**.
* ``<Path>`` names are **case sensitive** here. You have hereby been warned!
-- although this shouldn't be too surprising to you hopefully. * You can use other configuration items like ``<HostRegex>`` and
``<PathRegex>`` and ``<AccessControl``> to configure how Shibboleth handles
* You can use other configuration items like ``<HostRegex>`` and incoming requests.
``<PathRegex>`` and ``<AccessControl``> to configure what happens to
requests. Check out the documentation below - there's lots to learn. * Configuration is inherited **downwards** in the XML tree. So, configure ``authType``
on a ``<Host>`` element will see it apply to all paths beneath it. This is
* An interesting aspect here is that configuration is inherited downwards not required, however; attributes can be placed anywhere you desire.
in the XML tree. So, you could configure something like the ``authType``
on a ``<Host>`` and have it apply to all paths beneath it. * Nested ``<Path>`` elements are greedy. Putting a path with
``name="shibboleth"`` within a path with ``name="secure"`` really translates
You don't need to do this, though. You may put all the configuration to a path with ``name="secure/shibboleth"``.
attributes onto the ``<Path>`` element, or even move them up to
higher levels in the tree if you want to reduce duplication. * Upon changing this configuration, ensure the ``shibauthorizer`` and
``shibresponder`` applications are hard-restarted, as well as ``shibd``.
* Nested ``<Path>`` elements will see their path segments being greedy.
So putting a path with ``name="shibboleth"`` within a path with
``name="secure"`` really translates to a path with
``name="secure/shibboleth"``. Whatever takes your fancy here.
#. Once you're done, then restart the Shibboleth daemon, ensure that you
restart the Shibboleth FastCGI applications, and hard restart Nginx
just to make sure it finds those sockets::
service shibd restart
supervisorctl restart shibauthorizer shibresponder
service nginx restart
Assuming, of course, that you're using Supervisor to run your applications.
You should. It's easy to work with and fun.
#. Try loading up your Shibboleth protected URL. If all goes well, then you
should get a complete authentication cycle. If not, check carefully through
everything above.
Take a look at
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapper
and
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMap
for more information.
Gotchas Gotchas
------- -------
...@@ -323,9 +308,22 @@ to be invoked, check the following: ...@@ -323,9 +308,22 @@ to be invoked, check the following:
in Nginx is probably wrong and the authorizer isn't being contacted. in Nginx is probably wrong and the authorizer isn't being contacted.
* When in doubt, hard restart the entire stack, and use something like ``curl`` * When in doubt, hard restart the entire stack, and use something like ``curl``
to ensure you avoid any browser caching. to ensure you avoid any browser caching. If still in doubt that the Nginx
installation has been successfully built with the ``nginx-http-shibboleth``
module, run Nginx in debug mode, and trace the request accordingly.
Resources
---------
* http://wiki.nginx.org/HttpHeadersMoreModule
* https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapper
* https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMap
* https://github.com/nginx-shib/nginx-http-shibboleth
* http://davidjb.com/blog/2013/04/setting-up-a-shibboleth-sp-with-fastcgi-support/
* https://github.com/jcu-eresearch/shibboleth-fastcgi/
* https://github.com/jcu-eresearch/nginx-custom-build
* When in serious doubt, install a version of Nginx with debugging support, Deprecated documentation:
configure full trace logging, and run it with your configuration instead.
If
* http://davidjb.com/blog/2013/04/integrating-nginx-and-a-shibboleth-sp-with-fastcgi/
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment