Browse Source

Enhance the shibboleth guide

Update, reorganize and clean up the shibboleth guide. Remove the full
example of shibboleth2.xml, it does not add anything useful and just
creates clutter. 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. Add a section on configuring REMOTE_USER and
attributes-map.xml. Remove use of ``a2enmod`` since the Shibboleth
module is automatically enabled by the package on all supported distros.

Partial-bug: #1793374

Change-Id: I0eed3420aa49fdc75349a467e91f8e7f22b075e9
tags/15.0.0.0rc1
Colleen Murphy 5 months ago
parent
commit
83c37f4a94

+ 2
- 0
doc/source/admin/federation/configure_federation.rst View File

@@ -14,6 +14,8 @@
14 14
 Configuring Keystone for Federation
15 15
 ===================================
16 16
 
17
+.. _keystone-as-sp:
18
+
17 19
 -----------------------------------
18 20
 Keystone as a Service Provider (SP)
19 21
 -----------------------------------

+ 167
- 181
doc/source/admin/federation/shibboleth.rst View File

@@ -11,12 +11,28 @@
11 11
       License for the specific language governing permissions and limitations
12 12
       under the License.
13 13
 
14
-----------------
15
-Setup Shibboleth
16
-----------------
14
+---------------------
15
+Setting up Shibboleth
16
+---------------------
17 17
 
18
-Configure Apache HTTPD for mod_shibboleth
19
------------------------------------------
18
+See :ref:`keystone-as-sp` before proceeding with these Shibboleth-specific
19
+instructions.
20
+
21
+.. note::
22
+
23
+   The examples below are for Ubuntu 16.04, for which only version 2 of the
24
+   Shibboleth Service Provider is available. Version 3 is available for other
25
+   distributions and the configuration should be identical to version 2.
26
+
27
+Configuring Apache HTTPD for mod_shib
28
+-------------------------------------
29
+
30
+.. note::
31
+
32
+   You are advised to carefully examine the `mod_shib Apache configuration
33
+   documentation`_.
34
+
35
+.. _mod_shib Apache configuration documentation: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig
20 36
 
21 37
 Configure keystone under Apache, following the steps in the install guide for
22 38
 `SUSE`_, `RedHat`_ or `Ubuntu`_.
@@ -25,21 +41,22 @@ Configure keystone under Apache, following the steps in the install guide for
25 41
 .. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
26 42
 .. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
27 43
 
28
-You'll also need to install `Shibboleth <https://wiki.shibboleth.net/confluence/display/SHIB2/Home>`_, for
29
-example:
44
+Install the Module
45
+~~~~~~~~~~~~~~~~~~
46
+
47
+Install the Apache module package. For example, on Ubuntu:
30 48
 
31 49
 .. code-block:: console
32 50
 
33 51
    # apt-get install libapache2-mod-shib2
34 52
 
35
-Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow:
36
-
37
-Add this *WSGIScriptAliasMatch* directive to your public vhost configuration::
53
+The package and module name will differ between distributions.
38 54
 
39
-    WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /usr/local/bin/keystone-wsgi-public/$1
55
+Configure Protected Endpoints
56
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40 57
 
41
-Make sure the keystone Apache virtual host configuration contains a *<Location>* directive for the
42
-Shibboleth module and a *<Location>* directive for each identity provider
58
+In the Apache configuration for the keystone VirtualHost, set an additional
59
+``<Location>`` which is not part of keystone's API:
43 60
 
44 61
 .. code-block:: apache
45 62
 
@@ -47,75 +64,118 @@ Shibboleth module and a *<Location>* directive for each identity provider
47 64
        SetHandler shib
48 65
    </Location>
49 66
 
67
+If you are using ``mod_proxy``, for example to proxy requests to the
68
+``/identity`` path to keystone's UWSGI service, you must exempt this Shibboleth
69
+endpoint from it:
70
+
71
+.. code-block:: apache
72
+
73
+   Proxypass Shibboleth.sso !
74
+
75
+Configure each protected path to use the ``shibboleth`` AuthType:
76
+
77
+.. code-block:: apache
78
+
50 79
    <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
80
+       Require valid-user
81
+       AuthType shibboleth
51 82
        ShibRequestSetting requireSession 1
83
+       ShibExportAssertion off
84
+       <IfVersion < 2.4>
85
+           ShibRequireSession On
86
+           ShibRequireAll On
87
+       </IfVersion>
88
+   </Location>
89
+
90
+Do the same for the WebSSO auth paths if using horizon as a single sign-on
91
+frontend:
92
+
93
+.. code-block:: apache
94
+
95
+   <Location /v3/auth/OS-FEDERATION/websso/saml2>
96
+       Require valid-user
52 97
        AuthType shibboleth
53
-       ShibExportAssertion Off
98
+       ShibRequestSetting requireSession 1
99
+       ShibExportAssertion off
100
+       <IfVersion < 2.4>
101
+           ShibRequireSession On
102
+           ShibRequireAll On
103
+       </IfVersion>
104
+   </Location>
105
+   <Location /v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso>
54 106
        Require valid-user
55
-
107
+       AuthType shibboleth
108
+       ShibRequestSetting requireSession 1
109
+       ShibExportAssertion off
56 110
        <IfVersion < 2.4>
57 111
            ShibRequireSession On
58 112
            ShibRequireAll On
59
-      </IfVersion>
113
+       </IfVersion>
60 114
    </Location>
61 115
 
62
-.. NOTE::
63
-    * ``saml2`` is the name of the `protocol that you will configure <configure_federation.html#protocol>`_
64
-    * ``samltest`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
65
-    * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in
66
-      Apache 2.4+.
67
-    * You are advised to carefully examine `Shibboleth Apache configuration
68
-      documentation
69
-      <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig>`_
70
-
71
-Enable the ``shib2`` module, for example:
116
+Remember to reload Apache after altering the VirtualHost:
72 117
 
73 118
 .. code-block:: console
74 119
 
75
-   # a2enmod shib2
76
-
77
-Restart Apache, for example:
120
+   # systemctl reload apache2
78 121
 
79
-.. code-block:: console
122
+Configuring mod_shib
123
+--------------------
80 124
 
81
-   # service apache2 restart
125
+.. note::
82 126
 
83
-Configuring shibboleth2.xml
84
----------------------------
127
+   You are advised to examine `Shibboleth Service Provider Configuration
128
+   documentation
129
+   <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_
85 130
 
86
-Once you have your Keystone vhost (virtual host) ready, it's then time to
87
-configure Shibboleth and upload your Metadata to the Identity Provider.
131
+Generate a keypair
132
+~~~~~~~~~~~~~~~~~~
88 133
 
89
-Create a new keypair for Shibboleth with:
134
+For all SAML Service Providers, a PKI key pair must be generated and exchanged
135
+with the Identity Provider. The ``mod_shib`` package on the Ubuntu distribution
136
+provides a utility to generate the key pair:
90 137
 
91 138
 .. code-block:: console
92 139
 
93 140
    # shib-keygen -y <number of years>
94 141
 
95
-The newly created key file will be stored under ``/etc/shibboleth/sp-key.pem``.
142
+which will generate a key pair under ``/etc/shibboleth``. In other cases, the
143
+package might generate the key pair automatically upon installation.
96 144
 
97
-Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml``
98
-file. You will want to change five settings:
145
+Configure metadata
146
+~~~~~~~~~~~~~~~~~~
99 147
 
100
-* Set the SP entity ID. This value usually has the form of a URI but it does not
101
-  have to resolve to anything. It must uniquely identify your Service Provider
102
-  to your Identity Provider.
148
+``mod_shib`` also has its own configuration file at
149
+``/etc/shibboleth/shibboleth2.xml`` that must be altered, as well
150
+as its own daemon. First, give the Service Provider an entity ID. This is a URN
151
+that you choose that must be globally unique to the Identity Provider:
103 152
 
104 153
 .. code-block:: xml
105 154
 
106
-   <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth">
155
+   <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
156
+       REMOTE_USER="eppn persistent-id targeted-id">
157
+
158
+Depending on your Identity Provider, you may also want to change the REMOTE_USER
159
+setting, more on that in a moment.
107 160
 
108
-* Set the entity ID of the Identity Provider:
161
+Set the entity ID of the Identity Provider (this is the same as the value you
162
+provided for ``--remote-id`` in `Identity Provider`):
109 163
 
110 164
 .. code-block:: xml
111 165
 
112 166
    <SSO entityID="https://samltest.id/saml/idp">
113 167
 
114
-* Remove the discoveryURL lines unless you want to enable advanced IdP discovery.
168
+Additionally, if you want to enable ECP (required for Keystone-to-Keystone),
169
+the SSO tag for this entity must also have the ECP flag set:
115 170
 
116
-* Tell Shibboleth where to find the metadata of the Identity Provider. You could
117
-  either tell it to fetch it from a URI or point it to a local file. For
118
-  example, pointing to a local file:
171
+
172
+.. code-block:: xml
173
+
174
+   <SSO entityID="https://samltest.id/saml/idp" ECP="true">
175
+
176
+Tell Shibboleth where to find the metadata of the Identity Provider. You could
177
+either tell it to fetch it from a URI or point it to a local file. For example,
178
+pointing to a local file:
119 179
 
