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
This commit is contained in:
parent
83c37f4a94
commit
dcb9d8d084
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue