From 4f36d900e61bc3a56f4bf5b7775bbd88f2976ec5 Mon Sep 17 00:00:00 2001 From: Rich Megginson Date: Thu, 2 Jul 2015 11:43:06 -0600 Subject: [PATCH] add federation docs for mod_auth_mellon mod_auth_mellon is an authentication module for Apache. It authenticates the user against a SAML 2.0 IdP, and grants access to directories depending on attributes received from the IdP. It can be used by Keystone to provide authentication via the keystone.contrib.federation.backends.sql.Federation federation authentication driver for the saml2 auth method. closes-bug: #1470952 Change-Id: Id0467abe37ac4c4c74832ca5bb98f98c63afded1 --- doc/source/configure_federation.rst | 12 ++- doc/source/federation/mellon.rst | 122 ++++++++++++++++++++++++++++ doc/source/federation/websso.rst | 18 +++- 3 files changed, 147 insertions(+), 5 deletions(-) create mode 100644 doc/source/federation/mellon.rst diff --git a/doc/source/configure_federation.rst b/doc/source/configure_federation.rst index 0e7440f058..6325353bdd 100644 --- a/doc/source/configure_federation.rst +++ b/doc/source/configure_federation.rst @@ -56,14 +56,18 @@ To enable federation, you'll need to: Configure Apache to use a federation capable authentication method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are many ways to configure Federation in the Apache HTTPD server. -Using Shibboleth and OpenID Connect are documented so far. +There is currently support for two major federation protocols: -* To use Shibboleth, follow the steps outlined at: `Setup Shibboleth`_. -* To use OpenID Connect, follow the steps outlined at: `Setup OpenID Connect`_. +* SAML - Keystone supports the following implementations: + + * Shibboleth - see `Setup Shibboleth`_. + * Mellon - see `Setup Mellon`_. + +* OpenID Connect - see `Setup OpenID Connect`_. .. _`Setup Shibboleth`: federation/shibboleth.html .. _`Setup OpenID Connect`: federation/openidc.html +.. _`Setup Mellon`: federation/mellon.html Configure keystone and Horizon for Single Sign-On ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/federation/mellon.rst b/doc/source/federation/mellon.rst new file mode 100644 index 0000000000..9c4675b7eb --- /dev/null +++ b/doc/source/federation/mellon.rst @@ -0,0 +1,122 @@ +: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 Mellon (mod_auth_mellon) +============================== + +Configure Apache HTTPD for mod_auth_mellon +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Follow the steps outlined at: `Running Keystone in HTTPD`_. + +.. _`Running Keystone in HTTPD`: ../apache-httpd.html + +You'll also need to install the Apache module `mod_auth_mellon +`_. For example: + +.. code-block:: bash + + $ apt-get install libapache2-mod-auth-mellon + +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 Mellon module and +a ** directive for each identity provider:: + + + MellonEnable "info" + MellonSPPrivateKeyFile /etc/httpd/mellon/http_keystone.fqdn.key + MellonSPCertFile /etc/httpd/mellon/http_keystone.fqdn.cert + MellonSPMetadataFile /etc/httpd/mellon/http_keystone.fqdn.xml + MellonIdPMetadataFile /etc/httpd/mellon/idp-metadata.xml + MellonEndpointPath /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon + MellonIdP "IDP" + + + + AuthType "Mellon" + MellonEnable "auth" + + +.. NOTE:: + * See below for information about how to generate the values for the + `MellonSPMetadataFile`, etc. directives. + * ``saml2`` may be different in your deployment, but do not use a wildcard value. + Otherwise *every* federated protocol will be handled by Mellon. + * ``idp_1`` has to be replaced with the name associated with the IdP in Keystone. + * You are advised to carefully examine `mod_auth_mellon Apache + configuration documentation + `_ + +Enable the Keystone virtual host, for example: + +.. code-block:: bash + + $ a2ensite wsgi-keystone.conf + +Enable the ``ssl`` and ``auth_mellon`` modules, for example: + +.. code-block:: bash + + $ a2enmod ssl + $ a2enmod auth_mellon + +Restart the Apache instance that is serving Keystone, for example: + +.. code-block:: bash + + $ service apache2 restart + +Configuring the Mellon SP Metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mellon provides a script called ``mellon_create_metadata.sh`` which generates the +values for the config directives `MellonSPPrivateKeyFile`, `MellonSPCertFile`, +and `MellonSPMetadataFile`. It is run like this: + +.. code-block:: bash + + $ mellon_create_metadata.sh http://keystone.fqdn:5000 \ + http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon + +The first parameter is used as the entity ID, a unique identifier for this +Keystone SP. You do not have to use the URL, but it is an easy way to uniquely +identify each Keystone SP. The second parameter is the full URL for the +endpoint path corresponding to the parameter `MellonEndpointPath`. + +Fetch your Service Provider's Metadata file. This corresponds to the value of +the `MellonIdPMetadataFile` directive above. For example: + +.. code-block:: bash + + $ wget --cacert /path/to/ca.crt -O /etc/httpd/mellon/idp-metadata.xml \ + https://idp.fqdn/idp/saml2/metadata + +Upload your Service Provider's Metadata file to your Identity Provider. This +is the file used as the value of the `MellonSPMetadataFile` in the config, +generated by the `mellon_create_metadata.sh` script. The IdP may provide a +webpage where you can upload the file, or you may be required to submit the +file using `wget` or `curl`. Please check your IdP documentation for details. + +Once you are done, restart the Apache instance that is serving Keystone, for example: + +.. code-block:: bash + + $ service apache2 restart diff --git a/doc/source/federation/websso.rst b/doc/source/federation/websso.rst index e3f7a0920c..4ada0a4cc2 100644 --- a/doc/source/federation/websso.rst +++ b/doc/source/federation/websso.rst @@ -89,6 +89,22 @@ If `mod_auth_kerb` is used, then use the following as an example: +If `mod_auth_mellon` is used, then use the following as an example: + +.. code-block:: xml + + + + ... + + + AuthType Mellon + MellonEnable auth + Require valid-user + ... + + + .. NOTE:: If you are also using SSO via the API, don't forget to make the Location settings match your configuration used for the keystone identity provider @@ -101,7 +117,7 @@ A remote id attribute indicates the header to retrieve from the WSGI environment. This header contains information about the identity of the identity provider. For `mod_shib` this would be ``Shib-Identity-Provider``, for `mod_auth_openidc`, this could be -``HTTP_OIDC_ISS``. +``HTTP_OIDC_ISS``. For `mod_auth_mellon`, this could be ``MELLON_IDP``. It is recommended that this option be set on a per-protocol basis.