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
This commit is contained in:
Colleen Murphy
Colleen Murphy
parent
1d4c72cd6f
commit
95afd48fde
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -44,15 +44,15 @@ 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
|
||||
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"
|
||||
</Location>
|
||||
|
||||
<Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth>
|
||||
<Location /v3/OS-FEDERATION/identity_providers/myidp/protocols/mapped/auth>
|
||||
AuthType "Mellon"
|
||||
MellonEnable "auth"
|
||||
</Location>
|
||||
|
|
@ -60,66 +60,62 @@ a *<Location>* 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 <configure_federation.html#protocol>`_
|
||||
* ``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>`_
|
||||
|
||||
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 `<KeyDescriptor use="signing">` to
|
||||
`<KeyDescriptor use="encryption">` 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue