Merge "Enhance the mellon guide"

This commit is contained in:
Zuul 2019-01-09 03:16:19 +00:00 committed by Gerrit Code Review
commit 0ffc236fb1
2 changed files with 84 additions and 54 deletions

View File

@ -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

View File

@ -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
<https://github.com/UNINETT/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 *<Location>* directive for the Mellon module and
a *<Location>* 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
``<Location>`` directive near the top in your keystone VirtualHost file, before
your protected endpoints:
.. code-block:: apache
@ -49,54 +61,60 @@ a *<Location>* 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"
</Location>
Configure Protected Endpoints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configure each protected path to use the ``Mellon`` AuthType:
.. code-block:: apache
<Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
AuthType "Mellon"
MellonEnable "auth"
Require valid-user
AuthType Mellon
MellonEnable auth
</Location>
.. 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 <configure_federation.html#protocol>`_
* ``samltest`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
* You are advised to carefully examine `mod_auth_mellon Apache
configuration documentation
<https://github.com/UNINETT/mod_auth_mellon>`_
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
<Location /v3/auth/OS-FEDERATION/websso/saml2>
Require valid-user
AuthType Mellon
MellonEnable auth
</Location>
<Location /v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso>
Require valid-user
AuthType Mellon
MellonEnable auth
</Location>
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 `<KeyDescriptor use="signing">` to
`<KeyDescriptor use="encryption">` 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