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