125 lines
5.0 KiB
ReStructuredText
Raw Normal View History

: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
============
------------------------------------------
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"
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
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
Partially clarify federation auth plugins Federation protocols in keystone are very confusing due to the way they have evolved since the original service provider implementation where the auth plugin was defined in saml2.py. We renamed saml2.py to mapped.py[1] and now we can effectively support any federation protocol as long as there is some kind of Apache module that can understand it and pass certain IdP and user attributes through to keystone. So we started recommending not using the 'saml2' auth plugin and instead using the 'mapped' plugin, eventually removing the the notice when we removed the plugin[2]. Since the name of the federation protocol resource created in keystone must match one of the [auth]/methods, we also changed the documentation to start creating the 'mapped' protocol and use 'mapped' in the Apache settings[3]. This was really the wrong course. 'mapped' is not a protocol. Using only 'mapped' prevents us from defining multiple remote_id_attributes for different protocols. This patch changes references to the 'mapped' protocol and 'mapped' plugin back to 'saml2' (we never changed the openid ones). While the saml2 plugin does not itself exist, it is defined as an entrypoint to the mapped plugin, so it all works out. This doesn't solve the problem for if we want to define different remote_id_attributes for different SAML2.0 implementations, but there is a workaround for that[4]. Using 'saml2' as the protocol name is just much more intuitive than 'mapped'. [1] https://git.openstack.org/cgit/openstack/keystone-specs/tree/specs/keystone/juno/generic-mapping-federation.rst [2] https://review.openstack.org/#/c/397456/ [3] https://review.openstack.org/#/c/371210/ [4] https://bugs.launchpad.net/keystone/+bug/1724645/comments/1 Change-Id: I23fc3f1f651c12c4e3c1987dc71008e6e97b4ed8 Related-bug: #1724645
2017-10-21 20:38:34 +02:00
MellonEndpointPath /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon
MellonIdP "IDP"
</Location>
Partially clarify federation auth plugins Federation protocols in keystone are very confusing due to the way they have evolved since the original service provider implementation where the auth plugin was defined in saml2.py. We renamed saml2.py to mapped.py[1] and now we can effectively support any federation protocol as long as there is some kind of Apache module that can understand it and pass certain IdP and user attributes through to keystone. So we started recommending not using the 'saml2' auth plugin and instead using the 'mapped' plugin, eventually removing the the notice when we removed the plugin[2]. Since the name of the federation protocol resource created in keystone must match one of the [auth]/methods, we also changed the documentation to start creating the 'mapped' protocol and use 'mapped' in the Apache settings[3]. This was really the wrong course. 'mapped' is not a protocol. Using only 'mapped' prevents us from defining multiple remote_id_attributes for different protocols. This patch changes references to the 'mapped' protocol and 'mapped' plugin back to 'saml2' (we never changed the openid ones). While the saml2 plugin does not itself exist, it is defined as an entrypoint to the mapped plugin, so it all works out. This doesn't solve the problem for if we want to define different remote_id_attributes for different SAML2.0 implementations, but there is a workaround for that[4]. Using 'saml2' as the protocol name is just much more intuitive than 'mapped'. [1] https://git.openstack.org/cgit/openstack/keystone-specs/tree/specs/keystone/juno/generic-mapping-federation.rst [2] https://review.openstack.org/#/c/397456/ [3] https://review.openstack.org/#/c/371210/ [4] https://bugs.launchpad.net/keystone/+bug/1724645/comments/1 Change-Id: I23fc3f1f651c12c4e3c1987dc71008e6e97b4ed8 Related-bug: #1724645
2017-10-21 20:38:34 +02:00
<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.
Partially clarify federation auth plugins Federation protocols in keystone are very confusing due to the way they have evolved since the original service provider implementation where the auth plugin was defined in saml2.py. We renamed saml2.py to mapped.py[1] and now we can effectively support any federation protocol as long as there is some kind of Apache module that can understand it and pass certain IdP and user attributes through to keystone. So we started recommending not using the 'saml2' auth plugin and instead using the 'mapped' plugin, eventually removing the the notice when we removed the plugin[2]. Since the name of the federation protocol resource created in keystone must match one of the [auth]/methods, we also changed the documentation to start creating the 'mapped' protocol and use 'mapped' in the Apache settings[3]. This was really the wrong course. 'mapped' is not a protocol. Using only 'mapped' prevents us from defining multiple remote_id_attributes for different protocols. This patch changes references to the 'mapped' protocol and 'mapped' plugin back to 'saml2' (we never changed the openid ones). While the saml2 plugin does not itself exist, it is defined as an entrypoint to the mapped plugin, so it all works out. This doesn't solve the problem for if we want to define different remote_id_attributes for different SAML2.0 implementations, but there is a workaround for that[4]. Using 'saml2' as the protocol name is just much more intuitive than 'mapped'. [1] https://git.openstack.org/cgit/openstack/keystone-specs/tree/specs/keystone/juno/generic-mapping-federation.rst [2] https://review.openstack.org/#/c/397456/ [3] https://review.openstack.org/#/c/371210/ [4] https://bugs.launchpad.net/keystone/+bug/1724645/comments/1 Change-Id: I23fc3f1f651c12c4e3c1987dc71008e6e97b4ed8 Related-bug: #1724645
2017-10-21 20:38:34 +02:00
* ``saml2`` is the name of the `protocol that you will configure <configure_federation.html#protocol>`_
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
* ``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>`_
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
Enable the ``auth_mellon`` module, for example:
.. code-block:: bash
$ a2enmod auth_mellon
----------------------------------
Configuring the Mellon SP Metadata
----------------------------------
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
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
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
$ ./mellon_create_metadata.sh http://keystone.fqdn:5000 \
Partially clarify federation auth plugins Federation protocols in keystone are very confusing due to the way they have evolved since the original service provider implementation where the auth plugin was defined in saml2.py. We renamed saml2.py to mapped.py[1] and now we can effectively support any federation protocol as long as there is some kind of Apache module that can understand it and pass certain IdP and user attributes through to keystone. So we started recommending not using the 'saml2' auth plugin and instead using the 'mapped' plugin, eventually removing the the notice when we removed the plugin[2]. Since the name of the federation protocol resource created in keystone must match one of the [auth]/methods, we also changed the documentation to start creating the 'mapped' protocol and use 'mapped' in the Apache settings[3]. This was really the wrong course. 'mapped' is not a protocol. Using only 'mapped' prevents us from defining multiple remote_id_attributes for different protocols. This patch changes references to the 'mapped' protocol and 'mapped' plugin back to 'saml2' (we never changed the openid ones). While the saml2 plugin does not itself exist, it is defined as an entrypoint to the mapped plugin, so it all works out. This doesn't solve the problem for if we want to define different remote_id_attributes for different SAML2.0 implementations, but there is a workaround for that[4]. Using 'saml2' as the protocol name is just much more intuitive than 'mapped'. [1] https://git.openstack.org/cgit/openstack/keystone-specs/tree/specs/keystone/juno/generic-mapping-federation.rst [2] https://review.openstack.org/#/c/397456/ [3] https://review.openstack.org/#/c/371210/ [4] https://bugs.launchpad.net/keystone/+bug/1724645/comments/1 Change-Id: I23fc3f1f651c12c4e3c1987dc71008e6e97b4ed8 Related-bug: #1724645
2017-10-21 20:38:34 +02:00
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
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
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.
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
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
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
$ 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
Correct and enhance Mellon federation docs Make corrections to the mod_auth_mellon federation documentation for consistency and clarity, including: - Remove reference to shibboleth.xml when explaining the remote-id attribute in the main federation configuration instructions, as this does not generalize to all IdPs - Change references from /etc/httpd to /etc/apache2 because the document begins with an apt-get so it follows that the rest of the examples should assume a Debian-like environment - Change references to example IdP 'idp_1' to 'myidp' for consistency with the shibboleth examples - Change references to example protocol 'saml2' to 'mapped' since the saml2 auth plugin was removed[1] - Remove references to wsgi-keystone.conf since devstack just calls it keystone.conf, and enabling this vhost is already covered in the "Running Keystone in HTTPD" section - Remove reference to the ssl mod: it's obviously recommended but not strictly relevant to this topic - Remove instruction to restart apache immediately after enabling auth_mellon, as it would fail while Mellon is not yet fully configured. The document already mentions restarting apache after Mellon is configured. - Add a link to the mellon_create_metadata.sh script, since this does not come as an executable with the mod package. - Add tip about the SP metadata file generated by mod_auth_mellon - Move paragraph about fetching the IdP metadata to the end of the section so that the information about generating and uploading the SP metadata is grouped together [1] https://review.openstack.org/#/c/374508/ Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
2017-02-22 15:15:08 +01:00
.. _`mellon_create_metadata.sh`: https://github.com/UNINETT/mod_auth_mellon/blob/master/mellon_create_metadata.sh