diff options
Diffstat (limited to 'doc/source/admin/federation/shibboleth.inc')
| -rw-r--r-- | doc/source/admin/federation/shibboleth.inc | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/doc/source/admin/federation/shibboleth.inc b/doc/source/admin/federation/shibboleth.inc new file mode 100644 index 000000000..9415659ad --- /dev/null +++ b/doc/source/admin/federation/shibboleth.inc @@ -0,0 +1,275 @@ +.. -*- rst -*- + +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _shibboleth: + +--------------------- +Setting up 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`_. + +.. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server +.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server +.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server + +Install the Module +~~~~~~~~~~~~~~~~~~ + +Install the Apache module package. For example, on Ubuntu: + +.. code-block:: console + + # apt-get install libapache2-mod-shib2 + +The package and module name will differ between distributions. + +Configure Protected Endpoints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the Apache configuration for the keystone VirtualHost, set an additional +``<Location>`` which is not part of keystone's API: + +.. code-block:: apache + + <Location /Shibboleth.sso> + SetHandler shib + </Location> + +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 + + <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth> + Require valid-user + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibExportAssertion off + <IfVersion < 2.4> + ShibRequireSession On + ShibRequireAll On + </IfVersion> + </Location> + +Do the same for the WebSSO auth paths if using horizon as a single sign-on +frontend: + +.. code-block:: apache + + <Location /v3/auth/OS-FEDERATION/websso/saml2> + Require valid-user + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibExportAssertion off + <IfVersion < 2.4> + ShibRequireSession On + ShibRequireAll On + </IfVersion> + </Location> + <Location /v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso> + Require valid-user + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibExportAssertion off + <IfVersion < 2.4> + ShibRequireSession On + ShibRequireAll On + </IfVersion> + </Location> + +Remember to reload Apache after altering the VirtualHost: + +.. code-block:: console + + # systemctl reload apache2 + +Configuring mod_shib +-------------------- + +.. note:: + + You are advised to examine `Shibboleth Service Provider Configuration + documentation + <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_ + +Generate a keypair +~~~~~~~~~~~~~~~~~~ + +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 <number of years> + +which will generate a key pair under ``/etc/shibboleth``. In other cases, the +package might generate the key pair automatically upon installation. + +Configure metadata +~~~~~~~~~~~~~~~~~~ + +``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 + + <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth" + REMOTE_USER="eppn persistent-id targeted-id"> + +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 + + <SSO entityID="https://samltest.id/saml/idp"> + +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: + + +.. code-block:: xml + + <SSO entityID="https://samltest.id/saml/idp" ECP="true"> + +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 + + <MetadataProvider type="XML" file="/etc/shibboleth/samltest-metadata.xml" /> + +or pointing to a remote location: + +.. code-block:: xml + + <MetadataProvider type="XML" url="https://samltest.id/saml/idp" + backingFile="samltest-metadata.xml" /> + +When you are finished configuring ``shibboleth2.xml``, restart the ``shibd`` +daemon: + +.. 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 + <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_ + +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 + + <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid" /> + +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``: + +.. code-block:: xml + + <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth" + REMOTE_USER="uid"> + +Similarly, if using keystone as your Identity Provider, several custom +attributes will be needed in ``/etc/shibboleth/attribute-map.xml``: + +.. code-block:: xml + + <Attribute name="openstack_user" id="openstack_user"/> + <Attribute name="openstack_roles" id="openstack_roles"/> + <Attribute name="openstack_project" id="openstack_project"/> + <Attribute name="openstack_user_domain" id="openstack_user_domain"/> + <Attribute name="openstack_project_domain" id="openstack_project_domain"/> + +And update the ``REMOTE_USER`` variable in ``/etc/shibboleth/shibboleth2.xml`` +if desired: + +.. code-block:: xml + + <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth" + REMOTE_USER="openstack_user"> + +Restart the ``shibd`` daemon after making these changes: + +.. code-block:: console + + # systemctl restart shibd + +Exchange Metadata +~~~~~~~~~~~~~~~~~ + +Once configured, the Service Provider metadata is available to download: + +.. code-block:: console + + # wget https://sp.keystone.example.org/Shibboleth.sso/Metadata + +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:ref:`Continue configuring keystone <federation_configuring_keystone>` |