keystone/doc/source/admin/federation/mellon.rst

Setup Mellon

Configure Apache HTTPD for mod_auth_mellon

Configure keystone under Apache, following the steps in the install guide for SUSE, RedHat or Ubuntu.

You'll also need to install the Apache module mod_auth_mellon. For example:

$ 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

<Location /v3>
    MellonEnable "info"
    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/saml2/auth/mellon
    MellonIdP "IDP"
</Location>

<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. * saml2 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 auth_mellon module, for example:

$ a2enmod auth_mellon

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_create_metadata.sh http://keystone.fqdn:5000 \
  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 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 samltest.id) 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.

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:

$ 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:

$ service apache2 restart