summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2019-01-09 03:16:19 +0000
committerGerrit Code Review <review@openstack.org>2019-01-09 03:16:19 +0000
commit0ffc236fb11cdfe748694ce60dfd0c41b4ca6e20 (patch)
tree28a54f5d46778bf8b58232458f443fa9ae55b47b
parent01b964955ac4e5369cc36bfe387329b82338e820 (diff)
parentdcb9d8d084a60c1e8f83adf0a9ae84df9cc85ebe (diff)
Merge "Enhance the mellon guide"
-rw-r--r--doc/source/admin/federation/configure_federation.rst4
-rw-r--r--doc/source/admin/federation/mellon.rst128
2 files changed, 81 insertions, 51 deletions
diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst
index 53d3441..3ebde28 100644
--- a/doc/source/admin/federation/configure_federation.rst
+++ b/doc/source/admin/federation/configure_federation.rst
@@ -372,7 +372,9 @@ associate the incoming request with the Identity Provider resource. The key name
372is decided by the auth module choice: 372is decided by the auth module choice:
373 373
374* For ``mod_shib``: use ``Shib-Identity-Provider`` 374* For ``mod_shib``: use ``Shib-Identity-Provider``
375* For ``mod_auth_mellon``: use ``MELLON_IDP`` 375* For ``mod_auth_mellon``: the attribute name is configured with the
376 ``MellonIdP`` parameter in the VirtualHost configuration, if set to e.g.
377 ``IDP`` then use ``MELLON_IDP``
376* For ``mod_auth_openidc``: use ``HTTP_OIDC_ISS`` 378* For ``mod_auth_openidc``: use ``HTTP_OIDC_ISS``
377 379
378It is recommended that this option be set on a per-protocol basis by creating a 380It is recommended that this option be set on a per-protocol basis by creating a
diff --git a/doc/source/admin/federation/mellon.rst b/doc/source/admin/federation/mellon.rst
index 137eeac..edc4699 100644
--- a/doc/source/admin/federation/mellon.rst
+++ b/doc/source/admin/federation/mellon.rst
@@ -11,35 +11,47 @@
11 License for the specific language governing permissions and limitations 11 License for the specific language governing permissions and limitations
12 under the License. 12 under the License.
13 13
14------------ 14-----------------
15Setup Mellon 15Setting Up Mellon
16------------ 16-----------------
17 17
18Configure Apache HTTPD for mod_auth_mellon 18See :ref:`keystone-as-sp` before proceeding with these Mellon-specific
19------------------------------------------ 19instructions.
20 20
21Configure keystone under Apache, following the steps in the install guide for 21Configuring Apache HTTPD for mod_auth_mellon
22`SUSE`_, `RedHat`_ or `Ubuntu`_. 22--------------------------------------------
23
24.. note::
25
26 You are advised to carefully examine the `mod_auth_mellon documentation`_.
27
28.. _mod_auth_mellon documentation: https://github.com/Uninett/mod_auth_mellon/blob/master/doc/user_guide/mellon_user_guide.adoc#installing-configuring-mellon
29
30Follow the steps outlined at: Keystone install guide for `SUSE`_, `RedHat`_ or
31`Ubuntu`_.
23 32
24.. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server 33.. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server
25.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server 34.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
26.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server 35.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
27 36
28You'll also need to install the Apache module `mod_auth_mellon 37Install the Module
29<https://github.com/UNINETT/mod_auth_mellon>`_. For example: 38~~~~~~~~~~~~~~~~~~
39
40Install the Apache module package. For example, on Ubuntu:
30 41
31.. code-block:: console 42.. code-block:: console
32 43
33 # apt-get install libapache2-mod-auth-mellon 44 # apt-get install libapache2-mod-auth-mellon
34 45
35Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: 46The package and module name will differ between distributions.
36 47
37Add this *WSGIScriptAlias* directive to your public vhost configuration:: 48Configure mod_auth_mellon
49~~~~~~~~~~~~~~~~~~~~~~~~~
38 50
39 WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /usr/local/bin/keystone-wsgi-public/$1 51Unlike ``mod_shib``, all of ``mod_auth_mellon``'s configuration is done in
40 52Apache, not in a separate config file. Set up the shared settings in a single
41Make sure the *wsgi-keystone.conf* contains a *<Location>* directive for the Mellon module and 53``<Location>`` directive near the top in your keystone VirtualHost file, before
42a *<Location>* directive for each identity provider 54your protected endpoints:
43 55
44.. code-block:: apache 56.. code-block:: apache
45 57
@@ -49,54 +61,60 @@ a *<Location>* directive for each identity provider
49 MellonSPCertFile /etc/apache2/mellon/sp.keystone.example.org.cert 61 MellonSPCertFile /etc/apache2/mellon/sp.keystone.example.org.cert
50 MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml 62 MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml
51 MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml 63 MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml
52 MellonEndpointPath /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth/mellon 64 MellonEndpointPath /v3/mellon
53 MellonIdP "IDP" 65 MellonIdP "IDP"
54 </Location> 66 </Location>
55 67
68Configure Protected Endpoints
69~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70
71Configure each protected path to use the ``Mellon`` AuthType:
72
73.. code-block:: apache
74
56 <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth> 75 <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
57 AuthType "Mellon" 76 Require valid-user
58 MellonEnable "auth" 77 AuthType Mellon
78 MellonEnable auth
59 </Location> 79 </Location>
60 80
61.. NOTE:: 81Do the same for the WebSSO auth paths if using horizon as a single sign-on
62 * See below for information about how to generate the values for the 82frontend:
63 `MellonSPMetadataFile`, etc. directives.
64 * ``saml2`` is the name of the `protocol that you will configure <configure_federation.html#protocol>`_
65 * ``samltest`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
66 * You are advised to carefully examine `mod_auth_mellon Apache
67 configuration documentation
68 <https://github.com/UNINETT/mod_auth_mellon>`_
69 83
70Enable the ``auth_mellon`` module, for example: 84.. code-block:: apache
71
72.. code-block:: console
73 85
74 # a2enmod auth_mellon 86 <Location /v3/auth/OS-FEDERATION/websso/saml2>
87 Require valid-user
88 AuthType Mellon
89 MellonEnable auth
90 </Location>
91 <Location /v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso>
92 Require valid-user
93 AuthType Mellon
94 MellonEnable auth
95 </Location>
75 96
76Configuring the Mellon SP Metadata 97Configure the Mellon Service Provider Metadata
77---------------------------------- 98~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78 99
79Mellon provides a script called `mellon_create_metadata.sh`_ which generates 100Mellon provides a script called ``mellon_create_metadata.sh``_ which generates
80the values for the config directives `MellonSPPrivateKeyFile`, 101the values for the config directives ``MellonSPPrivateKeyFile``,
81`MellonSPCertFile`, and `MellonSPMetadataFile`. It is run like this: 102``MellonSPCertFile``, and ``MellonSPMetadataFile``. Run the script:
82 103
83.. code-block:: console 104.. code-block:: console
84 105
85 $ ./mellon_create_metadata.sh https://sp.keystone.example.org/mellon\ 106 $ ./mellon_create_metadata.sh \
86 https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth/mellon 107 https://sp.keystone.example.org/mellon \
108 http://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth/mellon
87 109
88The first parameter is used as the entity ID, a unique identifier for this 110The first parameter is used as the entity ID, a URN of your choosing that must
89Keystone SP. You do not have to use the URL, but it is an easy way to uniquely 111uniquely identify the Service Provider to the Identity Provider. The second
90identify each Keystone SP. The second parameter is the full URL for the 112parameter is the full URL for the endpoint path corresponding to the parameter
91endpoint path corresponding to the parameter `MellonEndpointPath`. Note that 113``MellonEndpointPath``.
92the metadata generated by this script includes a signing key but not an
93encryption key, and your IdP (such as samltest.id) may require an encryption
94key. Simply change the node `<KeyDescriptor use="signing">` to
95`<KeyDescriptor use="encryption">` or add another key to the file. Check your
96IdP documentation for details.
97 114
98After generating the keypair and metadata, copy the files to the locations 115After generating the keypair and metadata, copy the files to the locations
99given in the Mellon directives in your apache configs. 116given by the ``MellonSPPrivateKeyFile`` and ``MellonSPCertFile`` settings in
117your Apache configuration.
100 118
101Upload the Service Provider's Metadata file which you just generated to your 119Upload the Service Provider's Metadata file which you just generated to your
102Identity Provider. This is the file used as the value of the 120Identity Provider. This is the file used as the value of the
@@ -104,17 +122,27 @@ Identity Provider. This is the file used as the value of the
104can upload the file, or you may be required to submit the file using `wget` or 122can upload the file, or you may be required to submit the file using `wget` or
105`curl`. Please check your IdP documentation for details. 123`curl`. Please check your IdP documentation for details.
106 124
125Exchange Metadata
126~~~~~~~~~~~~~~~~~
127
107Fetch your Identity Provider's Metadata file and copy it to the path specified 128Fetch your Identity Provider's Metadata file and copy it to the path specified
108by the `MellonIdPMetadataFile` directive above. For example: 129by the ``MellonIdPMetadataFile`` setting in your Apache configuration.
109 130
110.. code-block:: console 131.. code-block:: console
111 132
112 $ wget -O /etc/apache2/mellon/idp-metadata.xml https://samltest.id/saml/idp 133 $ wget -O /etc/apache2/mellon/idp-metadata.xml https://samltest.id/saml/idp
113 134
114Once you are done, restart the Apache instance that is serving Keystone, for example: 135Remember to reload Apache after finishing configuring Mellon:
115 136
116.. code-block:: console 137.. code-block:: console
117 138
118 # service apache2 restart 139 # systemctl reload apache2
119 140
120.. _`mellon_create_metadata.sh`: https://github.com/UNINETT/mod_auth_mellon/blob/master/mellon_create_metadata.sh 141.. _`mellon_create_metadata.sh`: https://github.com/UNINETT/mod_auth_mellon/blob/master/mellon_create_metadata.sh
142
143Continue configuring keystone
144~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145
146`Continue configuring keystone`_
147
148.. _Continue configuring keystone: configure_federation.html#configuring-keystone