From dcb9d8d084a60c1e8f83adf0a9ae84df9cc85ebe Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Fri, 21 Dec 2018 20:12:58 -0800 Subject: [PATCH] Enhance the mellon guide Update, reorganize and clean up the mellon guide. Use the systemctl command to modernize the service management commands. Add examples of configuring all required endpoints in Apache to mirror the new section on configuring protected endpoints in the main guide and replace the lost examples from the consolidated WebSSO guide. Remove use of ``a2enmod`` since the Mellon module is automatically enabled by the package on all supported distros. Partial-bug: #1793374 Change-Id: If17d8e73688775b8aeae88f5d0907273bc8de193 --- .../admin/federation/configure_federation.rst | 4 +- doc/source/admin/federation/mellon.rst | 134 +++++++++++------- 2 files changed, 84 insertions(+), 54 deletions(-) diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst index 53d34410e2..3ebde284ae 100644 --- a/doc/source/admin/federation/configure_federation.rst +++ b/doc/source/admin/federation/configure_federation.rst @@ -372,7 +372,9 @@ associate the incoming request with the Identity Provider resource. The key name is decided by the auth module choice: * For ``mod_shib``: use ``Shib-Identity-Provider`` -* For ``mod_auth_mellon``: use ``MELLON_IDP`` +* For ``mod_auth_mellon``: the attribute name is configured with the + ``MellonIdP`` parameter in the VirtualHost configuration, if set to e.g. + ``IDP`` then use ``MELLON_IDP`` * For ``mod_auth_openidc``: use ``HTTP_OIDC_ISS`` It is recommended that this option be set on a per-protocol basis by creating a diff --git a/doc/source/admin/federation/mellon.rst b/doc/source/admin/federation/mellon.rst index 137eeac8d7..edc46991e4 100644 --- a/doc/source/admin/federation/mellon.rst +++ b/doc/source/admin/federation/mellon.rst @@ -11,35 +11,47 @@ License for the specific language governing permissions and limitations under the License. ------------- -Setup Mellon ------------- +----------------- +Setting Up Mellon +----------------- -Configure Apache HTTPD for mod_auth_mellon ------------------------------------------- +See :ref:`keystone-as-sp` before proceeding with these Mellon-specific +instructions. -Configure keystone under Apache, following the steps in the install guide for -`SUSE`_, `RedHat`_ or `Ubuntu`_. +Configuring Apache HTTPD for mod_auth_mellon +-------------------------------------------- + +.. note:: + + You are advised to carefully examine the `mod_auth_mellon documentation`_. + +.. _mod_auth_mellon documentation: https://github.com/Uninett/mod_auth_mellon/blob/master/doc/user_guide/mellon_user_guide.adoc#installing-configuring-mellon + +Follow the steps outlined at: Keystone 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 -You'll also need to install the Apache module `mod_auth_mellon -`_. For example: +Install the Module +~~~~~~~~~~~~~~~~~~ + +Install the Apache module package. For example, on Ubuntu: .. code-block:: console # apt-get install libapache2-mod-auth-mellon -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 *WSGIScriptAlias* directive to your public vhost configuration:: +Configure mod_auth_mellon +~~~~~~~~~~~~~~~~~~~~~~~~~ - WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /usr/local/bin/keystone-wsgi-public/$1 - -Make sure the *wsgi-keystone.conf* contains a ** directive for the Mellon module and -a ** directive for each identity provider +Unlike ``mod_shib``, all of ``mod_auth_mellon``'s configuration is done in +Apache, not in a separate config file. Set up the shared settings in a single +```` directive near the top in your keystone VirtualHost file, before +your protected endpoints: .. code-block:: apache @@ -49,54 +61,60 @@ a ** directive for each identity provider MellonSPCertFile /etc/apache2/mellon/sp.keystone.example.org.cert MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml - MellonEndpointPath /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth/mellon + MellonEndpointPath /v3/mellon MellonIdP "IDP" +Configure Protected Endpoints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configure each protected path to use the ``Mellon`` AuthType: + +.. code-block:: apache + - AuthType "Mellon" - MellonEnable "auth" + Require valid-user + AuthType Mellon + MellonEnable auth -.. NOTE:: - * See below for information about how to generate the values for the - `MellonSPMetadataFile`, etc. directives. - * ``saml2`` is the name of the `protocol that you will configure `_ - * ``samltest`` is the name associated with the `IdP in Keystone `_ - * You are advised to carefully examine `mod_auth_mellon Apache - configuration documentation - `_ +Do the same for the WebSSO auth paths if using horizon as a single sign-on +frontend: -Enable the ``auth_mellon`` module, for example: +.. code-block:: apache + + + Require valid-user + AuthType Mellon + MellonEnable auth + + + Require valid-user + AuthType Mellon + MellonEnable auth + + +Configure the Mellon Service Provider Metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mellon provides a script called ``mellon_create_metadata.sh``_ which generates +the values for the config directives ``MellonSPPrivateKeyFile``, +``MellonSPCertFile``, and ``MellonSPMetadataFile``. Run the script: .. code-block:: console - # a2enmod auth_mellon + $ ./mellon_create_metadata.sh \ + https://sp.keystone.example.org/mellon \ + http://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth/mellon -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:: console - - $ ./mellon_create_metadata.sh https://sp.keystone.example.org/mellon\ - https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/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`. Note that -the metadata generated by this script includes a signing key but not an -encryption key, and your IdP (such as samltest.id) may require an encryption -key. Simply change the node `` to -`` or add another key to the file. Check your -IdP documentation for details. +The first parameter is used as the entity ID, a URN of your choosing that must +uniquely identify the Service Provider to the Identity Provider. The second +parameter is the full URL for the endpoint path corresponding to the parameter +``MellonEndpointPath``. After generating the keypair and metadata, copy the files to the locations -given in the Mellon directives in your apache configs. +given by the ``MellonSPPrivateKeyFile`` and ``MellonSPCertFile`` settings in +your Apache configuration. Upload the Service Provider's Metadata file which you just generated to your Identity Provider. This is the file used as the value of the @@ -104,17 +122,27 @@ Identity Provider. This is the file used as the value of the can upload the file, or you may be required to submit the file using `wget` or `curl`. Please check your IdP documentation for details. +Exchange Metadata +~~~~~~~~~~~~~~~~~ + Fetch your Identity Provider's Metadata file and copy it to the path specified -by the `MellonIdPMetadataFile` directive above. For example: +by the ``MellonIdPMetadataFile`` setting in your Apache configuration. .. code-block:: console $ wget -O /etc/apache2/mellon/idp-metadata.xml https://samltest.id/saml/idp -Once you are done, restart the Apache instance that is serving Keystone, for example: +Remember to reload Apache after finishing configuring Mellon: .. code-block:: console - # service apache2 restart + # systemctl reload apache2 .. _`mellon_create_metadata.sh`: https://github.com/UNINETT/mod_auth_mellon/blob/master/mellon_create_metadata.sh + +Continue configuring keystone +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`Continue configuring keystone`_ + +.. _Continue configuring keystone: configure_federation.html#configuring-keystone