Browse Source

Merge "Enhance the shibboleth guide"

tags/15.0.0.0rc1
Zuul 5 months ago
parent
commit
01b964955a

+ 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