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