From 95afd48fde81aa0d279e86c08512a23e1a91536a Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Wed, 22 Feb 2017 15:15:08 +0100 Subject: [PATCH] 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 --- .../federation/configure_federation.rst | 14 ++-- doc/source/federation/mellon.rst | 72 +++++++++---------- 2 files changed, 41 insertions(+), 45 deletions(-) diff --git a/doc/source/federation/configure_federation.rst b/doc/source/federation/configure_federation.rst index 9e18b8f92d..9e27708c25 100644 --- a/doc/source/federation/configure_federation.rst +++ b/doc/source/federation/configure_federation.rst @@ -168,13 +168,13 @@ Provider we will use to authenticate end users: $ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp -The value for the ``remote-id`` option is the Entity ID provided by the IdP. It -is the same value that you set for the SSO entityID in /etc/shibboleth/shibboleth2.xml. -If the IdP is a Keystone IdP, it is the value set in that Keystone's -``[saml]/idp_entity_id`` option. It will usually appear as a URI but there -is no requirement for it to resolve to anything and may be arbitrarily decided -by the administrator of the IdP. The local name, here called 'myidp', is -decided by you and will be used by the mapping and protocol, and later for +The value for the ``remote-id`` option is the Entity ID provided by the IdP, +which can be found as the EntityDescriptor entityID in the IdP's provided +metadata. If the IdP is a keystone IdP, it is the value set in that keystone's +``[saml]/idp_entity_id`` option. It will usually appear as a URI but there is +no requirement for it to resolve to anything and may be arbitrarily decided by +the administrator of the IdP. The local name, here called 'myidp', is decided +by you and will be used by the mapping and protocol, and later for authentication. A keystone identity provider may have multiple `remote_ids` specified, this diff --git a/doc/source/federation/mellon.rst b/doc/source/federation/mellon.rst index 8445fc306f..6b1a20a353 100644 --- a/doc/source/federation/mellon.rst +++ b/doc/source/federation/mellon.rst @@ -44,15 +44,15 @@ a ** directive for each identity provider 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 + 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/mapped/auth/mellon MellonIdP "IDP" - + AuthType "Mellon" MellonEnable "auth" @@ -60,66 +60,62 @@ a ** directive for each identity provider .. 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. + * ``mapped`` is the name of the `protocol that you will configure `_ + * ``myidp`` is the name associated with the `IdP in Keystone `_ * You are advised to carefully examine `mod_auth_mellon Apache configuration documentation `_ -Enable the Keystone virtual host, for example: +Enable the ``auth_mellon`` module, 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: +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 + $ ./mellon_create_metadata.sh http://keystone.fqdn:5000 \ + http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/mapped/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`. +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 `` to +`` or add another key to the file. Check your +IdP documentation for details. -Fetch your Service Provider's Metadata file. This corresponds to the value of -the `MellonIdPMetadataFile` directive above. For example: +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/httpd/mellon/idp-metadata.xml \ + $ wget --cacert /path/to/ca.crt -O /etc/apache2/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 + +.. _`mellon_create_metadata.sh`: https://github.com/UNINETT/mod_auth_mellon/blob/master/mellon_create_metadata.sh