openstack/keystone
Code Issues Proposed changes
1041d3340c
keystone/doc/source/federation/mellon.rst
Rich Megginson 4f36d900e6 add federation docs for mod_auth_mellon 
mod_auth_mellon is an authentication module for Apache.
It authenticates the user against a SAML 2.0 IdP, and
grants access to directories depending on attributes
received from the IdP.  It can be used by Keystone to provide
authentication via the
keystone.contrib.federation.backends.sql.Federation federation
authentication driver for the saml2 auth method.

closes-bug: #1470952

Change-Id: Id0467abe37ac4c4c74832ca5bb98f98c63afded1
2015-07-21 12:10:30 -06:00

4.5 KiB
Raw Blame History

orphan

Setup Mellon (mod_auth_mellon)

Configure Apache HTTPD for mod_auth_mellon

Follow the steps outlined at: Running Keystone in HTTPD.

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

Enable the Keystone virtual host, for example:

$ a2ensite wsgi-keystone.conf

Enable the ssl and auth_mellon modules, for example:

$ a2enmod ssl
$ a2enmod auth_mellon

Restart the Apache instance that is serving Keystone, for example:

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

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

$ service apache2 restart