120 180
 .. code-block:: xml
121 181
 
@@ -128,132 +188,47 @@ or pointing to a remote location:
128 188
    <MetadataProvider type="XML" url="https://samltest.id/saml/idp"
129 189
        backingFile="samltest-metadata.xml" />
130 190
 
131
-You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_
191
+When you are finished configuring ``shibboleth2.xml``, restart the ``shibd``
192
+daemon:
193
+
194
+.. code-block:: console
195
+
196
+   # systemctl restart shibd
132 197
 
133
-The result should look like (The example shown below is for reference only, not
134
-to be used in a production environment):
198
+Check the ``shibd`` logs in ``/var/log/shibboleth/shibd.log`` and
199
+``/var/log/shibboleth/shibd_warn.log`` for errors or warnings.
200
+
201
+Configure allowed attributes
202
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
203
+
204
+.. note::
205
+
206
+   For more information see the `attributes documentation
207
+   <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_
208
+
209
+By default, ``mod_shib`` does not pass all attributes received from the Identity
210
+Provider to keystone. If your Identity Provider does not use attributes known to
211
+``shibd``, you must configure them. For example, `samltest.id` uses a custom UID
212
+attribute.  It is not discoverable in the Identity Provider metadata, but the
213
+attribute name and type is logged in the ``mod_shib`` logs when an
214
+authentication attempt is made. To allow the attribute, add it to
215
+``/etc/shibboleth/attribute-map.xml``:
135 216
 
136 217
 .. code-block:: xml
137 218
 
138
-   <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
139
-       xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
140
-       xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
141
-       xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
142
-       xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
143
-       clockSkew="180">
144
-
145
-       <!--
146
-       By default, in-memory StorageService, ReplayCache, ArtifactMap, and SessionCache
147
-       are used. See example-shibboleth2.xml for samples of explicitly configuring them.
148
-       -->
149
-
150
-       <!--
151
-       To customize behavior for specific resources on Apache, and to link vhosts or
152
-       resources to ApplicationOverride settings below, use web server options/commands.
153
-       See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfigurationElements for help.
154
-
155
-       For examples with the RequestMap XML syntax instead, see the example-shibboleth2.xml
156
-       file, and the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHowTo topic.
157
-       -->
158
-
159
-       <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
160
-       <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth">
161
-
162
-           <!--
163
-           Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
164
-           You MUST supply an effectively unique handlerURL value for each of your applications.
165
-           The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
166
-           a relative value based on the virtual host. Using handlerSSL="true", the default, will force
167
-           the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
168
-           Note that while we default checkAddress to "false", this has a negative impact on the
169
-           security of your site. Stealing sessions via cookie theft is much easier with this disabled.
170
-           -->
171
-           <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
172
-                     checkAddress="false" handlerSSL="false" cookieProps="http">
173
-
174
-               <!--
175
-               Configures SSO for a default IdP. To allow for >1 IdP, remove
176
-               entityID property and adjust discoveryURL to point to discovery service.
177
-               (Set discoveryProtocol to "WAYF" for legacy Shibboleth WAYF support.)
178
-               You can also override entityID on /Login query string, or in RequestMap/htaccess.
179
-               -->
180
-               <SSO entityID="https://samltest.id/saml/idp">
181
-                 SAML2 SAML1
182
-               </SSO>
183
-
184
-               <!-- SAML and local-only logout. -->
185
-               <Logout>SAML2 Local</Logout>
186
-
187
-               <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
188
-               <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
189
-
190
-               <!-- Status reporting service. -->
191
-               <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
192
-
193
-               <!-- Session diagnostic service. -->
194
-               <Handler type="Session" Location="/Session" showAttributeValues="false"/>
195
-
196
-               <!-- JSON feed of discovery information. -->
197
-               <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
198
-           </Sessions>
199
-           <!--
200
-           Allows overriding of error template information/filenames. You can
201
-           also add attributes with values that can be plugged into the templates.
202
-           -->
203
-           <Errors supportContact="root@localhost"
204
-               helpLocation="/about.html"
205
-               styleSheet="/shibboleth-sp/main.css"/>
206
-
207
-           <!-- Example of remotely supplied batch of signed metadata. -->
208
-           <!--
209
-           <MetadataProvider type="XML" uri="http://federation.org/federation-metadata.xml"
210
-                 backingFilePath="federation-metadata.xml" reloadInterval="7200">
211
-               <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
212
-               <MetadataFilter type="Signature" certificate="fedsigner.pem"/>
213
-           </MetadataProvider>
214
-           -->
215
-
216
-           <!-- Example of locally maintained metadata. -->
217
-           <!--
218
-           <MetadataProvider type="XML" file="partner-metadata.xml"/>
219
-           -->
220
-           <MetadataProvider type="XML" uri="https://samltest.id/saml/idp"/>
221
-
222
-           <!-- Map to extract attributes from SAML assertions. -->
223
-           <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
224
-
225
-           <!-- Use a SAML query if no attributes are supplied during SSO. -->
226
-           <AttributeResolver type="Query" subjectMatch="true"/>
227
-
228
-           <!-- Default filtering policy for recognized attributes, lets other data pass. -->
229
-           <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
230
-
231
-           <!-- Simple file-based resolver for using a single keypair. -->
232
-           <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
233
-
234
-           <!--
235
-           The default settings can be overridden by creating ApplicationOverride elements (see
236
-           the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApplicationOverride topic).
237
-           Resource requests are mapped by web server commands, or the RequestMapper, to an
238
-           applicationId setting.
239
-           Example of a second application (for a second vhost) that has a different entityID.
240
-           Resources on the vhost would map to an applicationId of "admin":
241
-           -->
242
-           <!--
243
-           <ApplicationOverride id="admin" entityID="https://admin.example.org/shibboleth"/>
244
-           -->
245
-       </ApplicationDefaults>
246
-
247
-       <!-- Policies that determine how to process and authenticate runtime messages. -->
248
-       <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
249
-
250
-       <!-- Low-level configuration about protocols and bindings available for use. -->
251
-       <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
252
-
253
-   </SPConfig>
254
-
255
-If keystone is your IdP, you will need to examine your attributes map file
256
-``/etc/shibboleth/attribute-map.xml`` and add the following attributes:
219
+   <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid" />
220
+
221
+You may also want to use that attribute as a value for the ``REMOTE_USER``
222
+variable, which will make the ``REMOTE_USER`` variable usable as a parameter to
223
+your mapping rules. To do so, add it to ``/etc/shibboleth/shibboleth2.xml``:
224
+
225
+.. code-block:: xml
226
+
227
+   <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
228
+       REMOTE_USER="uid">
229
+
230
+Similarly, if using keystone as your Identity Provider, several custom
231
+attributes will be needed in ``/etc/shibboleth/attribute-map.xml``:
257 232
 
258 233
 .. code-block:: xml
259 234
 
@@ -263,25 +238,36 @@ If keystone is your IdP, you will need to examine your attributes map file
263 238
    <Attribute name="openstack_user_domain" id="openstack_user_domain"/>
264 239
    <Attribute name="openstack_project_domain" id="openstack_project_domain"/>
265 240
 
266
-For more information see the
267
-`attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_
241
+And update the ``REMOTE_USER`` variable in ``/etc/shibboleth/shibboleth2.xml``
242
+if desired:
243
+
244
+.. code-block:: xml
245
+
246
+   <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
247
+       REMOTE_USER="openstack_user">
268 248
 
