Merge "Enhance the shibboleth guide"

This commit is contained in:
Zuul 2019-01-09 03:16:17 +00:00 committed by Gerrit Code Review
commit 01b964955a
2 changed files with 167 additions and 179 deletions

View File

@ -14,6 +14,8 @@
Configuring Keystone for Federation Configuring Keystone for Federation
=================================== ===================================
.. _keystone-as-sp:
----------------------------------- -----------------------------------
Keystone as a Service Provider (SP) Keystone as a Service Provider (SP)
----------------------------------- -----------------------------------

View File

@ -11,12 +11,28 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. 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 Configure keystone under Apache, following the steps in the install guide for
`SUSE`_, `RedHat`_ or `Ubuntu`_. `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 .. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server .. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
You'll also need to install `Shibboleth <https://wiki.shibboleth.net/confluence/display/SHIB2/Home>`_, for Install the Module
example: ~~~~~~~~~~~~~~~~~~
Install the Apache module package. For example, on Ubuntu:
.. code-block:: console .. code-block:: console
# apt-get install libapache2-mod-shib2 # 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 In the Apache configuration for the keystone VirtualHost, set an additional
``<Location>`` which is not part of keystone's API:
Make sure the keystone Apache virtual host configuration contains a *<Location>* directive for the
Shibboleth module and a *<Location>* directive for each identity provider
.. code-block:: apache .. code-block:: apache
@ -47,75 +64,118 @@ Shibboleth module and a *<Location>* directive for each identity provider
SetHandler shib SetHandler shib
</Location> </Location>
<Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth> If you are using ``mod_proxy``, for example to proxy requests to the
ShibRequestSetting requireSession 1 ``/identity`` path to keystone's UWSGI service, you must exempt this Shibboleth
AuthType shibboleth endpoint from it:
ShibExportAssertion Off
Require valid-user
.. 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> <IfVersion < 2.4>
ShibRequireSession On ShibRequireSession On
ShibRequireAll On ShibRequireAll On
</IfVersion> </IfVersion>
</Location> </Location>
.. NOTE:: Do the same for the WebSSO auth paths if using horizon as a single sign-on
* ``saml2`` is the name of the `protocol that you will configure <configure_federation.html#protocol>`_ frontend:
* ``samltest`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
* The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in
Apache 2.4+.
* You are advised to carefully examine `Shibboleth Apache configuration
documentation
<https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig>`_
Enable the ``shib2`` module, for example: .. 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 .. 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
<https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_
Configuring shibboleth2.xml Generate a keypair
--------------------------- ~~~~~~~~~~~~~~~~~~
Once you have your Keystone vhost (virtual host) ready, it's then time to For all SAML Service Providers, a PKI key pair must be generated and exchanged
configure Shibboleth and upload your Metadata to the Identity Provider. with the Identity Provider. The ``mod_shib`` package on the Ubuntu distribution
provides a utility to generate the key pair:
Create a new keypair for Shibboleth with:
.. code-block:: console .. code-block:: console
# shib-keygen -y <number of years> # shib-keygen -y <number of years>
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`` Configure metadata
file. You will want to change five settings: ~~~~~~~~~~~~~~~~~~
* Set the SP entity ID. This value usually has the form of a URI but it does not ``mod_shib`` also has its own configuration file at
have to resolve to anything. It must uniquely identify your Service Provider ``/etc/shibboleth/shibboleth2.xml`` that must be altered, as well
to your Identity Provider. 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 .. code-block:: xml
<ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"> <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
REMOTE_USER="eppn persistent-id targeted-id">
* 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 .. code-block:: xml
<SSO entityID="https://samltest.id/saml/idp"> <SSO entityID="https://samltest.id/saml/idp">
* 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 .. code-block:: xml
example, pointing to a local file:
<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 .. code-block:: xml
@ -128,132 +188,47 @@ or pointing to a remote location:
<MetadataProvider type="XML" url="https://samltest.id/saml/idp" <MetadataProvider type="XML" url="https://samltest.id/saml/idp"
backingFile="samltest-metadata.xml" /> backingFile="samltest-metadata.xml" />
You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_ 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 .. code-block:: console
to be used in a production environment):
# 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 .. code-block:: xml
<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config" <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid" />
xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
clockSkew="180">
<!-- You may also want to use that attribute as a value for the ``REMOTE_USER``
By default, in-memory StorageService, ReplayCache, ArtifactMap, and SessionCache variable, which will make the ``REMOTE_USER`` variable usable as a parameter to
are used. See example-shibboleth2.xml for samples of explicitly configuring them. your mapping rules. To do so, add it to ``/etc/shibboleth/shibboleth2.xml``:
-->
<!-- .. code-block:: xml
To customize behavior for specific resources on Apache, and to link vhosts or
resources to ApplicationOverride settings below, use web server options/commands.
See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfigurationElements for help.
For examples with the RequestMap XML syntax instead, see the example-shibboleth2.xml <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
file, and the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHowTo topic. REMOTE_USER="uid">
-->
<!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. --> Similarly, if using keystone as your Identity Provider, several custom
<ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"> attributes will be needed in ``/etc/shibboleth/attribute-map.xml``:
<!--
Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
You MUST supply an effectively unique handlerURL value for each of your applications.
The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
a relative value based on the virtual host. Using handlerSSL="true", the default, will force
the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
Note that while we default checkAddress to "false", this has a negative impact on the
security of your site. Stealing sessions via cookie theft is much easier with this disabled.
-->
<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="false" cookieProps="http">
<!--
Configures SSO for a default IdP. To allow for >1 IdP, remove
entityID property and adjust discoveryURL to point to discovery service.
(Set discoveryProtocol to "WAYF" for legacy Shibboleth WAYF support.)
You can also override entityID on /Login query string, or in RequestMap/htaccess.
-->
<SSO entityID="https://samltest.id/saml/idp">
SAML2 SAML1
</SSO>
<!-- SAML and local-only logout. -->
<Logout>SAML2 Local</Logout>
<!-- Extension service that generates "approximate" metadata based on SP configuration. -->
<Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
<!-- Status reporting service. -->
<Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
<!-- Session diagnostic service. -->
<Handler type="Session" Location="/Session" showAttributeValues="false"/>
<!-- JSON feed of discovery information. -->
<Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
</Sessions>
<!--
Allows overriding of error template information/filenames. You can
also add attributes with values that can be plugged into the templates.
-->
<Errors supportContact="root@localhost"
helpLocation="/about.html"
styleSheet="/shibboleth-sp/main.css"/>
<!-- Example of remotely supplied batch of signed metadata. -->
<!--
<MetadataProvider type="XML" uri="http://federation.org/federation-metadata.xml"
backingFilePath="federation-metadata.xml" reloadInterval="7200">
<MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
<MetadataFilter type="Signature" certificate="fedsigner.pem"/>
</MetadataProvider>
-->
<!-- Example of locally maintained metadata. -->
<!--
<MetadataProvider type="XML" file="partner-metadata.xml"/>
-->
<MetadataProvider type="XML" uri="https://samltest.id/saml/idp"/>
<!-- Map to extract attributes from SAML assertions. -->
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
<!-- Use a SAML query if no attributes are supplied during SSO. -->
<AttributeResolver type="Query" subjectMatch="true"/>
<!-- Default filtering policy for recognized attributes, lets other data pass. -->
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<!-- Simple file-based resolver for using a single keypair. -->
<CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
<!--
The default settings can be overridden by creating ApplicationOverride elements (see
the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApplicationOverride topic).
Resource requests are mapped by web server commands, or the RequestMapper, to an
applicationId setting.
Example of a second application (for a second vhost) that has a different entityID.
Resources on the vhost would map to an applicationId of "admin":
-->
<!--
<ApplicationOverride id="admin" entityID="https://admin.example.org/shibboleth"/>
-->
</ApplicationDefaults>
<!-- Policies that determine how to process and authenticate runtime messages. -->
<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
<!-- Low-level configuration about protocols and bindings available for use. -->
<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
</SPConfig>
If keystone is your IdP, you will need to examine your attributes map file
``/etc/shibboleth/attribute-map.xml`` and add the following attributes:
.. code-block:: xml .. code-block:: xml
@ -263,25 +238,36 @@ If keystone is your IdP, you will need to examine your attributes map file
<Attribute name="openstack_user_domain" id="openstack_user_domain"/> <Attribute name="openstack_user_domain" id="openstack_user_domain"/>
<Attribute name="openstack_project_domain" id="openstack_project_domain"/> <Attribute name="openstack_project_domain" id="openstack_project_domain"/>
For more information see the And update the ``REMOTE_USER`` variable in ``/etc/shibboleth/shibboleth2.xml``
`attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_ if desired:
Once you are done, restart your Shibboleth daemon and apache: .. 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 .. code-block:: console
# service shibd restart # systemctl restart shibd
# service apache2 restart
Check ``/var/log/shibboleth/shibd_warn.log`` for any ERROR or CRIT notices and Exchange Metadata
correct them. ~~~~~~~~~~~~~~~~~
Upload your Service Provider's metadata file to your Identity Provider. You can Once configured, the Service Provider metadata is available to download:
fetch it with:
.. code-block:: console .. code-block:: console
# wget https://sp.keystone.example.org/Shibboleth.sso/Metadata # wget https://sp.keystone.example.org/Shibboleth.sso/Metadata
This step depends on your Identity Provider choice and is not covered here. Upload your Service Provider's metadata to your Identity Provider. This step
If keystone is your Identity Provider you do not need to upload this file. 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