Browse Source

Enhance the mellon guide

Update, reorganize and clean up the mellon guide. Use the systemctl
command to modernize the service management commands. Add examples of
configuring all required endpoints in Apache to mirror the new section
on configuring protected endpoints in the main guide and replace the
lost examples from the consolidated WebSSO guide. Remove use of
``a2enmod`` since the Mellon module is automatically enabled by the
package on all supported distros.

Partial-bug: #1793374

Change-Id: If17d8e73688775b8aeae88f5d0907273bc8de193
tags/15.0.0.0rc1
Colleen Murphy 5 months ago
parent
commit
dcb9d8d084

+ 3
- 1
doc/source/admin/federation/configure_federation.rst View File

@@ -372,7 +372,9 @@ associate the incoming request with the Identity Provider resource. The key name
372 372
 is decided by the auth module choice:
373 373
 
374 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 378
 * For ``mod_auth_openidc``: use ``HTTP_OIDC_ISS``
377 379
 
378 380
 It is recommended that this option be set on a per-protocol basis by creating a

+ 78
- 50
doc/source/admin/federation/mellon.rst View File

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

Loading…
Cancel
Save