summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2019-01-09 03:16:17 +0000
committerGerrit Code Review <review@openstack.org>2019-01-09 03:16:17 +0000
commit01b964955ac4e5369cc36bfe387329b82338e820 (patch)
treebdb8873da7b6c8446db6b38879ac3f540356f81d
parente34a6cf73dff13f4df6b70bac8d33b81c1475955 (diff)
parent83c37f4a943e8e7181f2f6f973b82885f598e010 (diff)
Merge "Enhance the shibboleth guide"
-rw-r--r--doc/source/admin/federation/configure_federation.rst2
-rw-r--r--doc/source/admin/federation/shibboleth.rst348
2 files changed, 169 insertions, 181 deletions
diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst
index 407d1df..53d3441 100644
--- a/doc/source/admin/federation/configure_federation.rst
+++ b/doc/source/admin/federation/configure_federation.rst
@@ -14,6 +14,8 @@
14Configuring Keystone for Federation 14Configuring Keystone for Federation
15=================================== 15===================================
16 16
17.. _keystone-as-sp:
18
17----------------------------------- 19-----------------------------------
18Keystone as a Service Provider (SP) 20Keystone as a Service Provider (SP)
19----------------------------------- 21-----------------------------------
diff --git a/doc/source/admin/federation/shibboleth.rst b/doc/source/admin/federation/shibboleth.rst
index a846159..96e1a72 100644
--- a/doc/source/admin/federation/shibboleth.rst
+++ b/doc/source/admin/federation/shibboleth.rst
@@ -11,12 +11,28 @@
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 Shibboleth 15Setting up Shibboleth
16---------------- 16---------------------
17 17
18Configure Apache HTTPD for mod_shibboleth 18See :ref:`keystone-as-sp` before proceeding with these Shibboleth-specific
19----------------------------------------- 19instructions.
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
27Configuring 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
21Configure keystone under Apache, following the steps in the install guide for 37Configure keystone under Apache, following the steps in the install guide for
22`SUSE`_, `RedHat`_ or `Ubuntu`_. 38`SUSE`_, `RedHat`_ or `Ubuntu`_.
@@ -25,21 +41,22 @@ Configure keystone under Apache, following the steps in the install guide for
25.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server 41.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
26.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server 42.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
27 43
28You'll also need to install `Shibboleth <https://wiki.shibboleth.net/confluence/display/SHIB2/Home>`_, for 44Install the Module
29example: 45~~~~~~~~~~~~~~~~~~
46
47Install the Apache module package. For example, on Ubuntu:
30 48
31.. code-block:: console 49.. code-block:: console
32 50
33 # apt-get install libapache2-mod-shib2 51 # apt-get install libapache2-mod-shib2
34 52
35Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: 53The package and module name will differ between distributions.
36
37Add this *WSGIScriptAliasMatch* directive to your public vhost configuration::
38 54
39 WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /usr/local/bin/keystone-wsgi-public/$1 55Configure Protected Endpoints
56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40 57
41Make sure the keystone Apache virtual host configuration contains a *<Location>* directive for the 58In the Apache configuration for the keystone VirtualHost, set an additional
42Shibboleth module and a *<Location>* directive for each identity provider 59``<Location>`` which is not part of keystone's API:
43 60
44.. code-block:: apache 61.. code-block:: apache
45 62
@@ -47,75 +64,118 @@ Shibboleth module and a *<Location>* directive for each identity provider
47 SetHandler shib 64 SetHandler shib
48 </Location> 65 </Location>
49 66
67If 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
69endpoint from it:
70
71.. code-block:: apache
72
73 Proxypass Shibboleth.sso !
74
75Configure each protected path to use the ``shibboleth`` AuthType:
76
77.. code-block:: apache
78
50 <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth> 79 <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
80 Require valid-user
81 AuthType shibboleth
51 ShibRequestSetting requireSession 1 82 ShibRequestSetting requireSession 1
83 ShibExportAssertion off
84 <IfVersion < 2.4>
85 ShibRequireSession On
86 ShibRequireAll On
87 </IfVersion>
88 </Location>
89
90Do the same for the WebSSO auth paths if using horizon as a single sign-on
91frontend:
92
93.. code-block:: apache
94
95 <Location /v3/auth/OS-FEDERATION/websso/saml2>
96 Require valid-user
52 AuthType shibboleth 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 Require valid-user 106 Require valid-user
55 107 AuthType shibboleth
108 ShibRequestSetting requireSession 1
109 ShibExportAssertion off
56 <IfVersion < 2.4> 110 <IfVersion < 2.4>
57 ShibRequireSession On 111 ShibRequireSession On
58 ShibRequireAll On 112 ShibRequireAll On
59 </IfVersion> 113 </IfVersion>
60 </Location> 114 </Location>
61 115
62.. NOTE:: 116Remember to reload Apache after altering the VirtualHost:
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
71Enable the ``shib2`` module, for example:
72 117
73.. code-block:: console 118.. code-block:: console
74 119
75 # a2enmod shib2 120 # systemctl reload apache2
76
77Restart Apache, for example:
78 121
79.. code-block:: console 122Configuring mod_shib
123--------------------
80 124
81 # service apache2 restart 125.. note::
82 126
83Configuring shibboleth2.xml 127 You are advised to examine `Shibboleth Service Provider Configuration
84--------------------------- 128 documentation
129 <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_
85 130
86Once you have your Keystone vhost (virtual host) ready, it's then time to 131Generate a keypair
87configure Shibboleth and upload your Metadata to the Identity Provider. 132~~~~~~~~~~~~~~~~~~
88 133
89Create a new keypair for Shibboleth with: 134For all SAML Service Providers, a PKI key pair must be generated and exchanged
135with the Identity Provider. The ``mod_shib`` package on the Ubuntu distribution
136provides a utility to generate the key pair:
90 137
91.. code-block:: console 138.. code-block:: console
92 139
93 # shib-keygen -y <number of years> 140 # shib-keygen -y <number of years>
94 141
95The newly created key file will be stored under ``/etc/shibboleth/sp-key.pem``. 142which will generate a key pair under ``/etc/shibboleth``. In other cases, the
143package might generate the key pair automatically upon installation.
96 144
97Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml`` 145Configure metadata
98file. You will want to change five settings: 146~~~~~~~~~~~~~~~~~~
99 147
100* Set the SP entity ID. This value usually has the form of a URI but it does not 148``mod_shib`` also has its own configuration file at
101 have to resolve to anything. It must uniquely identify your Service Provider 149``/etc/shibboleth/shibboleth2.xml`` that must be altered, as well
102 to your Identity Provider. 150as its own daemon. First, give the Service Provider an entity ID. This is a URN
151that you choose that must be globally unique to the Identity Provider:
103 152
104.. code-block:: xml 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
158Depending on your Identity Provider, you may also want to change the REMOTE_USER
159setting, more on that in a moment.
107 160
108* Set the entity ID of the Identity Provider: 161Set the entity ID of the Identity Provider (this is the same as the value you
162provided for ``--remote-id`` in `Identity Provider`):
109 163
110.. code-block:: xml 164.. code-block:: xml
111 165
112 <SSO entityID="https://samltest.id/saml/idp"> 166 <SSO entityID="https://samltest.id/saml/idp">
113 167
114* Remove the discoveryURL lines unless you want to enable advanced IdP discovery. 168Additionally, if you want to enable ECP (required for Keystone-to-Keystone),
169the 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 171
117 either tell it to fetch it from a URI or point it to a local file. For 172.. code-block:: xml
118 example, pointing to a local file: 173
174 <SSO entityID="https://samltest.id/saml/idp" ECP="true">
175
176Tell Shibboleth where to find the metadata of the Identity Provider. You could
177either tell it to fetch it from a URI or point it to a local file. For example,
178pointing to a local file:
119 179
120.. code-block:: xml 180.. code-block:: xml
121 181
@@ -128,132 +188,47 @@ or pointing to a remote location:
128 <MetadataProvider type="XML" url="https://samltest.id/saml/idp" 188 <MetadataProvider type="XML" url="https://samltest.id/saml/idp"
129 backingFile="samltest-metadata.xml" /> 189 backingFile="samltest-metadata.xml" />
130 190
131You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_ 191When you are finished configuring ``shibboleth2.xml``, restart the ``shibd``
192daemon:
193
194.. code-block:: console
195
196 # systemctl restart shibd
132 197
133The result should look like (The example shown below is for reference only, not 198Check the ``shibd`` logs in ``/var/log/shibboleth/shibd.log`` and
134to be used in a production environment): 199``/var/log/shibboleth/shibd_warn.log`` for errors or warnings.
200
201Configure 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
209By default, ``mod_shib`` does not pass all attributes received from the Identity
210Provider 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
212attribute. It is not discoverable in the Identity Provider metadata, but the
213attribute name and type is logged in the ``mod_shib`` logs when an
214authentication attempt is made. To allow the attribute, add it to
215``/etc/shibboleth/attribute-map.xml``:
135 216
136.. code-block:: xml 217.. code-block:: xml
137 218
138 <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config" 219 <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid" />
139 xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config" 220
140 xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 221You may also want to use that attribute as a value for the ``REMOTE_USER``
141 xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 222variable, which will make the ``REMOTE_USER`` variable usable as a parameter to
142 xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" 223your mapping rules. To do so, add it to ``/etc/shibboleth/shibboleth2.xml``:
143 clockSkew="180"> 224
144 225.. code-block:: xml
145 <!-- 226
146 By default, in-memory StorageService, ReplayCache, ArtifactMap, and SessionCache 227 <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
147 are used. See example-shibboleth2.xml for samples of explicitly configuring them. 228 REMOTE_USER="uid">
148 --> 229
149 230Similarly, if using keystone as your Identity Provider, several custom
150 <!-- 231attributes will be needed in ``/etc/shibboleth/attribute-map.xml``:
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
255If keystone is your IdP, you will need to examine your attributes map file
256``/etc/shibboleth/attribute-map.xml`` and add the following attributes:
257 232
258.. code-block:: xml 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 <Attribute name="openstack_user_domain" id="openstack_user_domain"/> 238 <Attribute name="openstack_user_domain" id="openstack_user_domain"/>
264 <Attribute name="openstack_project_domain" id="openstack_project_domain"/> 239 <Attribute name="openstack_project_domain" id="openstack_project_domain"/>
265 240
266For more information see the 241And update the ``REMOTE_USER`` variable in ``/etc/shibboleth/shibboleth2.xml``
267`attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_ 242if desired:
243
244.. code-block:: xml
245
246 <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth"
247 REMOTE_USER="openstack_user">
268 248
269Once you are done, restart your Shibboleth daemon and apache: 249Restart the ``shibd`` daemon after making these changes:
270 250
271.. code-block:: console 251.. code-block:: console
272 252
273 # service shibd restart 253 # systemctl restart shibd
274 # service apache2 restart
275 254
276Check ``/var/log/shibboleth/shibd_warn.log`` for any ERROR or CRIT notices and 255Exchange Metadata
277correct them. 256~~~~~~~~~~~~~~~~~
278 257
279Upload your Service Provider's metadata file to your Identity Provider. You can 258Once configured, the Service Provider metadata is available to download:
280fetch it with:
281 259
282.. code-block:: console 260.. code-block:: console
283 261
284 # wget https://sp.keystone.example.org/Shibboleth.sso/Metadata 262 # wget https://sp.keystone.example.org/Shibboleth.sso/Metadata
285 263
286This step depends on your Identity Provider choice and is not covered here. 264Upload your Service Provider's metadata to your Identity Provider. This step
287If keystone is your Identity Provider you do not need to upload this file. 265depends on your Identity Provider choice and is not covered here. If keystone
266is your Identity Provider you do not need to upload this file.
267
268Continue configuring keystone
269~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
270
271`Continue configuring keystone`_
272
273.. _Continue configuring keystone: configure_federation.html#configuring-keystone