Merge "add federation docs for mod_auth_mellon"

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.
+There is currently support for two major federation protocols:
-Using Shibboleth and OpenID Connect are documented so far.
 
-* To use Shibboleth, follow the steps outlined at: `Setup Shibboleth`_.
+* SAML - Keystone supports the following implementations:
-* To use OpenID Connect, follow the steps outlined at: `Setup OpenID Connect`_.
+
+  * 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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
+<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 *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 *<Location>* directive for the Mellon module and
+a *<Location>* directive for each identity provider::
+
+    <Location /v3>
+        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"
+    </Location>
+
+    <Location /v3/OS-FEDERATION/identity_providers/idp_1/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`` 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
+      <https://github.com/UNINETT/mod_auth_mellon>`_
+
+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

doc/source/federation/websso.rst

@@ -89,6 +89,22 @@ If `mod_auth_kerb` is used, then use the following as an example:
       </Location>
   </VirtualHost>
 
+If `mod_auth_mellon` is used, then use the following as an example:
+
+.. code-block:: xml
+
+  <VirtualHost *:5000>
+
+      ...
+
+      <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
+        AuthType Mellon
+        MellonEnable auth
+        Require valid-user
+        ...
+      </Location>
+  </VirtualHost>
+
 .. 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.