269
-Once you are done, restart your Shibboleth daemon and apache:
249
+Restart the ``shibd`` daemon after making these changes:
270 250
 
271 251
 .. code-block:: console
272 252
 
273
-   # service shibd restart
274
-   # service apache2 restart
253
+   # systemctl restart shibd
275 254
 
276
-Check ``/var/log/shibboleth/shibd_warn.log`` for any ERROR or CRIT notices and
277
-correct them.
255
+Exchange Metadata
256
+~~~~~~~~~~~~~~~~~
278 257
 
279
-Upload your Service Provider's metadata file to your Identity Provider. You can
280
-fetch it with:
258
+Once configured, the Service Provider metadata is available to download:
281 259
 
282 260
 .. code-block:: console
283 261
 
284 262
    # wget https://sp.keystone.example.org/Shibboleth.sso/Metadata
285 263
 
286
-This step depends on your Identity Provider choice and is not covered here.
287
-If keystone is your Identity Provider you do not need to upload this file.
264
+Upload your Service Provider's metadata to your Identity Provider. This step
265
+depends on your Identity Provider choice and is not covered here. If keystone
266
+is your Identity Provider you do not need to upload this file.
267
+
268
+Continue configuring keystone
269
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
270
+
271
+`Continue configuring keystone`_
272
+
273
+.. _Continue configuring keystone: configure_federation.html#configuring-keystone

Loading…
Cancel
Save