From b8c756ecdd7cced1db4300935484e8c83701c82e Mon Sep 17 00:00:00 2001 From: WuKong Date: Tue, 30 Jun 2015 18:47:29 +0200 Subject: migrate moon code from github to opnfv Change-Id: Ice53e368fd1114d56a75271aa9f2e598e3eba604 Signed-off-by: WuKong --- keystone-moon/doc/source/extensions/shibboleth.rst | 279 +++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 keystone-moon/doc/source/extensions/shibboleth.rst (limited to 'keystone-moon/doc/source/extensions/shibboleth.rst') diff --git a/keystone-moon/doc/source/extensions/shibboleth.rst b/keystone-moon/doc/source/extensions/shibboleth.rst new file mode 100644 index 00000000..d67cfa1a --- /dev/null +++ b/keystone-moon/doc/source/extensions/shibboleth.rst @@ -0,0 +1,279 @@ +:orphan: + +.. + 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. + +================ +Setup Shibboleth +================ + +Configure Apache HTTPD for mod_shibboleth +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Follow the steps outlined at: `Running Keystone in HTTPD`_. + +.. _`Running Keystone in HTTPD`: ../apache-httpd.html + +You'll also need to install `Shibboleth `_, for +example: + +.. code-block:: bash + + $ apt-get install libapache2-mod-shib2 + +Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: + +Add *WSGIScriptAlias* directive to your vhost configuration:: + + WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1 + +Make sure the *wsgi-keystone.conf* contains a ** directive for the Shibboleth module and +a ** directive for each identity provider:: + + + SetHandler shib + + + + ShibRequestSetting requireSession 1 + ShibRequestSetting applicationId idp_1 + AuthType shibboleth + ShibRequireAll On + ShibRequireSession On + ShibExportAssertion Off + Require valid-user + + +.. NOTE:: + * ``saml2`` may be different in your deployment, but do not use a wildcard value. + Otherwise *every* federated protocol will be handled by Shibboleth. + * ``idp_1`` has to be replaced with the name associated with the idp in Keystone. + The same name is used inside the shibboleth2.xml configuration file but they could + be different. + * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in + Apache 2.4+ and should be dropped in that specific setup. + * You are advised to carefully examine `Shibboleth Apache configuration + documentation + `_ + +Enable the Keystone virtual host, for example: + +.. code-block:: bash + + $ a2ensite wsgi-keystone.conf + +Enable the ``ssl`` and ``shib2`` modules, for example: + +.. code-block:: bash + + $ a2enmod ssl + $ a2enmod shib2 + +Restart Apache, for example: + +.. code-block:: bash + + $ service apache2 restart + +Configuring shibboleth2.xml +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you have your Keystone vhost (virtual host) ready, it's then time to +configure Shibboleth and upload your Metadata to the Identity Provider. + +If new certificates are required, they can be easily created by executing: + +.. code-block:: bash + + $ shib-keygen -y + +The newly created file will be stored under ``/etc/shibboleth/sp-key.pem`` + +You should fetch your Service Provider's Metadata file. Typically this can be +achieved by simply fetching a Metadata file, for example: + +.. code-block:: bash + + $ wget --no-check-certificate -O https://service.example.org/Shibboleth.sso/Metadata + +Upload your Service Provider's Metadata file to your Identity Provider. +This step depends on your Identity Provider choice and is not covered here. + +Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml`` +file. You are advised to examine `Shibboleth Service Provider Configuration documentation `_ + +An example of your ``/etc/shibboleth/shibboleth2.xml`` may look like +(The example shown below is for reference only, not to be used in a production +environment): + +.. code-block:: xml + + + + + + + + + + + + + + + + SAML2 SAML1 + + + + + SAML2 Local + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + SAML2 SAML1 + + + SAML2 Local + + + + + + + + + + + + SAML2 SAML1 + + + SAML2 Local + + + + + + + + + + + + + + + + +Keystone enforces `external authentication`_ when the ``REMOTE_USER`` +environment variable is present so make sure Shibboleth doesn't set the +``REMOTE_USER`` environment variable. To do so, scan through the +``/etc/shibboleth/shibboleth2.xml`` configuration file and remove the +``REMOTE_USER`` directives. + +Examine your attributes map file ``/etc/shibboleth/attributes-map.xml`` and adjust +your requirements if needed. For more information see +`attributes documentation `_ + +Once you are done, restart your Shibboleth daemon: + +.. _`external authentication`: ../external-auth.html + +.. code-block:: bash + + $ service shibd restart + $ service apache2 restart -- cgit 1.2.3-korg