..
      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
============

------------------------------------------
Configure Apache HTTPD for mod_auth_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:

.. 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 this *WSGIScriptAlias* directive to your public vhost configuration::

    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

.. code-block:: none

    <Location /v3>
        MellonEnable "info"
        MellonSPPrivateKeyFile /etc/apache2/mellon/http_keystone.fqdn.key
        MellonSPCertFile /etc/apache2/mellon/http_keystone.fqdn.cert
        MellonSPMetadataFile /etc/apache2/mellon/http_keystone.fqdn.xml
        MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml
        MellonEndpointPath /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon
        MellonIdP "IDP"
    </Location>

    <Location /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth>
        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>`_
    * ``myidp`` 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>`_

Enable the ``auth_mellon`` module, for example:

.. code-block:: bash

    $ a2enmod 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:: bash

    $ ./mellon_create_metadata.sh http://keystone.fqdn:5000 \
      http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/myidp/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 testshib.org) 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.

After generating the keypair and metadata, copy the files to the locations
given in the Mellon directives in your apache configs.

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
`MellonSPMetadataFile` in the config. 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.

Fetch your Identity Provider's Metadata file and copy it to the path specified
by the `MellonIdPMetadataFile` directive above. For example:

.. code-block:: bash

    $ wget --cacert /path/to/ca.crt -O /etc/apache2/mellon/idp-metadata.xml \
      https://idp.fqdn/idp/saml2/metadata

Once you are done, restart the Apache instance that is serving Keystone, for example:

.. code-block:: bash

    $ service apache2 restart

.. _`mellon_create_metadata.sh`: https://github.com/UNINETT/mod_auth_mellon/blob/master/mellon_create_metadata.sh