From 83c37f4a943e8e7181f2f6f973b82885f598e010 Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Fri, 21 Dec 2018 19:52:45 -0800 Subject: [PATCH] Enhance the shibboleth guide Update, reorganize and clean up the shibboleth guide. Remove the full example of shibboleth2.xml, it does not add anything useful and just creates clutter. Use the systemctl command to modernize the service management commands. Add examples of configuring all required endpoints in Apache to mirror the new section on configuring protected endpoints in the main guide and replace the lost examples from the consolidated WebSSO guide. Add a section on configuring REMOTE_USER and attributes-map.xml. Remove use of ``a2enmod`` since the Shibboleth module is automatically enabled by the package on all supported distros. Partial-bug: #1793374 Change-Id: I0eed3420aa49fdc75349a467e91f8e7f22b075e9 --- .../admin/federation/configure_federation.rst | 2 + doc/source/admin/federation/shibboleth.rst | 344 +++++++++--------- 2 files changed, 167 insertions(+), 179 deletions(-) diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst index 407d1df5a8..53d34410e2 100644 --- a/doc/source/admin/federation/configure_federation.rst +++ b/doc/source/admin/federation/configure_federation.rst @@ -14,6 +14,8 @@ Configuring Keystone for Federation =================================== +.. _keystone-as-sp: + ----------------------------------- Keystone as a Service Provider (SP) ----------------------------------- diff --git a/doc/source/admin/federation/shibboleth.rst b/doc/source/admin/federation/shibboleth.rst index a846159350..96e1a729f3 100644 --- a/doc/source/admin/federation/shibboleth.rst +++ b/doc/source/admin/federation/shibboleth.rst @@ -11,12 +11,28 @@ License for the specific language governing permissions and limitations under the License. ----------------- -Setup Shibboleth ----------------- +--------------------- +Setting up Shibboleth +--------------------- -Configure Apache HTTPD for mod_shibboleth ------------------------------------------ +See :ref:`keystone-as-sp` before proceeding with these Shibboleth-specific +instructions. + +.. note:: + + The examples below are for Ubuntu 16.04, for which only version 2 of the + Shibboleth Service Provider is available. Version 3 is available for other + distributions and the configuration should be identical to version 2. + +Configuring Apache HTTPD for mod_shib +------------------------------------- + +.. note:: + + You are advised to carefully examine the `mod_shib Apache configuration + documentation`_. + +.. _mod_shib Apache configuration documentation: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig Configure keystone under Apache, following the steps in the install guide for `SUSE`_, `RedHat`_ or `Ubuntu`_. @@ -25,21 +41,22 @@ Configure keystone under Apache, following the steps in the install guide for .. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server .. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server -You'll also need to install `Shibboleth `_, for -example: +Install the Module +~~~~~~~~~~~~~~~~~~ + +Install the Apache module package. For example, on Ubuntu: .. code-block:: console # apt-get install libapache2-mod-shib2 -Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: +The package and module name will differ between distributions. -Add this *WSGIScriptAliasMatch* directive to your public vhost configuration:: +Configure Protected Endpoints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /usr/local/bin/keystone-wsgi-public/$1 - -Make sure the keystone Apache virtual host configuration contains a ** directive for the -Shibboleth module and a ** directive for each identity provider +In the Apache configuration for the keystone VirtualHost, set an additional +```` which is not part of keystone's API: .. code-block:: apache @@ -47,75 +64,118 @@ Shibboleth module and a ** directive for each identity provider SetHandler shib - - ShibRequestSetting requireSession 1 - AuthType shibboleth - ShibExportAssertion Off - Require valid-user +If you are using ``mod_proxy``, for example to proxy requests to the +``/identity`` path to keystone's UWSGI service, you must exempt this Shibboleth +endpoint from it: +.. code-block:: apache + + Proxypass Shibboleth.sso ! + +Configure each protected path to use the ``shibboleth`` AuthType: + +.. code-block:: apache + + + Require valid-user + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibExportAssertion off ShibRequireSession On ShibRequireAll On - + -.. NOTE:: - * ``saml2`` is the name of the `protocol that you will configure `_ - * ``samltest`` is the name associated with the `IdP in Keystone `_ - * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in - Apache 2.4+. - * You are advised to carefully examine `Shibboleth Apache configuration - documentation - `_ +Do the same for the WebSSO auth paths if using horizon as a single sign-on +frontend: -Enable the ``shib2`` module, for example: +.. code-block:: apache + + + Require valid-user + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibExportAssertion off + + ShibRequireSession On + ShibRequireAll On + + + + Require valid-user + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibExportAssertion off + + ShibRequireSession On + ShibRequireAll On + + + +Remember to reload Apache after altering the VirtualHost: .. code-block:: console - # a2enmod shib2 + # systemctl reload apache2 -Restart Apache, for example: +Configuring mod_shib +-------------------- -.. code-block:: console +.. note:: - # service apache2 restart + You are advised to examine `Shibboleth Service Provider Configuration + documentation + `_ -Configuring shibboleth2.xml ---------------------------- +Generate a keypair +~~~~~~~~~~~~~~~~~~ -Once you have your Keystone vhost (virtual host) ready, it's then time to -configure Shibboleth and upload your Metadata to the Identity Provider. - -Create a new keypair for Shibboleth with: +For all SAML Service Providers, a PKI key pair must be generated and exchanged +with the Identity Provider. The ``mod_shib`` package on the Ubuntu distribution +provides a utility to generate the key pair: .. code-block:: console # shib-keygen -y -The newly created key file will be stored under ``/etc/shibboleth/sp-key.pem``. +which will generate a key pair under ``/etc/shibboleth``. In other cases, the +package might generate the key pair automatically upon installation. -Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml`` -file. You will want to change five settings: +Configure metadata +~~~~~~~~~~~~~~~~~~ -* Set the SP entity ID. This value usually has the form of a URI but it does not - have to resolve to anything. It must uniquely identify your Service Provider - to your Identity Provider. +``mod_shib`` also has its own configuration file at +``/etc/shibboleth/shibboleth2.xml`` that must be altered, as well +as its own daemon. First, give the Service Provider an entity ID. This is a URN +that you choose that must be globally unique to the Identity Provider: .. code-block:: xml - + -* Set the entity ID of the Identity Provider: +Depending on your Identity Provider, you may also want to change the REMOTE_USER +setting, more on that in a moment. + +Set the entity ID of the Identity Provider (this is the same as the value you +provided for ``--remote-id`` in `Identity Provider`): .. code-block:: xml -* Remove the discoveryURL lines unless you want to enable advanced IdP discovery. +Additionally, if you want to enable ECP (required for Keystone-to-Keystone), +the SSO tag for this entity must also have the ECP flag set: -* Tell Shibboleth where to find the metadata of the Identity Provider. You could - either tell it to fetch it from a URI or point it to a local file. For - example, pointing to a local file: + +.. code-block:: xml + + + +Tell Shibboleth where to find the metadata of the Identity Provider. You could +either tell it to fetch it from a URI or point it to a local file. For example, +pointing to a local file: .. code-block:: xml @@ -128,132 +188,47 @@ or pointing to a remote location: -You are advised to examine `Shibboleth Service Provider Configuration documentation `_ +When you are finished configuring ``shibboleth2.xml``, restart the ``shibd`` +daemon: -The result should look like (The example shown below is for reference only, not -to be used in a production environment): +.. code-block:: console + + # systemctl restart shibd + +Check the ``shibd`` logs in ``/var/log/shibboleth/shibd.log`` and +``/var/log/shibboleth/shibd_warn.log`` for errors or warnings. + +Configure allowed attributes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + For more information see the `attributes documentation + `_ + +By default, ``mod_shib`` does not pass all attributes received from the Identity +Provider to keystone. If your Identity Provider does not use attributes known to +``shibd``, you must configure them. For example, `samltest.id` uses a custom UID +attribute. It is not discoverable in the Identity Provider metadata, but the +attribute name and type is logged in the ``mod_shib`` logs when an +authentication attempt is made. To allow the attribute, add it to +``/etc/shibboleth/attribute-map.xml``: .. code-block:: xml - + - +You may also want to use that attribute as a value for the ``REMOTE_USER`` +variable, which will make the ``REMOTE_USER`` variable usable as a parameter to +your mapping rules. To do so, add it to ``/etc/shibboleth/shibboleth2.xml``: - + - - - - - - - - - SAML2 SAML1 - - - - SAML2 Local - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -If keystone is your IdP, you will need to examine your attributes map file -``/etc/shibboleth/attribute-map.xml`` and add the following attributes: +Similarly, if using keystone as your Identity Provider, several custom +attributes will be needed in ``/etc/shibboleth/attribute-map.xml``: .. code-block:: xml @@ -263,25 +238,36 @@ If keystone is your IdP, you will need to examine your attributes map file -For more information see the -`attributes documentation `_ +And update the ``REMOTE_USER`` variable in ``/etc/shibboleth/shibboleth2.xml`` +if desired: -Once you are done, restart your Shibboleth daemon and apache: +.. code-block:: xml + + + +Restart the ``shibd`` daemon after making these changes: .. code-block:: console - # service shibd restart - # service apache2 restart + # systemctl restart shibd -Check ``/var/log/shibboleth/shibd_warn.log`` for any ERROR or CRIT notices and -correct them. +Exchange Metadata +~~~~~~~~~~~~~~~~~ -Upload your Service Provider's metadata file to your Identity Provider. You can -fetch it with: +Once configured, the Service Provider metadata is available to download: .. code-block:: console # wget https://sp.keystone.example.org/Shibboleth.sso/Metadata -This step depends on your Identity Provider choice and is not covered here. -If keystone is your Identity Provider you do not need to upload this file. +Upload your Service Provider's metadata to your Identity Provider. This step +depends on your Identity Provider choice and is not covered here. If keystone +is your Identity Provider you do not need to upload this file. + +Continue configuring keystone +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`Continue configuring keystone`_ + +.. _Continue configuring keystone: configure_federation.html#configuring-keystone