Merge "add federation docs for mod_auth_mellon"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
6a6fcc22be
@ -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.
|
||||
Using Shibboleth and OpenID Connect are documented so far.
|
||||
There is currently support for two major federation protocols:
|
||||
|
||||
* To use Shibboleth, follow the steps outlined at: `Setup Shibboleth`_.
|
||||
* To use OpenID Connect, follow the steps outlined at: `Setup OpenID Connect`_.
|
||||
* SAML - Keystone supports the following implementations:
|
||||
|
||||
* 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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
122
doc/source/federation/mellon.rst
Normal file
122
doc/source/federation/mellon.rst
Normal file
@ -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
|
||||
@ -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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user